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
#EJB local references
#Web service references
#Resource references
#Resource environment references

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>.

where

name is the name of the remote home interface used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the ejb-ref-name provided in the Java EE deployment descriptor.
link is the name of the remote home interface in the EJB module.

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.

where

name is the name of the remote home interface used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the ejb-ref-name provided in the Java EE deployment descriptor.
group is the directory or directory tree in the repository where the unique artifact directory is located.
artifact is the prefix (no version or file extension) of the library's file name
version is the version number to be appended to the file name.
type is the file extension for the file in the repository.
link is the name of the remote home interface in the EJB module.

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>.

where

name is the name of the local home interface used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the ejb-ref-name provided in the Java EE deployment descriptor.
link is the name of the local home interface in the EJB module.

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.

where

name is the name of the local home interface used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the ejb-ref-name provided in the Java EE deployment descriptor.
group is the directory or directory tree in the repository where the unique artifact directory is located.
artifact is the prefix (no version or file extension) of the library's file name
version is the version number to be appended to the file name.
type is the file extension for the file in the repository.
link is the name of the local home interface in the EJB module.

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.

where

name is the name of the service reference used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the service-ref-name provided in the Java EE deployment descriptor.
portName specifies the name to identify the port to connect to.
protocol specifies the protocol to use for the connection, typically http or https.
host specifies the host for the connection.
port specifies the port for the connection.
uri specifies the web service to connect to.
credentials identifies the credentials name to be used for secure connections.

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.

where

name is the name of the service reference used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the service-ref-name provided in the Java EE deployment descriptor.
service is the service name for the service block in the WSDL.
portName specifies the name to identify the port to connect to.
protocol specifies the protocol to use for the connection, typically http or https.
host specifies the host for the connection.
port specifies the port for the connection.
uri specifies the web service to connect to.
credentials identifies the credentials name to be used for secure connections.
binding specifies the binding name to that identifies this web service port configuration.

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.

where

name is the name of the reference used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the resource-ref-name provided in the Java EE deployment descriptor.
URL is the URL that is be be mapped to that reference.

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>.

where

name is the name of the reference used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the resource-ref-name provided in the Java EE deployment descriptor.
link is the name to be mapped to the reference and should match the name specified in the <connectiondefinition-instance> element of the connector's deployment plan.

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.

where

name is the name of the reference used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the resource-ref-name provided in the Java EE deployment descriptor.
group is the directory or directory tree in the repository where the unique artifact directory is located.
artifact is the prefix (no version or file extension) of the library's file name
version is the version number to be appended to the file name.
type is the file extension for the file in the repository.
link is the name to be mapped to the reference and should match the name specified in the <connectiondefinition-instance> element of the connector's deployment plan.

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>.

where

name is the name of the reference used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the resource-ref-name provided in the Java EE deployment descriptor.
The <admin-object-module> element is required when the queue or topic name is not unique in the server. In this case, module is the name of the connector that contains the topic or queue specified in the <admin-object-link> element.
link is the name of the administered object to be mapped to the reference and should match the name specified in the <message-destination-name> element of the <adminobject-instance> of the connector's deployment plan.

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.

where

name is the name of the reference used in your module. The JNDI name used by your module will be java:/comp/env/name and it should map to the resource-ref-name provided in the Java EE deployment descriptor.
group is the directory or directory tree in the repository where the unique artifact directory is located.
artifact is the prefix (no version or file extension) of the library's file name
version is the version number to be appended to the file name.
type is the file extension for the file in the repository.
link is the name of the administered object to be mapped to the reference and should match the name specified in the <message-destination-name> element of the <adminobject-instance> of the connector's deployment plan.