com.sas.iom
Class WorkspaceFactory

java.lang.Object
  |
  +--com.sas.iom.WorkspaceFactory

public class WorkspaceFactory

extends java.lang.Object

implements java.io.Serializable

WorkspaceFactory provides a factory for creating and connecting to a remote object on an IOM Server that implements com.sas.iom.SAS.IWorkspace. Information necessary to create a connection can be read out of a JNDI repository (such as LDAP), or it may be provided directly by the caller. The necessary information may be associated with an instance of the factory at the time the factory is instantiated, or it may be provided on a per-method-call basis. If the connection information is provided at the time the factory is instantiated, the factory will provide connection pooling.

If connection pooling is used, then this factory will maintain a configurable number of active connections spread across one or more similar servers. When a caller accesses the factory to request a connection to a workspace object, the factory will allocate a connection from the pool if one is available. Otherwise, the factory will create a new connection for the caller. A connection pool has a configurable maximum service limit. If a caller accesses a factory to request a connection to a workspace object, and the factory has reached its maximum service limit, then the factory will not create a new connection, and it will either throw an exception or it will delay service of the request until another factory caller releases a connection and returns it to the pool.

Connection pooling requires a two-tiered security model because the factory will need to create connections before the ultimate users of the connections can present credentials that authorize them to use the connections. The two security roles that correspond to each tier are called pool administrator and pool user. The administrator is responsible for instantiating the factory and, thus, starting the pool. The user must establish that it is authorized to use connections from the factory before it can call a method on the factory to obtain a connection. If the administrator directly provided the factory with its pooling information upon instantiation, then authorization is granted to any user that merely holds an object reference for the factory. The factory is serializable to allow the administrator to control access to the factory by storing it in a protected repository.

If the information necessary to start and run the connection pool came from a JNDI respository, then additional security requirements may be placed on the administrator and the user. To successfully instantiate a factory that reads connection information from a JNDI repository, the administrator must provide JNDI credentials that authorize it to read the appropriate server definitions and login definitions in the repository. To successfully obtain a connection from the factory, a user must provide JNDI credentials that are listed in the value of the sasAllowedClientDN attribute of the appropriate login definition. The administrator has the option of making this user authorization step unnecessary.

If the factory tries to connect to a server in the pool and fails to connect, the factory will remove the server from the pool and will not attempt to make any further connections to that server.

See Also:

Serialized Form

Constructor Summary

WorkspaceFactory()
NON-POOLING CONSTRUCTOR - constructs a factory that creates a new connection each time createWorkspaceByLogicalName() or createWorkspaceByServer() is called.

WorkspaceFactory(java.lang.Object jndiInformation, java.lang.String baseDN, java.lang.String logicalName, boolean userAuthorizationRequired, boolean adminAuthorizationRequired, java.io.PrintWriter logWriter)
JNDI POOLING CONSTRUCTOR - constructs a factory that reads the information necessary to create a pool of live connections to remote workspace objects from a JNDI repository.

WorkspaceFactory(java.util.Properties[] connectionDescriptors, java.util.Properties poolParameters, java.io.PrintWriter logWriter)
AD HOC POOLING CONSTRUCTOR - constructs a factory that uses the provided information to create a pool of live connections to remote workspace objects.

Method Summary

com.sas.iom.SAS.IWorkspace	createWorkspaceByLogicalName(java.lang.String logicalName, java.lang.String sasReferenceDN, java.lang.String protocol, java.lang.String ldapProviderUrl, java.util.Properties ldapProperties) Creates a new connection to a workspace object using LDAP information.
com.sas.iom.SAS.IWorkspace	createWorkspaceByServer(java.util.Properties serverInfo) Creates a new IWorkspace object based on Server definitions.
void	destroy() Immediately disconnects all live connections to remote workspace object including allocated connections and connections in progress.
void	destroy(java.lang.String adminDN, java.lang.String adminPassword) Immediately disconnects all live connections to remote workspace object including allocated connections and connections in progress.
boolean	equals(java.lang.Object that) Compares an object with this factory for equality.
static WorkspaceFactory	getFactory(java.util.Hashtable repositoryProperties, java.lang.String baseDN, java.lang.String logicalName) Searches for a factory that any user can use to obtain a connection to a server described in the JNDI repository identified by repositoryProperties under the given base DN and logical name.
static WorkspaceFactory	getFactory(java.lang.String userDN, java.lang.String userPassword, java.util.Hashtable repositoryProperties, java.lang.String baseDN, java.lang.String logicalName) Searches for a factory that the given user can use to obtain a connection to a server described in the JNDI repository identified by repositoryProperties under the given base DN and logical name.
java.util.Properties[]	getServersByLogicalName(java.lang.String logicalName, java.lang.String protocol, java.lang.String ldapProviderUrl, java.util.Properties ldapProperties) Gets a list of server definitions matching the logicalName.
WorkspaceConnector	getWorkspaceConnector(long waitMilliseconds) Allocates a connection from an ad hoc pool or a JNDI pool with user authorization turned off.
WorkspaceConnector	getWorkspaceConnector(java.lang.String userDN, java.lang.String userPassword, long waitMilliseconds) Allocates a connection from a JNDI pool with user authorization turned on.
static WorkspaceConnector	getWorkspaceConnectorByUUID(java.lang.String uuid) Returns a reference to a previously created workspace connector that encapsulates a workspace object with the given UUID.
static WorkspaceConnector	getWorkspaceConnectorByUUID(java.lang.String userDN, java.lang.String userPassword, java.lang.String uuid) Returns a reference to a previously created workspace connector that encapsulates a workspace object with the given UUID.
void	shutdown() Disconnects all unallocated live connections to remote workspace objects.
void	shutdown(java.lang.String adminDN, java.lang.String adminPassword) Disconnects all unallocated live connections to remote workspace objects.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WorkspaceFactory

public WorkspaceFactory(java.lang.Object jndiInformation,
                        java.lang.String baseDN,
                        java.lang.String logicalName,
                        boolean userAuthorizationRequired,
                        boolean adminAuthorizationRequired,
                        java.io.PrintWriter logWriter)
                 throws WorkspaceFactoryException

JNDI POOLING CONSTRUCTOR - constructs a factory that reads the information necessary to create a pool of live connections to remote workspace objects from a JNDI repository. The connections can then be accessed quickly using this factory's getWorkspaceConnector() methods. The caller of this constructor must either provide JNDI credentials that allow read access to the server definitions and login definitions in the repository or it must provide an existing instance of javax.naming.directory.DirContext. The caller may configure this factory such that further access through the getWorkspaceConnector(), shutdown(), and destroy() methods also require authorization against the JNDI repository.

Parameters:

jndiInformation - an instance of either java.util.Hashtable or javax.naming.directory.DirContext. If a java.util.Hashtable object, then it is a table of values that can be used to initialize a javax.naming.directory,DirContext object. The information in the table identifies the JNDI repository that contains the values necessary to start a connection pool and provides the distinguished name and password of an entity that has read access to that information. The keys for the values are defined in javax.naming.Context, and the required keys are listed below.

• javax.naming.Context.INITIAL_CONTEXT_FACTORY
• javax.naming.Context.PROVIDER_URL
• javax.naming.Context.SECURITY_AUTHENTICATION
• javax.naming.Context.SECURITY_PRINCIPAL
• javax.naming.Context.SECURITY_CREDENTIALS

If jndiInformation is not an instance of java.util.Hashtable, then it must be an existing instance of javax.naming.directory.DirContext that can be used as described above.

baseDN - a partial JNDI distinguished name that defines the section within the repository naming hierarchy that contains the pooling information.

logicalName - the value of the sasLogicalName attribute for all login definitions and server definitions (relative to the baseDN) in the JNDI repository that contain information for this factory.

userAuthorizationRequired - true if user access to this factory through the getWorkspaceConnector() method should require authorization against the JNDI repository.

adminAuthorizationRequired - true if administative access to this factory through the shutdown() and destroy() methods should require authorization against the credentials used to construct this factory.

logWriter - a print stream to write log messages to. If null, then no log message will be written.

Throws:

WorkspaceFactoryException - if the administrator credentials are invalid, the pooling information is incomplete, or a connection to a server fails.

WorkspaceFactory

public WorkspaceFactory(java.util.Properties[] connectionDescriptors,
                        java.util.Properties poolParameters,
                        java.io.PrintWriter logWriter)
                 throws WorkspaceFactoryException

AD HOC POOLING CONSTRUCTOR - constructs a factory that uses the provided information to create a pool of live connections to remote workspace objects. The connections can then be accessed quickly using this factory's getWorkspaceConnector() methods. Access to this factory through the getWorkspaceConnector(), shutdown(), and destroy() methods do not require further authorization so the caller of this constructor should take care to properly control access to the factory. The factory is serializable to allow the caller to control access to the factory by storing it in a protected repository.

Parameters:

connectionDescriptors - an array of tables that describe how to connect to the servers that participate in the connection pool. The required values for each table are listed below.

host

The IP name or address of the machine to connect to

port

The TCP port number to connect to

userName

a user name defined on the host machine

password

the password for userName

The optional values for each table are listed below.

encryptionPolicy

none, optional, or required. The default value is none. If the specified value is not none, then the client and server will attempt to agree upon an encryption algorithm and what should be encrypted. If that negotiation fails and the value is required, then the connection will fail. If the value is optional, then the connection will continue with no encryption unless the server is configured to require encryption. In that case, the connection will fail.

encryptionAlgorithms

a comma-separated list of encryption algorithms that the client would like to use to secure this connection in order of preference. Possible values are sasproprietary, rc2, rc4, des, and tripledes. To use any algorithm other than sasproprietary, SAS/SECURE software must be installed on both the client and server. Furthermore, use of des, and tripledes may be restricted outside the USA due to export law. The connection will use the first algorithm on this list that is also supported by the server. If no value is specified, the connection will use the first value suggested by the server that the client is capable of supporting.

encryptionContent

specifies which messages between the client and server should be encrypted if encryption is used. Possible values are all (the default; encrypt all messages) and authentication (encrypt only message that contain user name and password information). The default is all. If the server requires a higher level of encryption than is specified by this value, the connection will fail.

sasMaxPerWorkspacePool

the maximum number of connections this factory should have to this server at any given time. If no value is specified, then the number of connections will be limited only by the physical capacity of the server.

sas-RecycleActivationLimit

the maximum number of times a connection can be reused before it is disconnected (and reconnected if necessary). The value must be greater than or equal to 0. If the value is 0, then the connection can be reused any number of times. The default value is 0.

sas-ServerRunForever

The value must be either true or false. If the value is false, then unallocated live connections will be disconnected after a period of time (determined by the value of sas-ServerShutdownAfter) unless they are allocated to a user before that period of time passes. Otherwise, unallocated live connections will remain alive indefinitely. The default value is true.

sas-ServerShutdownAfter

The period of time, in minutes, that an unallocated live connection will remain alive waiting to be allocated to a user. This attribute is ignored if the value of sas-ServerRunForever is true. The value must not be less than 0, and it must not be greater than 1440 (the number of minutes in a day). The default value is 3. If the value is 0, then a connection returned to a pool by a user will be disconnected immediately unless another user is waiting for a connection from the pool.

poolParameters - a table of values that describe how the connection pool should behave. Possible values are listed below. All values are optional. This parameter may be null if the default is desired for all values.

sasMinSize

The minimum number of live connections that must be associated with this factory at any given time unless the factory has been shut down or destroyed. This number includes both connections that have been allocated to users and unallocated connections. The default value is 0.

sasMinAvail

The minimum number of unallocated live connections that must be associated with this factory at any given time unless the factory has been shut down or destroyed. The default value is 0.

logWriter - a print stream to write log messages to. If null, then no log message will be written.

Throws:

WorkspaceFactoryException - if a connection descriptor or login descriptor is invalid or if a connection to a server fails

WorkspaceFactory

public WorkspaceFactory()

NON-POOLING CONSTRUCTOR - constructs a factory that creates a new connection each time createWorkspaceByLogicalName() or createWorkspaceByServer() is called. An internal ORB is constructed to broker requests for the connections. This ORB can be shut down by calling destroy().

Method Detail

equals

public boolean equals(java.lang.Object that)

Compares an object with this factory for equality. Two non-pooling factories are considered equal only if they are the same object (i.e. their object references are equal).

Overrides:

equals in class java.lang.Object

Parameters:

that - the object to compare with this object.

Returns:

true if this object is equal to that object.

getFactory

public static WorkspaceFactory getFactory(java.util.Hashtable repositoryProperties,
                                          java.lang.String baseDN,
                                          java.lang.String logicalName)

Searches for a factory that any user can use to obtain a connection to a server described in the JNDI repository identified by repositoryProperties under the given base DN and logical name. If such a factory has not been created yet, then this method returns null.

Parameters:

repositoryProperties - The information in the table identifies the JNDI repository that contains the values necessary to start a connection pool. The keys for the values are defined in javax.naming.Context, and the required keys are listed below.

• javax.naming.Context.INITIAL_CONTEXT_FACTORY
• javax.naming.Context.PROVIDER_URL

Other values that are not required but are significant when searching are

• javax.naming.Context.DNS_URL
• javax.naming.Context.OBJECT_FACTORIES
• javax.naming.Context.URL_PKG_PREFIXES

Values that describe a user identity for security purposes including javax.naming.Context.SECURITY_AUTHENTICATION, javax.naming.Context.SECURITY_PRINCIPAL, and javax.naming.Context.SECURITY_CREDENTIALS, are not necessary because this method only searches for factories that all users can use.

baseDN - a partial JNDI distinguished name that defines the section within the repository naming hierarchy that contains the pooling information.

logicalName - the value of the sasLogicalName attribute for all login definitions and server definitions (relative to the baseDN) in the JNDI repository that contain information for starting a connection pool.

getFactory

public static WorkspaceFactory getFactory(java.lang.String userDN,
                                          java.lang.String userPassword,
                                          java.util.Hashtable repositoryProperties,
                                          java.lang.String baseDN,
                                          java.lang.String logicalName)

Searches for a factory that the given user can use to obtain a connection to a server described in the JNDI repository identified by repositoryProperties under the given base DN and logical name. If such a factory has not been created yet, then this method returns null.

Parameters:

userDN - the distinguished name of some object in the given JNDI directory that has a userPassword attribute. If this method finds a factory that meets all the other search criteria specified in the arguments, and that factory has set userAuthorizationRequired to true, then This object's DN must be a value of (or be a member of a group whose DN is a value of) the sasAllowedClientDN attribute of one of the login definitions used to create that factory. If the factory does not require user authorization, then this parameter is ignored.

userPassword - the value of the userPassword attribute for the object identified with userDN. This value may be in plain text or it may be base64 encoded. If it is base64 encoded, it must begin with the tag {base64}.

repositoryProperties - The information in the table identifies the JNDI repository that contains the values necessary to start a connection pool. The keys for the values are defined in javax.naming.Context, and the required keys are listed below.

• javax.naming.Context.INITIAL_CONTEXT_FACTORY
• javax.naming.Context.PROVIDER_URL

Other values that are not required but are significant when searching are

• javax.naming.Context.DNS_URL
• javax.naming.Context.OBJECT_FACTORIES
• javax.naming.Context.URL_PKG_PREFIXES

Values that describe a user identity for security purposes including javax.naming.Context.SECURITY_AUTHENTICATION, javax.naming.Context.SECURITY_PRINCIPAL, and javax.naming.Context.SECURITY_CREDENTIALS, are not necessary because security information is provided with the userDN and userPassword parameters.

baseDN - a partial JNDI distinguished name that defines the section within the repository naming hierarchy that contains the pooling information.

logicalName - the value of the sasLogicalName attribute for all login definitions and server definitions (relative to the baseDN) in the JNDI repository that contain information for starting a connection pool.

getWorkspaceConnector

public WorkspaceConnector getWorkspaceConnector(long waitMilliseconds)
                                         throws WorkspaceFactoryException

Allocates a connection from an ad hoc pool or a JNDI pool with user authorization turned off. If all live connections in the pool have been allocated to other users, then this factory will create a new connection for this user. If this factory requires user authorization through JNDI, then this method will throw an exception. If an administrator has shut down or destroyed this factory, then this method will throw an exception.

Parameters:

waitMilliseconds - used if this factory has reached its maximum use limit at the time of this method call. If that is the case, then this method will behave in one of the three following ways based on the value of waitMilliseconds:

greater than zero

this method will wait up to N milliseconds for factory usage to fall below the limit (where N is the value of waitMilliseconds) before either returning a workspace connector or throwing an exception.

zero

this method will wait indefinitely for factory usage to fall below the maximum usage limit, and will return a workspace connector once it does.

less than zero

this method will throw an exception immediately.

Returns:

a connector to a workspace

Throws:

WorkspaceFactoryException - if this factory requires user authorization through JNDI, if the factory has been shut down or destroyed, if the factory has reached its maximum usage limit, or there is a problem creating new connections.

getWorkspaceConnector

public WorkspaceConnector getWorkspaceConnector(java.lang.String userDN,
                                                java.lang.String userPassword,
                                                long waitMilliseconds)
                                         throws WorkspaceFactoryException

Allocates a connection from a JNDI pool with user authorization turned on. User credentials will be authorized against the same JNDI repsoitory that was used to instantiate the factory. If the user does not have authority to use the factory, then this method will throw an exception. If all live connections in the pool have been allocated to other users, then this factory will create a new connection for this user. If an administrator has shut down or destroyed this factory, then this method will throw an exception.

Parameters:

userDN - the distinguished name of some object in the JNDI directory used to instantiate this factory that has a userPassword attribute. This object's DN must be a value of (or be a member of a group whose DN is a value of) the sasAllowedClientDN attribute of one of the login definitions used to create this factory. If this factory does not require user authorization, then this parameter is ignored.

userPassword - the value of the userPassword attribute for the object identified with userDN. This value may be in plain text or it may be base64 encoded. If it is base64 encoded, it must begin with the tag {base64}. If this factory does not require user authorization, then this parameter is ignored.

waitMilliseconds - used if this factory has reached its maximum use limit at the time of this method call. If that is the case, then this method will behave in one of the three following ways based on the value of waitMilliseconds:

greater than zero

this method will wait up to N milliseconds for factory usage to fall below the limit (where N is the value of waitMilliseconds) before either returning a workspace connector or throwing an exception.

zero

this method will wait indefinitely for factory usage to fall below the maximum usage limit, and will return a workspace connector once it does.

less than zero

this method will throw an exception immediately.

Returns:

a connector to a workspace

Throws:

WorkspaceFactoryException - if the user is not authorized to use this factory, if the factory has been shut down or destroyed, if the factory has reached its maximum usage limit, or there is a problem creating new connections.

getWorkspaceConnectorByUUID

public static WorkspaceConnector getWorkspaceConnectorByUUID(java.lang.String uuid)

Returns a reference to a previously created workspace connector that encapsulates a workspace object with the given UUID. The UUID for a workspace object can be found by calling its UniqueIdentifier() method. If no such workspace connector has been created, or if such a connector has been created but has already been closed, this method returns null.

Parameters:

uuid - the UUID of the desired workspace

Returns:

a reference to the workspace connector that encapsulates the desired workspace

getWorkspaceConnectorByUUID

public static WorkspaceConnector getWorkspaceConnectorByUUID(java.lang.String userDN,
                                                             java.lang.String userPassword,
                                                             java.lang.String uuid)
                                                      throws WorkspaceFactoryException

Returns a reference to a previously created workspace connector that encapsulates a workspace object with the given UUID. The UUID for a workspace object can be found by calling its UniqueIdentifier() method. If no such workspace connector has been created, or if such a connector has been created but has already been closed, this method returns null.

Parameters:

userDN - the distinguished name of some object in the given JNDI directory that has a userPassword attribute. If this method finds a factory that meets all the other search criteria specified in the arguments, and that factory has set userAuthorizationRequired to true, then This object's DN must be a value of (or be a member of a group whose DN is a value of) the sasAllowedClientDN attribute of one of the login definitions used to create that factory. If the factory does not require user authorization, then this parameter is ignored.

userPassword - the value of the userPassword attribute for the object identified with userDN. This value may be in plain text or it may be base64 encoded. If it is base64 encoded, it must begin with the tag {base64}.

uuid - the UUID of the desired workspace

Returns:

a reference to the workspace connector that encapsulates the desired workspace

Throws:

WorkspaceFactoryException - if the user is not authorized to use the desired workspace

createWorkspaceByLogicalName

public com.sas.iom.SAS.IWorkspace createWorkspaceByLogicalName(java.lang.String logicalName,
                                                               java.lang.String sasReferenceDN,
                                                               java.lang.String protocol,
                                                               java.lang.String ldapProviderUrl,
                                                               java.util.Properties ldapProperties)
                                                        throws WorkspaceFactoryException

Creates a new connection to a workspace object using LDAP information. Server definitions are located in the LDAP repository by searching (relative to baseDN) for sasServer objects that have the given logicalName as an attribute. Login definitions are located in the LDAP repository by searching (relative to baseDN) for sasLogin objects that have the given sasReferenceDN as an attribute. Each server definition is then paired with a login definition by matching objects with like values for the sasDomainName attribute.

This method throws an exception if it is called after a call to destroy().

Parameters:

logicalName - A valid logical name of the server.

sasReferenceDN - A reference DN for the user to match with the domain name to get a login definition.

protocol - Protocol to communicate with the server. Currently, the only valid value is bridge.

ldapProviderUrl - A url specifying the location of an LDAP provider. This value typically takes the form ldap://host:port

ldapProperties - A Properties object containing the following LDAP properties:

baseDN

Container that will contain all sasserver and saslogin definitions.

ldapUserName

DN of a user to use to connect to LDAP.

ldapPassword

Password that corresponds with ldapUserName.

authentication

LDAP authentication value. This is an optional field. The authentication values are NONE or SIMPLE.

Returns:

A workspace object.

Throws:

WorkspaceFactoryException - This exception is thrown if an error occurs.

createWorkspaceByServer

public com.sas.iom.SAS.IWorkspace createWorkspaceByServer(java.util.Properties serverInfo)
                                                   throws WorkspaceFactoryException

Creates a new IWorkspace object based on Server definitions.

This method throws an exception if it is called after a call to destroy().

Parameters:

serverInfo - A properties object containing the following server definitions and a valid username and password :

host

A comma delimited String of valid host names. This definition is required. This maps to machineDNSName in LDAP.

port

TCP/IP port String to connect with bridge. Do not specify this definition if you specify serviceName.

protocol

A valid protocol String to communicate with the SAS server (bridge or corba). If you do not specify a value

this property will be defaulted to "bridge".

userName

A valid username String for the MVA server.

password

The password String that corresponds to the username you specify with the userName property.

encryptionPolicy

whether or not JavaBridge should attempt to negotiate with the server over which encryption algorithm to use and what to do if the negotiations fail. Possible values:

none

do not use encryption. This is the default.

optional

attempt to use encryption but, if algorithm negotiation fails, continue with an unencrypted session

required

attempt to use encryption but, if algorithm negotiation fails, fail the connection

encryptionContent

specifies which messages should be encrypted if encryption is used. Possible values:

all

encrypt all messages. This is the default.

authentication

encrypt only messages that contain user name and password information.

encryptionAlgorithms

the list of algorithms you are willing to use in order of preference. Values in the list should be separated by commas and chosen from sasproprietary, rc2, rc4, des, or tripledes. If no value is specified, then one of the server's favorite algorithms will be used.

Note that the server's encryption policy is, by default, optional so no special action is needed to prepare an IOM BRIDGE server to use encryption. However, it is possible to set up the server so that encryption is required. Consult IOM BRIDGE server documentation for details.

name

Name of the server definition. This definition is optional.

description

A description of the server definition. This definition is optional.

transcodingPreference

This property controls where character data will be transcoded. There are two possible values:

client

Transcode character data on the client using Java character encoding converters to convert between Unicode and encoding appropriate for SAS specific locale.

server

Transcode character data on the server using SAS character encoding converters to convert betweeen some intermediate encoding (which both client and server is capable of converting to/from) and encoding appropriate for SAS specific locale. The client also trancodes character data using the Java character encoding converters to convert between the intermediate encoding (described above) and Unicode.

Note : The only time user sets the value to server is when he/she knows that the Java environment does not have a converter that converts between Unicode and the encoding appropriate for SAS specific locale.

The default value is client. If the Java environment is not capable of performing the required conversions, then the transcoding responsibilities will automatically be shifted to SAS.

Returns:

A workspace object.

Throws:

WorkspaceFactoryException - This exception is thrown if an error occurs.

getServersByLogicalName

public java.util.Properties[] getServersByLogicalName(java.lang.String logicalName,
                                                      java.lang.String protocol,
                                                      java.lang.String ldapProviderUrl,
                                                      java.util.Properties ldapProperties)
                                               throws WorkspaceFactoryException

Gets a list of server definitions matching the logicalName.

Parameters:

logicalName - A valid logical name of the server.

protocol - Protocol to communicate with the server. Valid values are bridge or corba.

ldapProviderUrl - A valid url specifying and LDAP server and its port to make connection of the form : "ldap://host:port".

ldapProperties - A Properties object containing the following LDAP properties :

baseDN

Container that will contain all sasserver and saslogin definitions.

ldapUserName

DN of a user to use to connect to LDAP.

ldapPassword

Password that corresponds with ldapUserName.

authentication

LDAP authentication value. This is an optional field. The authentication values are NONE or SIMPLE.

Returns:

An array of Properties object containing server definitions matching the logical name.

The properties returned contains the following server definitions.

host

A comma delimited String of valid host names. This definition is required. This maps to machineDNSName in LDAP.

port

TCP/IP port to connect with bridge.

protocol

Protocol to communicate with the SAS server. Valid values are bridge or corba.

name

Name of the server definition.

description

A description of the server definition.

Throws:

WorkspaceFactoryException - This exception is thrown if an error occurs.

shutdown

public void shutdown()
              throws WorkspaceFactoryException

Disconnects all unallocated live connections to remote workspace objects. Allocated connections and connections in progress are not immediately affected, but, as they are deallocated, the connections will be closed instead of returned to the pool. After this method has been called, all subsequent calls to shutdown() will do nothing, but calls getWorkspaceConnector() will result in an exception.

Throws:

WorkspaceFactoryException - if this factory requires administrators to request authorization to use this method.

shutdown

public void shutdown(java.lang.String adminDN,
                     java.lang.String adminPassword)
              throws WorkspaceFactoryException

Disconnects all unallocated live connections to remote workspace objects. Allocated connections and connections in progress are not immediately affected, but, as they are deallocated, the connections will be closed instead of returned to the pool. After this method has been called, all subsequent calls to shutdown() will do nothing, but calls getWorkspaceConnector() will result in an exception.

Parameters:

adminDN - the distinguished name of some object in the JNDI directory used to instantiate this factory that has a userPassword attribute. This object must have read access to the pool parameters object that was named when this factory was instantiated. If this factory does not require administrator authorization, then this parameter is ignored.

adminPassword - the value of the userPassword attribute for the object identified with adminDN. This value may be in plain text or it may be base64 encoded. If it is base64 encoded, it must begin with the tag {base64}. If this factory does not require administrator authorization, then this parameter is ignored.

Throws:

WorkspaceFactoryException - if the administrator credentials provided are invalid.

destroy

public void destroy()
             throws WorkspaceFactoryException

Immediately disconnects all live connections to remote workspace object including allocated connections and connections in progress. Any attempt to use a connection allocated from this factory after this method has been called will result in an exception. After this method has been called, all subsequent calls to shutdown() and destroy() will do nothing, but calls getWorkspaceConnector() will result in an exception.

Throws:

WorkspaceFactoryException - if this factory requires administrators to request authorization to use this method.

destroy

public void destroy(java.lang.String adminDN,
                    java.lang.String adminPassword)
             throws WorkspaceFactoryException

Immediately disconnects all live connections to remote workspace object including allocated connections and connections in progress. Any attempt to use a connection allocated from this factory after this method has been called will result in an exception. After this method has been called, all subsequent calls to shutdown() and destroy() will do nothing, but calls getWorkspaceConnector() will result in an exception.

Parameters:

adminDN - the distinguished name of some object in the JNDI directory used to instantiate this factory that has a userPassword attribute. This object must have read access to the pool parameters object that was named when this factory was instantiated. If this factory does not require administrator authorization, then this parameter is ignored.

adminPassword - the value of the userPassword attribute for the object identified with adminDN. This value may be in plain text or it may be base64 encoded. If it is base64 encoded, it must begin with the tag {base64}. If this factory does not require administrator authorization, then this parameter is ignored.

Throws:

WorkspaceFactoryException - if the administrator credentials provided are invalid.