Oracle8i Enterprise JavaBeans Developer's Guide and Reference Release 3 (8.1.7) Part Number A83725-01 |
Library | Service | Contents | Index

## Using JNDI to Access Bound Objects

Clients use the Java Naming and Directory Interface (JNDI) interface to look up published objects in the JServer namespace. JNDI is an interface supplied by Sun Microsystems that gives the Java application developer a methodology to access name and directory services. This section discusses only those parts of the JNDI API that are needed to look up and activate published objects. To obtain a complete set of documentation for JNDI, see the web site URL `http://java.sun.com/products/jndi/index.html`.

Note: It is also possible to access the session namespace without using JNDI. Instead, you can use CosNaming methods.

As described in "URL Syntax", the JNDI URL required to access any bound name in the JServer namespace requires a compound name consisting of the following two components:

- Service name--the service name is used by JServer to retrieve a handle to the correct namespace.

  Several namespaces will exist within your network. The service specifies which namespace to retrieve the JNDI bound object from. Service names can be one of the following:

  Service Name | Description
  --- | ---
  `sess_iiop:// <hostname>:<port>:<SID>` | Specifies the host, port, and SID that the desired namespace is located. Specifying this service name only without a session name returns a ServiceCtx object. The session IIOP service is the main service used by IIOP applications. It retrieves objects and object references bound in JNDI namespaces on different database hosts. See "Session IIOP Service" for a full description.
  `jdbc_access:` | Specifies that the desired object exists in a well-known namespace. Used primarily to retrieve JTA UserTransaction and DataSource objects from the namespace.
  `java:` | Used to specify that the bound name is actually an EJB environment variable that was specified within its deployment descriptor.

- Session name--the actual JNDI bound name of the object within the designated namespace. The syntax mimics a UNIX file system syntax. The session name can be represented by a `SessionCtx` object.

You can utilize the service and session contexts to perform some advanced techniques, such as opening different sessions within a database or enabling several clients to access an object in a single session. These are discussed further in the "Session IIOP Service". However, for simple JNDI lookup invocations, you should use the URL syntax specified in "URL Syntax".

### Importing JNDI Support Classes

When you use JNDI in your client or server object implementations, be sure to include the following import statements in each source file:

    import javax.naming.Context;    // the JNDI Context interface
    import javax.naming.InitialContext;
    import oracle.aurora.jndi.sess_iiop.ServiceCtx; // JNDI property constants
    import java.util.Hashtable;     // hashtable for the initial context environment

### Retrieving the JNDI InitialContext

`Context` is an interface in the `javax.naming` package that is used to retrieve the `InitialContext`. All Oracle8i EJB and CORBA clients use the `InitialContext` for JNDI `lookup()`. Before you perform a JNDI `lookup()`, you set the environment variables, such as authentication information into the `Context`. You can use a hash table or a properties list for the environment. Then, this information is made available to the naming service when the `lookup()` is performed. The examples in this guide always use a Java `Hashtable`, as follows:

    Hashtable environment = new Hashtable();

Next, you set up properties in the hash table. You must always set the `Context` `URL_PKG_PREFIXES` property, whether you are on the client or server. The remaining properties are used for authentication, which primarily are used by clients or by a server authenticating itself as another user.

- `javax.naming.Context.URL_PKG_PREFIXES`

- `javax.naming.Context.SECURITY_PRINCIPAL`

- `javax.naming.Context.SECURITY_CREDENTIALS`

- `javax.naming.Context.SECURITY_ROLE`

- `javax.naming.Context.SECURITY_AUTHENTICATION`

- `USE_SERVICE_NAME`

#### URL_PKG_PREFIXES

`Context.URL_PKG_PREFIXES` holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories. The value of the property should be a colon-separated list of package prefixes for the class name of the factory class that will create a URL context factory.

In the current implementation, you must always supply this property in the Context environment, and it must be set to the String "`oracle.aurora.jndi`".

#### SECURITY_PRINCIPAL

`Context.SECURITY_PRINCIPAL` holds the database username.

#### SECURITY_CREDENTIALS

`Context.SECURITY_CREDENTIAL` holds the clear-text password. This is the Oracle database password for the SECURITY_PRINCIPAL (the database user). In all of the three authentication methods mentioned in SECURITY_AUTHENTICATION below, the password is encrypted when it is transmitted to the server.

#### SECURITY_ROLE

`Context.SECURITY_ROLE` holds the Oracle8i database role with which the user is connecting. For example, "CLERK" or "MANAGER".

#### SECURITY_AUTHENTICATION

`Context.SECURITY_AUTHENTICATION` holds the name of the environment property that specifies the type of authentication to use. Values for this property provide for the authentication types supported by Oracle8i. There are four possible values, which are defined in the `ServiceCtx` class:

- `ServiceCtx.NON_SSL_LOGIN`: The client authenticates itself to the server with a username and password using the Login protocol over a standard TCP/IP connection (not a secure socket layer connection). The Login protocol provides for encryption of the password as it is transmitted from the client to the server. The server does not authenticate itself to the client. See "Providing Username and Password for Client-Side Authentication" for more information about this protocol.

- `ServiceCtx.SSL_CREDENTIAL`: The client authenticates itself to the server providing a username and password that are encrypted over a secure socket layer (SSL) connection. The server authenticates itself to the client by providing credentials.

- `SSL_LOGIN`: The client authenticates itself to the server with a username and password within the Login protocol, over an SSL connection. The server does not authenticate itself to the client.

- `SSL_CLIENT_AUTH`: Both the client and the server authenticate themselves to each other by providing certificates to each other over an SSL connection.

  Note: To use an SSL connection, you must be able to access a listener that has an SSL port configured, and the listener must be able to redirect requests to an SSL-enabled database IIOP port. You must also include the following JAR files when you compile and build your application: If your client uses JDK 1.1, import `jssl-1_1.jar` and `javax-ssl-1_1.jar.` If your client uses Java 2, import `jssl-1_2.jar` and `javax-ssl-1_2.jar`.

#### USE_SERVICE_NAME

If you are using a service name instead of an SID in the URL, you set this property to true. Otherwise, the last string in the URL must contain the SID. Given a Hashtable within the variable, `env`, the following designates that the service name is used instead of the SID within the URL:

    Hashtable env = new Hashtable();
    env.put(Context.URL_PKG_PREFIXES, "oracle.aurora.jndi");
    env.put(Context.SECURITY_PRINCIPAL, "scott");
    env.put(Context.SECURITY_CREDENTIALS, "tiger");
    env.put(Context.SECURITY_AUTHENTICATION, ServiceCtx.NON_SSL_LOGIN);
    env.put("USE_SERVICE_NAME", "true");
    Context ic = new InitialContext(env);

The default is false.

The URL given within the lookup should contain a service name, instead of an SID. The following URL contains the service name, `orasun12`:

    myHello hello =

        (myHello) ic.lookup("sess_iiop://localhost:2481:orasun12/test/myHello");

#### The JNDI InitialContext Methods

`InitialContext` is a class in the `javax.naming` package that implements the `Context` interface. All naming operations are relative to a context. The initial context implements the `Context` interface and provides the starting point for resolution of names.

#### Constructor

You construct a new initial context using the constructor:

    public InitialContext(Hashtable environment)

It requires a `Hashtable` for the input parameter that contains the environment information described in "Retrieving the JNDI InitialContext" above. The following code fragment sets up an environment for a typical client, and creates a new initial context:

    Hashtable env = new Hashtable();
    env.put(Context.URL_PKG_PREFIXES, "oracle.aurora.jndi");
    env.put(Context.SECURITY_PRINCIPAL, "scott");
    env.put(Context.SECURITY_CREDENTIALS, "tiger");
    env.put(Context.SECURITY_AUTHENTICATION, ServiceCtx.NON_SSL_LOGIN);
    Context ic = new InitialContext(env);

#### lookup

This is the most common initial context class method that the CORBA or EJB application developer will use:

    public Object lookup(String URL)

You use `lookup()` to retrieve an object instance or to create a new service context.

- To retrieve an object instance, specify a URL for the service name and append the JNDI bound name (the session name). The returned result must be cast to the expected object type. For example, to retrieve the Hello interface, you would do the following:

      HelloHome hello_home =
          (HelloHome) ic.lookup("sess_iiop://localhost:2481:ORCL/test/myHello");
      myHello hello = hello_home.create ();

  The service name is "`sess_iiop://localhost:2481:ORCL`"; the JNDI bound name for Hello's home interface is "`/test/myHello`".

- To retrieve a handle to a specific namespace, specify the desired service context. The return result must be cast to `ServiceCtx` when a new service context is being created. For example, if `initContext` is a JNDI initial context, the following statement creates a new service context:

      ServiceCtx service =
          (ServiceCtx) initContext.lookup("sess_iiop://localhost:2481:ORCL");

See "Session Management Scenarios" for examples on how to use the JNDI `lookup` method within an EJB or CORBA application.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index