| |
Here we present a list of many of the classes you need for a resource adapter setup, with descriptions of their purpose and whether they are part of the resource adapter or jboss.
ConnectionFactory (resource adapter). This is what your client program (or JAWS) uses to get the connections to do its work. The most familiar example is the javax.sql.DataSource, supplying db connections. The resource cci spec describes another sort of connection that provides a way to get at less standardized resource managers. The connections from the connection factory do not represent actual resource manager connections but rather short-lived handles to them to be used only briefly during actual resource access. "Closing" such a handle merely indicates you are done using it, not that the underlying connection to the resource should be disposed of. When a connection is requested, the ConnectionFactory simply asks the ConnectionManager for one.
ConnectionManager (jboss). The connection manager provides pooling functionality and makes sure connections are hooked up to the right transactions. It doesn't know anything about what kind of connections its dealing with, just how to pool them and hook up transactions. Now what it's actually pooling are ManagedConnections, which we'll get to in a minute. When it needs another one, it asks the ManagedConnectionFactory. When you ask for a connection, it finds or creates a managed connection and gets a connection handle from the managed connection to return to you. When it is looking for a ManagedConnection, it gets to use two criteria: ConnectionRequestInfo and Subject. The ConnectionRequestInfo comes from the ConnectionFactory, and contains resource adapter specific per-connection configuration information, such as client id or language. The connection manager does not know the internal structure of ConnectionRequestInfo, but passes it unchanged to the ManagedConnectionFactory. The subject comes from a PrincipalMapping, which may supply a "constant" user or may translate the principal information from the client context into a resource-adapter suitable subject. The ConnectionRequestInfo and Subject are parameters for creating a new ManagedConnection; if preexisting pooled connections are available, the ConnectionManager asks the ManagedConnectionFactory for a match based on the ConnectionRequestInfo and Subject from among the available ManagedConnections.
ManagedConnectionFactory (Resource adapter). The ManagedConnectionFactory actually creates and configures the actual connections to the resource manager we're doing all this work to get to. This is really the only part of the resource adapter you can configure at deployment time, telling it usually what resource instance (such as database) and possibly user and password to connect to. When the ConnectionManager needs another physical connection to use, it asks the ManagedConnectionFactory.
ManagedConnection. The ManagedConnection is the actual physical connection to the resource. In its interface it doesn't really do anything itself, but provides two kinds of handles so you can do something with it: Connections so you can do work in the resource, and transaction management handles consisting of either XAResource for controlling xa (two phase) transactions or LocalTransaction for resources that do not support the xa protocol.
In addition, there are several classes provided by jboss to get all this set up. You will mostly be dealing with ConnectionFactoryLoader mbean configuration. After a resource adapter is deployed, which makes the classes available and checks that all the necessary parts are identified, the ConnectionFactoryLoader will instantiate and configure instances of many of the classes listed above to prepare for access to a specific resource instance. In particular it uses a ConnectionManagerFactory to create a ConnectionManager instance for this connector instance.
There are three major pieces of the connector framework that can be configured: the ManagedConnectionFactory, where you configure such resource adapter specific properties as which resource instance you are connecting to and transaction isolation, the ConnectionManager where you specify pooling policies, and the PrincipalMapping -- how to determine who the resource user is and how to authenticate that user. Each of these is configured using text in the Properties.load file format. In addition, you need to specify many classes and mbeans to get just the configuration you want.
Attributes of a ConnectionFactoryLoader mbean configuration.
mbean code="org.jboss.resource.ConnectionFactoryLoader" name="DefaultDomain:service=ConnectionFactoryLoader,name=DefaultDS". This is the mbean declaration, identifying it as a ConnectionFactoryLoader instance and supplying an ObjectName. Note that the name="myObjectName" is part of the ConnectionFactoryLoader mbean ObjectName and has nothing to do with the jndi name the ConnectionFactory will be bound under. Remember also that ObjectNames have to be unique.
(attribute) JndiName (formerly FactoryName). This is the JNDI name that the ConnectionFactory will end up getting bound under in JNDI. You or JAWS use this to find the ConnectionFactory when you want to do some work on the resource it is connected to.
(attribute)TransactionManagerName. This is the jndi name of the transaction manager to hook up transactions from. Normally it is java:/TransactionManager. This may concievably be changed to an depends at some time in the future.
(depends)ResourceAdapterName. This is the (string representation of) the ObjectName of the RARDeployment set up by the RARDeployer when it deploys the needed rar. The connection factory loader will not be started until this mbean is present. The object names look like this: jboss.jca:service=RARDeployment,name=[display name of rar].
(attribute)ManagedConnectionFactoryProperties. These are, in Properties.load file format, all the configuration you want to do on the ManagedConnectionFactory. Typically this will include what resource you are connecting to and such adapter specific items as transaction isolation. The configurable items are specified in the resource adapter's deployment descriptor (ra.xml). Most of the relevant contents of this deployment descriptor may be viewed in the RARDeployment mbean created by the RARDeployer when it deploys the connector.
(depends)ConnectionManagerFactoryLoaderName. This is the mbean ObjectName of a ConnectionManagerFactoryLoader. By specifying the ConnectionManagerFactoryLoader, you are specifying what kind of connection manager you want to use. There are three choices supplied with JBoss providing different levels of transaction support: none, local, and xa. They all rely on the same pooling code, although they will behave differently when receiving multiple requests for a connection from within the same transaction. If you wish to provide alternate pooling or other ConnectionManager functionality, you must provide both a ConnectionManager and a ConnectionManagerFactory, and provide a ConnectionManagerFactoryLoader configuration section in jboss.jcml to make the factory available. The ConnectionFactoryLoader will not be started until the ConnectionManagerFactoryLoader is available. The three supplied ConnectionManagerFactoryLoaders have ObjectNames: jboss.jca:service=ConnectionManagerFactoryLoader,name=MinervaNoTransCMFactory, jboss.jca:service=ConnectionManagerFactoryLoader,name=MinervaSharedLocalCMFactory, and jboss.jca:service=ConnectionManagerFactoryLoader,name=MinervaXACMFactory.
ConnectionManagerProperties. For the three jboss ConnectionManagers, this configures, in property file format, the pooling parameters.
PoolConfiguration. (per-factory, per-user) Configures whether pooling is based on the users identity or not. If you have only one user (for instance you are using the ManyToOnePrincipalMapping), per-factory is appropriate. If your connector supports reauthentication, per-factory is also appropriate. Otherwise, per-user is apt to work better. As far as I know, this has not been tested significantly.
MinSize. The initial and minimum number of managed connections in the pool. IMPORTANT NOTE: If you wish to set this greater than 0, your resource adapter must support setting a default Subject in the ManagedConnectionFactoryProperties, usually by means of UserName and Password properties. Without this, there is no way for the pool to determine the Subject for the initial connections.
MaxSize. The maximum number of managed connections in the pool. Requests beyond this will block.
BlockingTimeoutMillis. The length of time to wait when the pool is exhausted before throwing a ResourceException. -1 means never.
IdleTimeoutMinutes. This is the (minimum) time for the connection manager to wait in minutes before closing unused connections. This may not be exact, the cleanup process is run based on the CleanupIntervalMinutes parameter.
MaxIdleTimeoutPercent. (0.0 .. 1.0)Despite the name "Percent" suggesting a value between 0 and 100, this parameter must be between 0.0 and 1.0. It controls the amount a pool can shrink due to idle timouts closing connections. If 0.0, each time idle connections are closed, if n are closed, n-1 will be created anew so the pool size is reduced by one. If 1.0, connections are created only if necessary to get back to the pool minimum size.
CleanupIntervalMinutes. The time between idle timeout removal runs. This may not be exact due to server load.
PrincipalMappingClass. In order to get a connection, you need a javax.security.auth.Subject. This class is responsible for mapping the callerPrincipal used in the rest of the application to a Subject of the appropriate form for use with the resource manager. For instance for a database, this subject normally contains a user name and password. The ManyToOnePrincipalMapping ignores the callerPrincipal and always returns a Subject with PrivateCredentials consisting of a PasswordCredential containing the userName and password specified in the PrincipalMappingProperties. Non database resource adapters may require other principal mappings or Subject credentials.
PrincipalMappingProperties. This provides, in Properties.load file format, the properties for the PrincipalMappingClass instance. For the ManyToOnePrincipalMapping, these properties consist of userName and password.
As for any resource adapter, all the resource adapter specific configuration must be done with the ManagedConnectionFactoryProperties entry. Let's consider the contents separately for the two wrappers.
Here are the available properties to configure.
UserName (String). The username used to create JDBC connections. This can also be supplied via the PrincipalMapping class, for instance the ManyToOnePrincipalMapping can provide a "constant" user/password.
Password (String). The default password used to create a JDBC connection. As for UserName, this can be supplied by the PrincipalMapping.
ConnectionURL (String). The jdbc URL used to create jdbc connections from java.sql.Driver.
Driver (String). The class name of the JDBC driver that handles this jdbc URL. Note that it is preferred to use this property rather than the JDBCProvider previously required.
TransactionIsolation (String). The string name of the desired transaction isolation for the connections. The allowed strings are the names of the static Connection members, TRANSACTION_SERIALIZABLE, TRANSACTION_REPEATABLE_READ, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_NONE. Note that not all values are supported by all databases. Alternatively, you may use (the string representation of) the integer value for the transaction isolation level. This may be useful if a driver supports a nonstandard isolation level.
AutoCommit (String). You are strongly advised not to set this. The autocommit property is set false by default for connections obtained from this adapter wrapper. This property is included only to provide emulation of the obsolete JDBCDataSourceLoader which provided no transaction support and left autocommit true.
Here are the available properties to configure.
XADataSourceClass (String). The class name of the underlying XADataSource driver. This specifies what driver is being wrapped.
XADataSourceProperties (String) These are the properties needed to configure the underlying XADataSource. They must be in the format of name=value pairs separated by semicolons, with no spaces. For example, name1=value1;name2=value2;name3=value3. The most typical use for this is the url for the database instance you are connecting to.
UserName (String). The username used to create JDBC connections. This can also be supplied via the PrincipalMapping class, for instance the ManyToOnePrincipalMapping can provide a "constant" user/password.
Password (String). The default password used to create a JDBC connection. As for UserName, this can be supplied by the PrincipalMapping.
TransactionIsolation (String). The string name of the desired transaction isolation for the connections. The allowed strings are the names of the static Connection members, TRANSACTION_SERIALIZABLE, TRANSACTION_REPEATABLE_READ, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_NONE. Note that not all values are supported by all databases. Alternatively, you may use (the string representation of) the integer value for the transaction isolation level. This may be useful if a driver supports a nonstandard isolation level.
 | |