Creating an Initial Context (SAP Library - Developing Java EE 5 Applications)

Creating an Initial Context

Use

The initial context is the starting point for all naming operations as all methods on naming and directory services are performed relative to some context. To access objects in the JNDI Registry Service naming system, you have to create an initial context instance.

Creating an initial context depends on the type of the client. The following categories of clients exist:

● External (remote) clients – standalone Java applications, which connect to the Java instance using a remote protocol.

● Server-side clients running on the Java instance – Java EE applications, which can be using JNDI either from the same server process, or from another Java instance or AS Java cluster.

Procedure

Creating Initial Context from an External Client

To establish the connection between client and server, you have to add the JAR files located in usr\sap\<sid>\<instance_id>\j2ee\j2eeclient\. In the client class path, add the following JAR files:

sap.com~tc~exception~impl.jar

sap.com~tc~logging~java~impl.jar

sap.com~tc~je~clientlib~impl.jar

As an external client, you have to use the InitialContext constructor with a Hashtable as a parameter, which contains environment properties specifying the connection details that should be used by the system in the context creation.

To create an initial context that provides client access to the JNDI Registry Service of the AS Java as a name service provider, you have to perform the following steps:

...

1. Specify the initial context factory class name as a value to the following environment property:

Context.INITIAL_CONTEXT_FACTORY or its string representation:java.naming.factory.initial

To connect to the JNDI Registry Service, you have to use the following initial context factory class name: com.sap.engine.services.jndi.InitialContextFactoryImpl.

Note

If you do not specify this property, the initial context creation fails with a NamingException.

2. Specify the provider URL as a value to the following environment property:

Context.PROVIDER_URL or its string representationjava.naming.provider.url.

Note

If you do not specify this property, the initial context creation fails with a NamingException.

Connection from the client to the naming system can be made either via the message server of the AS Java cluster or via the Internet Communication Manager (ICM) of the targeted Java instance. In both cases, the connection is via P4 protocol.

○ Connection via the ICM: the client sends a new initial context request to the ICM, which balances the load and redirects the request to one of the server processes in the Java instance. As a result, the client establishes a connection to one of the server processes via the ICM. This connection is later used for performing various JNDI operations over the returned initial context.

In the provider URL in this case, include the ICM host and P4 port: <icm_host>:<P4_port>.

This graphic is explained in the accompanying text

○ Connection via the Message Server: the client requests connection information about all available Java instances in the cluster from the message server. The JNDI Registry Service chooses a Java instance and sends a new initial context request to its ICM. Then the ICM redirects the request to one of the available server processes.

In the provider URL, define the message server host and HTTP port: <ms_host>:<ms_http_port>.

This graphic is explained in the accompanying text

There are a number of additional RMI-P4 specific InitialContext properties. More information: RMI-P4 Specific InitialContext Properties.

3. You can use the following properties to authenticate the user that will be using the naming service:

○ Context.SECURITY_PRINCIPAL or its string representation java.naming.security.principal - specifies the identity of the principal (user) for security purposes.

○ Context.SECURITY_CREDENTIALS or its string representation java.naming.security.credentials - specifies the password for the principal.

To perform naming operations that require authentication or access control, the principal is associated with the thread, which gets the new initial context and is disassociated when close () method is called for this context. When a thread is associated with a principal, the principal becomes default for the thread so if any contexts are created by the same thread without principal or credential properties, the principal associated with the thread remains unchanged. If a new thread is started from the current one, the principal associated with the parent thread is propagated to the child thread also. A thread may be associated with only one principal at a time. If a single thread creates several contexts without closing any contexts, the thread will be associated with the principal that was used for the creation of the last context.

Note

java.naming.security.principal and java.naming.security.credentials can be omitted. If you do not specify these properties, the user is logged on as Guest. This means that the lookup operation itself as well as all the operations performed over the objects returned by the lookup executions will be performed with the permissions configured for the Guest user. However, this is valid only for the default configuration of the JNDI Registry Service security roles.

More information: User Authentication and Single Sign-On

Syntax

Context ctx = null;

Hashtable env = new Hashtable();

env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sap.engine.services.jndi.InitialContextFactoryImpl");

env.put(Context.PROVIDER_URL, "localhost:50004");

env.put(Context.SECURITY_PRINCIPAL, "MyUserName");

env.put(Context.SECURITY_CREDENTIALS, "MyPassword");

try {

ctx = new InitialContext(env);

} catch (NamingException ne) {

ne.printStackTrace()

} finally {

try {

ctx.close();

} catch (Exception e) {

e.printStackTrace()

}

○ sap.security.policy.configuration - specifies the name of a custom policy configuration to be used in the authentication of the user performing a new InitialContext operation. If this property is not specified, the authentication of the user is made according to the default policy configuration of the naming service. Using a custom policy configuration requires using also a custom security callback handler.

○ sap.security.callback.handler - specifies the implementation of desired security callback handler object that should be used during the login to the server. If you do not specify the callback handler implementation explicitly, the JNDI Registry Service will use the default one. In addition to setting this property to the InitialContext, you have to adjust the corresponding login module stack that the naming service uses during the authentication process. More information: Remote Authentication.

If custom callback handler has to be used, add the following property:

Syntax

Context ctx = null;

Hashtable env = new Hashtable();

env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sap.engine.services.jndi.InitialContextFactoryImpl");

env.put(Context.PROVIDER_URL, "localhost:50004");

env.put("javax.security.auth.callback", CallbackHandlerImpl);

try {

ctx = new InitialContext(env);

} catch (NamingException ne) {

ne.printStackTrace()

} finally {

try {

ctx.close();

} catch (Exception e) {

e.printStackTrace()

}

Creating Initial Context from a Client Running on the Same Server Process

Server-side clients that are running on the same server process do not need to specify any properties.

Use the InitialContext constructor without parameters:

Syntax

Context ctx = new InitialContext();

Recommendation

We recommend that you do not specify any environment properties. The context will always be created by the JNDI Registry Service of the same server process.

This is the typical initial context creation pattern for Java EE 5 applications and other server-side components.

Creating Initial Context from a Client Running on Another Server Process

A client that is running on a certain server process in an AS Java cluster can obtain a context to the naming system of another cluster or instance:

1. Specify the provider URL as a value of the following environment property:

Context.PROVIDER_URL or its string representationjava.naming.provider.url

The connection can be made to the naming system either via the message server of the AS Java cluster or via the ICM of the targeted Java instance. Depending on the connection information provided by the provider URL, the value string has to contain one of the following:

○ The message server host and HTTP port: <ms_host>:<ms_http_port>

○ The ICM host and p4 port: <icm_host>:<p4_port>

2. Set an AS Java-specific property with name “force_remote” and value “true”. If it is not specified, the context instance returned will give you access to the local server process naming system and the provider URL, if specified, will be ignored.

Syntax

Context ctx = null;

Hashtable env = new Hashtable();

env.put(Context.PROVIDER_URL, "10.55.161.251:50004");

env.put("force_remote", "true");

env.put(Context.SECURITY_PRINCIPAL, "MyUserName");

env.put(Context.SECURITY_CREDENTIALS, "MyPassword");

try {

ctx = new InitialContext(env);

} catch (NamingException ne) {

e.printStackTrace();

}

Caution

The MyUserName and MyPassword entries in the example above are the values that the application user passes to the application through an HTTP call, for example. Never hard code the values for the actual user name and corresponding password.

In this case, the application behaves like an external (remote) client for the JNDI Registry Service of the foreign Java instance or AS Java cluster.

Note

The provider URL is mandatory; otherwise the initial context creation fails with a NamingException.

The context that the client gets as a result of the new initial context call gives access to the root context of the naming system on a server process of the foreign AS Java instance or cluster.