Show TOC

 Configuring Resource ReferencesLocate this document in the navigation structure

Use

Resource references are used to obtain connections to factories for various resource manager objects. On the J2EE Engine, these include:

  • javax.sql.DataSource factories for objects that provide access to database management systems.
  • javax.jms.QueueConnectionFactory for QueueConnection objects that are used with point-to-point JMS providers.
  • javax.jms.TopicConnectionFactory for TopicConnection objects that are used with publish/subscribe JMS Providers.
  • javax.resource.cci.ConnectionFactory for connector objects to EIS systems.
  • javax.mail.Session object that is used by the JavaMail API to send/receive mail messages.
  • java.net.URL for obtaining URL connections.
Procedure

On the web.xml screen of your Web Module project, proceed as follows:

  1. Open the Resource screen.
  2. Select Resource Entries and choose Add.
  3. Select the added entry and provide the following information in the fields on the right-hand side:
    1. Enter the name of the resource manager connection factory reference in the Resource Reference Name field. This is the name that you use in your servlet (or JSP) code to look up that resource. It is relative to the java:comp/env context.

The name you specify in this field may not be the real JNDI name of the resource you are referencing. If this is the case, you must additionally perform the steps described below in "Mapping the Reference Name to the JNDI Name of the Resource Using web-j2ee-engine.xml".

  1. Choose the type of the resource manager connection factory from the Resource Type dropdown list box.
  2. Decide on the Resource Authentication scheme that must be used to authenticate the referring component with the referenced resource manager connection factory. Container is selected by default, which means that the container uses the authentication settings for the component and authenticates it with the resources of the connection factory. If you select Application, you have to do the authentication programmatically in your servlet (or JSP) code.
  3. By default, each resource connection is shared to application-scoped components. If you want to prevent this, choose Resource Sharing Scope and then choose Unshareable.
  4. Optionally, enter a description of the resource reference in the Description field.

Mapping the Reference Name to the JNDI Name of the Resource Using web-j2ee-engine.xml

If you have specified a custom name of the resource reference in the Resource Reference Name field in the web.xml, then you must map it to the real JNDI name with which the resource is bound to the naming. This is necessary to be able to look that resource up in your code.

You define the mapping using the web-j2ee-engine.xml screen of your Web Module project. Proceed as follows:

  1. Open the web-j2ee-engine.xml screen.
  2. Open the References screen.
  3. Select resource-ref and choose Add.
  4. From the Choose items screen that appears, choose the resource reference that you have defined in the web.xml.
  5. Enter the JNDI name of the target resource manager connection factory in the JNDI name field.

    The value you must enter in the JNDI Name field depends on the type of the resource you reference:

    • For resources of type javax.sql.DataSource , it must be the same as the value of the <data-source-name> tag you specified in the data-sources.xml descriptor, or the value of the <alias> tag of the same descriptor if you have defined an alias for your DataSource . If you do not use the data-sources.xml but the data-source-aliases.xml, the value of the JNDI Name field must be the same as the value of the <alias> tag for the corresponding DataSource .
    • For resources of type javax.jms.QueueConnectionFactory and javax.jms.TopicConnectionFactory , it must be the same as the value of the <factory-name> tag you specified in the jms-factories.xml descriptor, or the value of the <alias> tag of the same descriptor if you have specified an alias for your ConnectionFactory .
    • For resources of type javax.resource.cci.ConnectionFactory , it must be the same as the value of the <jndi-name> tag you specified in the connector-j2ee-engine.xml descriptor, or the value of the <alias> tag of the same descriptor if you have specified an alias for your ConnectionFactory . If you have not used the connector-j2ee-engine.xml descriptor (since it is not mandatory), then the JNDI name of the resource is a default one and is equivalent to the name of the corresponding RAR file (not including the .rar file extension).
    • For resources of type javax.mail.Session , it must be the same as the value of the <res-ref-name> tag you specified in the web.xml descriptor for your Session .
    • For resources of type java.net.URL , it must be the same as the value of the <res-ref-name> tag you specified in the web-j2ee-engine.xml descriptor for your Session .
  6. Optionally, choose Non transactional so that connections to the resource manager are not listed in the global transactions.
Example

Resource of Type javax.mail.Session

To get a resource of type javax.mail.Session the web.xml descriptor can be as follows:

  <resource-ref>
      <res-ref-name>mail/Session</res-ref-name>
      <res-type>javax.mail.Session</res-type>
      <res-auth>Container</res-auth>
    </resource-ref>

Resource of Type java.net.URL

We need to redirect an HTTP request to a URL available as JNDI resource. The following source code retrieves the corresponding java.net.URL resource and redirects the client request to it.

InitialContext context = new InitialContext();
URL yahoo=(URL)context.lookup("java:comp/env/url/Yahoo.com");
response.sendRedirect(yahoo.toString());

We describe the reference to that resource in the web.xml as follows:

  <resource-ref>
      <res-ref-name>url/Yahoo.com</res-ref-name>
      <res-type>java.net.URL</res-type>
      <res-auth>Container</res-auth>
    </resource-ref>

We describe the reference to that resource in the web-j2ee-engine.xml as follows:

  <resource-ref>
      <res-ref-name>url/Yahoo.com</res-ref-name>
      <res-link>http://www.yahoo.com</res-link>
    </resource-ref>

More information about the web-j2ee-engine.xml deployment descriptor:

web-j2ee-engine.dtd