The naming package includes two JNDI service providers. One is an in-memory namespace provider. The typical use for an in-memory namespace is listing non-persistenct objects such as connection factories, active services, etc. The other is a JNDI environment naming context (ENC) implementation for the purpose of exposing the environment naming space to a J2EE application. It provides an in-memory, read-only, serializable context implementation. The in-memory namespace is used to populate the ENC for the currently running component.

tyrex.naming.MemoryContext is an in-memory JNDI service provider. Binds objects into a namespace held entirely in memory, supporting serializable, remoteable and local objects. The in-memory service provider is particularly useful for holding resource factories (the JNDI ENC) and exposing run-time services and configuration objects.

An instance of tyrex.naming.MemoryContext constructed with no environment attribute will use it's namespace and serve as the root of that namespace. Such a namespace is no accessible except through the creating context, and is garbage collected when all such contexts are no longer referenced. If necessary the root context can be duplicated using lookup( "" ).

If the environment attribute {@link Context.PROVIDER_URL} is set, the context will reference a node in a namespace shared by all such contexts. That tree is statically held in memory for the life time of the virtual machine.

tyrex.naming.MemoryContextFactory implements a context factory for tyrex.naming.MemoryContext. When set properly the InitialContext will return a tyrex.naming.MemoryContext referencing the named path in the shared memory space. If the PROVIDER_URL property is not set, a new context with with it's own namespace will be created.

To use the memory context from an InitialContext set the INITIAL_CONTEXT_FACTORY and PROVIDER_URL environment attributes as follows:

Hashtable env;
Conetxt   ctx;

// Make ctx points to a path within the shared space
env = new Hashtable();
env.put( Context.INITIAL_CONTEXT_FACTORY, 
         "tyrex.naming.MemoryContextFactory" );
env.put( Context.PROVIDER_URL, path );
ctx = new InitialContext( env );

// Make ctx the root of a private namespace
env = new Hashtable();
env.put( Context.INITIAL_CONTEXT_FACTORY, 
         "tyrex.naming.MemoryContextFactory" );
ctx = new InitialContext( env );
      

By default a memory context is read-write. You may set a context to read only, causing all context returns from that context to be read-only as well. However, other contexts obtained for the same path will be read-write. This functionality enables the application to pass a read-only view of it's namespace and continue updating it. The environment attribute readOnly can be set to make a context read-only.

In order to access a shared namespace the application must have the adequate permission tyrex.naming.NamingPermission "shared". No permission is necessary to create or access a private namespace.

tyrex.naming.EnvContext is an environment naming context implementation (ENC). This is a read only, serializable, bound-to-thread JNDI service provider that implements the full J2EE requirements. This object is also used to set the contents of the ENC for the current thread.

This context is not constructed directly but generally through the application performing a URL lookup on the java: namespace. Such requests are materizlied through tyrex.naming.java.javaURLContextFactory which directs them to an instance of tyrex.naming.java.JavaContext. The JNDI properties have to be properly configured with the property java.naming.factory.url.pkgs=tyrex.naming to enable InitialContext to work transparently for the application.

To comply with J2EE requirements, the environment context is a read-only namespace, heirarchial and supporting links, can bind non-persistent objects (like factories, services), and can be serialized as part of a bean's activation/passivation.

The runtime context is used to populate the ENC and associate it with the current running thread, see tyrex.tm.RuntimeContext for more details.

The following example places an instance of UserTransaction and a JDBC connector adaptor in the ENC of the current thread:

Context        root;
Context        ctx;
RuntimeContext runCtx;

// Construct a non-shared memory context
root = new MemoryContext();
// Create comp/UserTransaction and comp/env/mydb
ctx = root.createSubcontext( "comp" );
ctx.bind( "UserTransaction", ut );
ctx = ctx.createSubcontext( "env" );
ctx = ctx.createSubcontext( "jdbc" );
ctx = ctx.bind( "mydb", jdbcAdapter );

. . .
// Associate the memory context with a new
// runtime context and associate the runtime context
// with the current thread
runCtx = RuntimeContext.newRuntimeContext( root, null );
RuntimeContext.setRuntimeContext( runCtx );

. . .
// Application code
InitialContext ctx;

ctx = new InitialContext();
ds = (DataSource) ctx.lookup( "java:comp/env/jdbc/mydb" );
. . .

// Dissociate the runtime context from the thread
RuntimeContext.unsetRuntimeContext();
      

In order to set the naming context for the current thread the application must have the adequate permission tyrex.naming.NamingPermission "enc". No permission is necessary to access the namespace using the java: URL.