Jndi Lookups

Using JNDI Lookups of J2C Connection Factories and
JDBC Datasources in WebSphere Applications

Direct versus Indirect Lookups
A developer has a choice of two types of lookups (direct and indirect) for
obtaining a J2C connection factory or a JDBC datasource when there is a need
to access an Enterprise Information System (EIS) resource such as CICS, IMS,
or DB2.
The first type uses a specific JNDI name in the context lookup and is called a
“direct lookup”. This type of lookup will obtain a connection factory or datasource
if and only if a factory or datasource with that JNDI name already exists in the
WebSphere configuration. A direct lookup is ok for development and unit testing
but is not appropriate for production. The primary reason is that when the
application is installed in a production environment, the JNDI name used by the
developer is not exposed during the deployment process. The application
Deployer is not able to select which connection factory or datasource in the
production environment is to be used and the WebSphere Administrator must
ensure a resource with the JNDI name specified by the developer is defined to
enable the application to run. Both of these issues are highly problematic in a
production environment.
To give the application’s Deployer the ability to select which connection factory or
datasource is to be used by the application, the developer needs to use an
“indirect lookup” in the context lookup. An indirect lookup is specified by using
the string “java:comp/env” as a prefix for the resource name (which is not
necessarily the same as the JNDI name), for an example see Figure 1 –
Resource Reference in a Deployment Descriptor. When the developer uses this
prefix, a context lookup will look for a resource reference with that name in the
global name space. The resource reference information provides the JNDI name
of the connection factory or datasource (as well as other connection parameters
such as Authentication type and Sharing scope). In a test environment the JNDI
name provided in the resource reference will be used to locate a connection
factory or datasource in the test environment’s WebSphere configuration (see
Figure 2 - J2C Connection Factory). In a production environment the presence
of a resource reference in the EAR allows the Deployer to specify which resource
is to be used, (see Figure 3 Mapping Resource References During Deployment)
and the relationship between the resource reference and the JNDI name
specified by the Deployer maintained in the name space.
Not only is the use of an indirect lookup recommended because of being a best
practice since it gives more control over connection management properties
(authentication and sharing scope) specified in a resource reference and allows
the Deployer to select which J2C connection factory is to be used, it is
recommended because the usage of direct lookups for J2C connection factories
has been deprecated in Version 6 of WebSphere (see Scenario 5).
© 2006, IBM Advanced Technical Support Techdocs - Washington Systems Center Version 1/15/2006
http://www.ibm.com/support/Techdocs
TD102945 Using JNDI Lookups of J2C Connection Factories and JDBC Datasources in WebSphere Applications Page 1 of 8
+
Figure 1 - Resource Reference in Deployment Descriptor
In this example the developer uses the resource reference name of ‘IMS’ to
obtain an IMS J2C connection factory in an indirect lookup.
Also please note that the concepts described here also apply to obtaining CICS
J2C connection factories as well as JDBC datasources.
Figure 2 - J2C Connection Factory

The name of the IMS J2C connection factory can be any value. The JNDI name
of the factory is used to specify the factory during deployment in production and
to locate the factory in a WebSphere test configuration.
Figure 3 - Mapping Resource References During Deployment
The Deployer has selected a J2C connection factory with a JNDI name of
eis/IMSLocal rather than the original resource reference JNDI name of
eis/IMSRemote for any resource references to IMS.
Note to EGL developers, the EGL location property in the callLink member provides
the J2C connection factory lookup string when remoteComType is set to CICSJ2C.
Now lets look at various scenarios and see how this actually works using
Rational Application Developer test environment when accessing IMS.
Scenario 1: Indirect Lookup-Valid Resource-Ref and J2C CF
In this scenario assume the EAR contains a resource reference as in Figure 1

and the WebSphere configuration has a J2C connection with a JNDI name of
eis/IMSRemote as in Figure 2.
The application uses an indirect lookup as below:

javax.resource.cci.ConnectionFactory cf =
(ConnectionFactory)ctx.lookup("java:comp/env/IMS");
The indirect lookup of IMS locates a resource reference by this name (see Figure
1 – Resource Reference in Deployment Descriptor). The resource reference has
a JNDI Name of eis/IMSRemote. The J2C connection factory IMSRemote has
a matching JNDI name (see Figure 2 - J2C Connection Factory) and this
connection factory is used to successfully access IMS
Scenario 2: Indirect Lookup-Invalid Resource-Ref
This scenario demonstrates what happens when using an indirect lookup without
having a resource reference with that name in the deployment descriptor.
(ConnectionFactory)ctx.lookup("java:comp/env/myIMS");
The indirect lookup of myIMS for a resource reference by this name fails with a
NameNotFoundException exception since there is no resource reference with
this name in the deployment descriptor (see messages below)
javax.naming.NameNotFoundException: Name "comp/env/myIMS" not found in

context "java:".
Scenario 3: Indirect Lookup-Resource-Ref with an invalid JNDI Name
Now lets assume the EAR has a resource reference as configured in Figure 1 but
that a J2C connection with a JNDI name of eis/IMSRemote does not exist in the
WebSphere configuration.
(ConnectionFactory)ctx.lookup("java:comp/env/IMS");
A NameNotFoundException exception will be thrown when the JNDI name of

eis/IMSRemote is not found in the WebSphere configuration (see the messages
below)
NMSV0605W: A Reference object looked up from the context "java:" with the name
"comp/env/IMS" was sent to the JNDI Naming Manager and an exception resulted.
Reference data follows:
Reference Factory Class Name: com.ibm.ws.util.ResRefJndiLookupObjectFactory
Reference Factory Class Location URLs: <null>
Reference Class Name: java.lang.Object
Type: ResRefJndiLookupInfo
Content: com.ibm.ws.util.ResRefJndiLookupInfo@77039111 ResRefJndiLookupInfo: Look
up Name="IMS";JndiLookupInfo: jndiName="eis/IMSRemote"; providerURL="";
initialContextFactory=""
Exception data follows:

javax.naming.NameNotFoundException: Context:
rigelNode01Cell/nodes/rigelNode01/servers/server1, name: eis/IMSRemote: First
component in name IMSRemote not found. Root exception is
org.omg.CosNaming.NamingContextPackage.NotFound:
IDL:omg.org/CosNaming/NamingContext/NotFound:1.0
Note that the NameNameNotFoundException exception is for the JNDI name

specified in the resource reference.
Scenario 4: Direct Lookup-No JNDI name match with a J2C CF
In this scenario the developer does a direct lookup when there is no J2C
connection factory with this JNDI name in the WebSphere configuration.
The application uses a direct lookup as below:
(ConnectionFactory)ctx.lookup("eis/IMSRemote");
The direct lookup of a JNDI name of eis/IMSRemote fails with a

NameNotFoundException exception (see below) since there is no J2C
connection factory with a JNDI name of eis/IMSRemote.
javax.naming.NameNotFoundException: Context:
rigelNode01Cell/nodes/rigelNode01/servers/server1, name: eis/IMSRemote: First
component in name IMSRemote not found. Root exception is
org.omg.CosNaming.NamingContextPackage.NotFound:
IDL:omg.org/CosNaming/NamingContext/NotFound:1.0
Scenario 5: Direct Lookup-JNDI name match with a J2C CF
In this scenario the developer does a direct lookup. There is a J2C connection
factory with this JNDI name in the WebSphere configuration.
The application uses a direct lookup as below:
(ConnectionFactory)ctx.lookup("eis/IMSRemote");
The direct lookup of eis/IMSRemote locates a J2C connection factory

IMSRemote with a matching JNDI name (see Figure 2 - J2C Connection
Factories), this connection factory is used to successfully access IMS. See the
messages below and note that warning message J2CA0294W is displayed to
indicate a direct JNDI lookup has been deprecated that resource reference
default values are used for the connection.
J2CA0294W: Deprecated usage of direct JNDI lookup of resource
eis/IMSRemote. The following default values are used: [Resource-ref
settings]
res-auth: 1 (APPLICATION)
res-isolation-level: 0 (TRANSACTION_NONE)
res-sharing-scope: true (SHAREABLE)
loginConfigurationName: null
loginConfigProperties: null
[Other attributes]
res-resolution-control: 999 (undefined)

isCMP1_x: false (not CMP1.x)
isJMS: false (not JMS)
Note that the connection management properties default.
Summary
An "indirect" name with the java:comp/env prefix should be used to locate

J2C Connection Factories or JDBC Datasources. This makes any
resource-reference data associated with the application available to the
connection management runtime, to better manage resources based on
the res-auth, res-isolation-level, res-sharing-scope, and res-resolution-
control settings. Use of "java:comp/env" looks in the global name space
and requires a resource references for the request name be specified in
the deployment descriptor.
Doing an indirect lookup (e.g. "java:comp/env/eis/IMS") uses the resource-

ref with this name and the JNDI name in the name space is used to locate
the J2C connection factory or JDBC datasource.
An “direct” name (not using "java:comp/env") ignores any resource

references in the deployment descriptor and looks for a JC2 connection
factory or JDBC datasource with a JNDI name which matches the name
used in the lookup.

Jndi Lookups

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Jndi Lookups

Uploaded by

Copyright:

Available Formats

Using JNDI Lookups of J2C Connection Factories and

JDBC Datasources in WebSphere Applications

Figure 1 - Resource Reference in Deployment Descriptor

Figure 2 - J2C Connection Factory

Figure 3 - Mapping Resource References During Deployment

Scenario 1: Indirect Lookup-Valid Resource-Ref and J2C CF

In this scenario assume the EAR contains a resource reference as in Figure 1

The application uses an indirect lookup as below:

Scenario 2: Indirect Lookup-Invalid Resource-Ref

The application uses an indirect lookup as below:

javax.naming.NameNotFoundException: Name "comp/env/myIMS" not found in

The application uses an indirect lookup as below:

A NameNotFoundException exception will be thrown when the JNDI name of

Exception data follows:

Note that the NameNameNotFoundException exception is for the JNDI name

The application uses a direct lookup as below:

The direct lookup of a JNDI name of eis/IMSRemote fails with a

Scenario 5: Direct Lookup-JNDI name match with a J2C CF

The application uses a direct lookup as below:

The direct lookup of eis/IMSRemote locates a J2C connection factory

res-resolution-control: 999 (undefined)

Note that the connection management properties default.

An "indirect" name with the java:comp/env prefix should be used to locate

Doing an indirect lookup (e.g. "java:comp/env/eis/IMS") uses the resource-

An “direct” name (not using "java:comp/env") ignores any resource

You might also like