Chapter 2 Jaguar Naming Services

JNDI support

Java Naming and Directory Interface (JNDI) is a standard Java interface for accessing distributed objects and services by name. It provides a portable, unified interface for naming and directory services. The JNDI specification is independent of any specific directory or naming service such as LDAP, NDS, DCE/CDS, or NIS.

Jaguar's JNDI implementation includes the JNDI service provider interface (SPI), which enables you to use a variety of custom directory and naming services. Jaguar uses the SPI in conjunction with the CosNaming interface to provide component lookup capability. Given a bound name, the SPI locates the referenced package and component. Once it locates the component, the SPI works with the client stub interface to instantiate the component and return the requested object.

For complete information about instantiating and resolving objects with JNDI, see Chapter 13, "Creating CORBA-Compatible Java Clients" in the Jaguar CTS Programmer's Guide.

JNDI version level In Jaguar servers that use JDK 1.2, the JNDI InitialContext object follows the JNDI 1.2 interface specification. In servers that use JDK 1.1, JNDI InitialContext follows the JNDI 1.1 interface specification. When you start the Jaguar server, the JNDI classes required for the server's JDK version are configured automatically.

JNDI J2EE features

Jaguar supports the JNDI features required by the Java 2 Enterprise Edition (J2EE) platform specification. You must run the JDK 1.2 version of the Jaguar server to use these features.

In J2EE, you can use the application component's naming environment to customize an application's business logic without accessing the source code. The application component's container implements the environment as a JNDI naming context and provides the JNDI interfaces to access the environment properties that you define in the deployment descriptor.

Environment properties

When you deploy a J2EE application, use the deployment descriptor to define all the environment properties that the application component needs to access. This sample code defines the environment property (env-entry) maxExemptions as an Integer and sets its value to 10:

<env-entry>
   <description>
     The maximum number of tax exemptions
   </description>
   <env-entry-name>maxExemptions</env-entry-name>
   <env-entry-type>java.lang.Integer</env-entry-type>
   <env-entry-value>10</env-entry-value>
</env-entry>

The information between the opening and closing env-entry tags defines an environment entry element, which consists of:

description This is optional.
env-entry-name The environment property name, relative to the java:comp/env context.
env-entry-type The environment property's Java datatype must be one of: Boolean, Byte, Double, Float, Integer, Long, Short, or String.
env-entry-value The environment property value, which is optional.

Within the same container, all instances of an application component share the same environment properties. The component instances cannot modify the environment at runtime.

An application component instance uses the JNDI interfaces to locate the environment naming context and access the environment properties. To locate the naming context, an application creates a javax.naming.InitialContext object and gets the InitialContext for java:comp/env. In this example, the application retrieves the value of the environment property maxExemptions and uses that value to determine an outcome:

Context initContext = new InitialContext();
Context myEnv = 
   (Context)initContext.lookup("java:comp/env");

// Get the maximum number of tax exemptions
Integer max=(Integer)myEnv.lookup("maxExemptions");

// Get the minimum number of tax exemptions 
Integer min = (Integer)myEnv.lookup("minExemptions");

// Use these properties to customize the business logic
if (numberOfExemptions > max.intValue() ||
   (numberOfExemptions < min.intValue())
    throw new InvalidNumberOfExemptionsException();

Default name service When you call the empty constructor to create a new InitialContext, Jaguar sets the Context.INITIAL_CONTEXT_FACTORY system property and sets Jaguar's EJB name service as the default.

For information about using Jaguar Manager to add and configure environment properties in Web applications, see Chapter 22, "Creating Web Applications" in the Jaguar CTS Programmer's Guide.

EJB references

An EJB reference identifies the home of an enterprise Bean. You can use the deployment descriptor to create a link between an EJB reference and an enterprise Bean, contained within an EJB JAR file. Deployment descriptor interfaces allow an application component to access an enterprise Bean's home interface using EJB references.

To locate an enterprise Bean's home interface, declare an EJB reference in the deployment descriptor and use JNDI to look up the interface. The referenced enterprise Bean must be in the ejb subcontext of the application component's environment.

Declaring an EJB reference

You can declare an EJB reference in the deployment descriptor using the ejb-ref element. The data between the opening and closing ejb-ref tags defines an ejb-ref element. This code sample defines an EJB reference to the Employee entity Bean:

<ejb-ref>
   <description>
      Reference to the Employee entity Bean
   </description>
   <ejb-ref-name>ejb/Employee</ejb-ref-name>
   <ejb-ref-type>Entity</ejb-ref-type>
   <home>com.wooster.empl.EmployeeHome</home>
   <remote>com.wooster.empl.Employee</remote>
</ejb-ref>

An ejb-ref element contains:

description This is optional.
ejb-ref-name The name of the Bean used in the application component.
ejb-ref-type The Bean type, Entity or Session.
home The expected Java type of the home interface.
remote The expected Java type of the remote interface.
ejb-link This is optional.

This code sample illustrates how to use JNDI to look up the home interface of the Employee enterprise Bean:

// Get the default initial JNDI context
Context initContext = new InitialContext();

// Look up the home interface of the Employee enterprise
// Bean
Object result =
   initContext.lookup("java:comp/env/ejb/Employee");

// Convert the result to the correct type
EmployeeHome empHome = (EmployeeHome)
   javax.rmi.PortableRemoteObject.narrow(result,
   EmployeeHome.class);

Declaring an EJB link

You can define a link from an EJB reference to an enterprise Bean by declaring an ejb-link element in the deployment descriptor. The application component and the target enterprise Bean must be in the same J2EE application. This sample code creates a link to the Employee enterprise Bean, by adding an ejb-link element to the Bean's EJB reference definition:

<ejb-ref>
   <description>
      Reference to the Employee entity Bean
   </description>
   <ejb-ref-name>ejb/Employee</ejb-ref-name>
   <ejb-ref-type>Entity</ejb-ref-type>
   <home>com.wooster.empl.EmployeeHome</home>
   <remote>com.wooster.empl.Employee</remote>
   <ejb-link>Employee</ejb-link>
</ejb-ref>

For information about using Jaguar Manager to add and configure EJB references in Web applications, see Chapter 22, "Creating Web Applications" in the Jaguar CTS Programmer's Guide.

For information about using Jaguar Manager to add and configure EJB references in EJB components, see Chapter 8, "Creating Enterprise JavaBean Components" in the Jaguar CTS Programmer's Guide.

Resource factory references

A resource factory is an object that you use to create resources. You can assign a logical name to a resource factory in the deployment descriptor.

A resource-ref element defines a single resource factory reference. This code sample defines a reference to the resource factory that implements the DataSource interface:

<resource-ref>
   <description>
      Data source for the database in which the Employee
      enterprise Bean records transactions
   </description>
   <res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
   <res-type>javax.sql.DataSource</res-type>
   <res-auth>Container</res-auth>
</resource-ref>

A resource-ref element contains:

description This is optional.
res-ref-name Resource reference name used in the application's code.
res-type Resource Java datatype that the application expects.
res-auth Resource sign-on authorization, Bean or Container.

This code sample obtains a reference to the resource factory that implements the DataSource interface, and uses that reference to get a database connection (resource):

// Obtain the initial JNDI context
Context initContext = new InitialContext();

// Look up the resource factory using JNDI
javax.sql.DataSource ds = (javax.sql.DataSource)
   initContext.lookup
     ("java:comp/env/jdbc/EmployeeAppDB");

// Get a database connection
java.sql.Connection connection = ds.getConnection();

For information about using Jaguar Manager to add and configure resource references in Web applications, see Chapter 22, "Creating Web Applications" in the Jaguar CTS Programmer's Guide.

For information about using Jaguar Manager to add and configure resource references in EJB components, see Chapter 8, "Creating Enterprise JavaBean Components" in the Jaguar CTS Programmer's Guide.

UserTransaction references

J2EE application components can use the Java Transaction API (JTA) UserTransaction interface to manage transactions. A component instance can look up an object that implements the interface using the JNDI name java:comp/UserTransaction.

In this code sample, an application component uses the interface to manage a transaction:

// Get the initial JNDI context
Context initContext = new InitialContext();

// Look up the UserTransaction object
UserTransaction tran = (UserTransaction)
   initContext.lookup("java:comp/UserTransaction");

// Start a transaction
tran.begin();

// data updates

// Commit the transaction
tran.commit();