JNDI environment references

Resources referenced by JNDI names often must be mapped into the names of the resources as deployed in the server. This allows resource programmers to choose names without regard to the server's configuration. Deployment plans contain the information necessary to map the names chosen to resources deployed in the server.

References must be defined in the following order.

EJB references

Use the <ejb-ref> to map a reference to an EJB's remote home interface. Choose one of the following templates.

Choose this template when the referenced remote home interface can be found by searching in your module's EAR (when the module is included in an EAR) or your module's <dependencies>.


<ejb-ref>
  <ref-name>name</ref-name>
  <ejb-link>link</ejb-link>
</ejb-ref>

where

Choose this template when the referenced remote home interface can only be found with additional selection criterion. For example, if the remote home interface name is not unique within your module's EAR (when the module is included in an EAR) or your module's <dependencies> this template will remove any ambiguity. 


<ejb-ref>
  <ref-name>name</ref-name>
  <pattern>
    <groupId>group</groupId>
    <artifactId>artifact</artifactId>
    <version>version</version>
    <module>module</module>
    <type>type</type>
    <name>link</name>
  </pattern>
</ejb-ref>

where

EJB local references

Use the <ejb-local-ref> to map a reference to an EJB's local home interface. Choose one of the following templates.

Choose this template when the referenced local home interface can be found by searching in your module's EAR (when the module is included in an EAR) or your module's <dependencies>.


<ejb-local-ref>
  <ref-name>name</ref-name>
  <ejb-link>link</ejb-link>
</ejb-local-ref>

where

Choose this template when the referenced remote home interface can only be found with additional selection criterion. For example, if the remote home interface name is not unique within your module's EAR (when the module is included in an EAR) or your module's <dependencies> this template will remove any ambiguity.


<ejb-local-ref>
  <ref-name>name</ref-name>
  <pattern>
    <groupId>group</groupId>
    <artifactId>artifact</artifactId>
    <version>version</version>
    <module>module</module>
    <type>type</type>
    <name>name</name>
  </pattern>
</ejb-local-ref>

where

Web service references

Use the <service-ref> element to map a reference to a Web service. Choose one of the following templates.

Use this template when the WSDL for the referenced Web service is complete. This reference will target only the ports listed.


<service-ref>
  <service-ref-name>name</service-ref-name>
  <!-- Repeat the port element for each port available through the reference -->
  <port>
    <port-name>portName</port-name>
    <protocol>protocol</protocol>
    <host>host</host>
    <port>port</port>
    <uri>uri</uri>
    <credentials-name>credentials</credentials-name>
  </port>
</service-ref>

where

Use this template when the WSDL for the referenced service is not complete. The elements specified here will provide the information needed to complete the WSDL.


<service-ref>
  <service-ref-name>name</service-ref-name>
  <service-name>service</service-name>
  <!-- Repeat the port-completion element for every port available from the reference -->
  <port-completion>
    <port>
      <port-name>portName</port-name>
      <protocol>protocol</protocol>
      <host>host</host>
      <port>port</port>
      <uri>uri</uri>
      <credentials-name>credentials</credentials-name>
    </port>
    <binding-name>binding</binding>
  </port-completion>
</service-ref>

where

Resource references

Use the <resource-ref> element to map a reference to a URL or a connector's connection factory Choose one of the following templates.

Choose this template when the reference is for a URL.


<resource-ref>
  <ref-name>name</ref-name>
  <url>url</resource-url>
</resource-ref>

where

Choose this template when the reference is used to find a connection factory that can be found by searching in your module's EAR (when the module is included in an EAR) or your module's <dependencies>. Typically, this will be a JDBC or JMS connection factory, but it could be any connection factory from a Java EE connector with an <outbound-resourceadapter>.


<resource-ref>
  <ref-name>name</ref-name>
  <resource-link>link</resource-link>
</resource-ref>

where

Choose this template when the referenced connection factory can only be found with additional selection criterion. For example, if the connection factory name is not unique within your module's EAR (when the module is included in an EAR) or your module's <[dependencies> this template will remove any ambiguity.


<resource-ref>
  <ref-name>name</ref-name>
  <pattern>
    <groupId>group</groupId>
    <artifactId>artifact</artifactId>
    <version>version</version>
    <module>module</module>
    <type>type</type>
    <name>name</name>
  </pattern>
</resource-ref>

where

Resource environment references

Use the <resource-env-ref> to map a reference to a Java connector's administered object. If you are deploying an asset that uses Java EE 1.3 conventions for its Java EE deployment descriptors, this can also be used to map JMS topics and queues, but for any asset that follows Java EE 1.4 connections or better, the <message-destination> element should be used instead.

Choose this template when the reference is used to find an administered object that can be found by searching in your module's EAR (when the module is included in an EAR) or your module's <dependencies>. 


<resource-env-ref>
  <ref-name>name</ref-name>
  <!--
  <admin-object-module>module</admin-object-module>
  -->
  <admin-object-link>link</admin-object-link>
</resource-env-ref>

where

Choose this template when the referenced administered object can only be found with additional selection criterion. For example, if the administered object name is not unique within your module's EAR (when the module is included in an EAR) or your module's <dependencies>, this template will remove any ambiguity. 


<resource-env-ref>
  <ref-name>name</ref-name>
  <pattern>
    <groupId>group</groupId>
    <artifactId>artifact</artifactId>
    <version>version</version>
    <module>module</module>
    <type>type</type>
    <name>link</name>
  </pattern>
</resource-env-ref>

where