JBoss.org Community Documentation
Resource manager connection factory references allow application component code to refer to resource factories using logical names called resource manager connection factory references. Resource manager connection factory references are defined by the resource-ref
elements in the standard deployment descriptors. The Deployer
binds the resource manager connection factory references to the actual resource manager connection factories that exist in the target operational environment using the jboss.xml
and jboss-web.xml
descriptors.
Each resource-ref
element describes a single resource manager connection factory reference. The resource-ref
element consists of the following child elements:
An optional description element that provides the purpose of the reference.
A
res-ref-name
element that specifies the name of the reference relative to the java:comp/env
context. The resource type based naming convention for which subcontext to place the res-ref-name
into is discussed in the next paragraph.
A res-type element that specifies the fully qualified class name of the resource manager connection factory.
A
res-auth
element that indicates whether the application component code performs resource signon programmatically, or whether the container signs on to the resource based on the principal mapping information supplied by the Deployer. It must be one of Application
or Container
.
An optional res-sharing-scope element. This currently is not supported by JBoss.
The J2EE specification recommends that all resource manager connection factory references be organized in the subcontexts of the application component's environment, using a different subcontext for each resource manager type. The recommended resource manager type to subcontext name is as follows:
JDBC DataSource
references should be declared in the java:comp/env/jdbc
subcontext.
JMS connection factories should be declared in the java:comp/env/jms
subcontext.
JavaMail connection factories should be declared in the java:comp/env/mail
subcontext.
URL connection factories should be declared in the java:comp/env/url
subcontext.
Example 4.12, “A web.xml resource-ref descriptor fragment” shows an example web.xml
descriptor fragment that illustrates the resource-ref
element usage. Example 4.13, “ENC resource-ref access sample code fragment” provides a code fragment that an application component would use to access the DefaultMail
resource declared by the resource-ref
.
<web> <!-- ... --> <servlet> <servlet-name>AServlet</servlet-name> <!-- ... --> </servlet> <!-- ... --> <!-- JDBC DataSources (java:comp/env/jdbc) --> <resource-ref> <description>The default DS</description> <res-ref-name>jdbc/DefaultDS</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> </resource-ref> <!-- JavaMail Connection Factories (java:comp/env/mail) --> <resource-ref> <description>Default Mail</description> <res-ref-name>mail/DefaultMail</res-ref-name> <res-type>javax.mail.Session</res-type> <res-auth>Container</res-auth> </resource-ref> <!-- JMS Connection Factories (java:comp/env/jms) --> <resource-ref> <description>Default QueueFactory</description> <res-ref-name>jms/QueueFactory</res-ref-name> <res-type>javax.jms.QueueConnectionFactory</res-type> <res-auth>Container</res-auth> </resource-ref> <web>
Example 4.12. A web.xml resource-ref descriptor fragment
Context initCtx = new InitialContext(); javax.mail.Session s = (javax.mail.Session) initCtx.lookup("java:comp/env/mail/DefaultMail");
Example 4.13. ENC resource-ref access sample code fragment