SimpleNamingContextBuilder (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.mock.jndi

## Class SimpleNamingContextBuilder

- java.lang.Object
- - org.springframework.mock.jndi.SimpleNamingContextBuilder

- All Implemented Interfaces:
    InitialContextFactoryBuilder

      public class SimpleNamingContextBuilder
      extends Object
      implements InitialContextFactoryBuilder

  Simple implementation of a JNDI naming context builder.

  Mainly targeted at test environments, where each test case can configure JNDI appropriately, so that `new InitialContext()` will expose the required objects. Also usable for standalone applications, e.g. for binding a JDBC DataSource to a well-known JNDI location, to be able to use traditional J2EE data access code outside of a J2EE container.

  There are various choices for DataSource implementations:

  - SingleConnectionDataSource (using the same Connection for all getConnection calls);
  - DriverManagerDataSource (creating a new Connection on each getConnection call);
  - Apache's Jakarta Commons DBCP offers BasicDataSource (a real pool).

  Typical usage in bootstrap code:

       SimpleNamingContextBuilder builder = new SimpleNamingContextBuilder();
       DataSource ds = new DriverManagerDataSource(...);
       builder.bind("java:comp/env/jdbc/myds", ds);
       builder.activate();

  Note that it's impossible to activate multiple builders within the same JVM, due to JNDI restrictions. Thus to configure a fresh builder repeatedly, use the following code to get a reference to either an already activated builder or a newly activated one:

       SimpleNamingContextBuilder builder = SimpleNamingContextBuilder.emptyActivatedContextBuilder();
       DataSource ds = new DriverManagerDataSource(...);
       builder.bind("java:comp/env/jdbc/myds", ds);

  Note that you should not call `activate()` on a builder from this factory method, as there will already be an activated one in any case.

  An instance of this class is only necessary at setup time. An application does not need to keep a reference to it after activation.

  Author:
    Juergen Hoeller, Rod Johnson
  See Also:
    `emptyActivatedContextBuilder()`, `bind(String, Object)`, `activate()`, `SimpleNamingContext`, `SingleConnectionDataSource`, `DriverManagerDataSource`, `BasicDataSource`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleNamingContextBuilder()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `activate()` Register the context builder by registering it with the JNDI NamingManager.
    `void` | `bind(String name, Object obj)` Bind the given object under the given name, for all naming contexts that this context builder will generate.
    `void` | `clear()` Clear all bindings in this context builder, while keeping it active.
    `InitialContextFactory` | `createInitialContextFactory(Hashtable<?,?> environment)` Simple InitialContextFactoryBuilder implementation, creating a new SimpleNamingContext instance.
    `void` | `deactivate()` Temporarily deactivate this context builder.
    `static SimpleNamingContextBuilder` | `emptyActivatedContextBuilder()` If no SimpleNamingContextBuilder is already configuring JNDI, create and activate one.
    `static SimpleNamingContextBuilder` | `getCurrentContextBuilder()` Checks if a SimpleNamingContextBuilder is active.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SimpleNamingContextBuilder

          public SimpleNamingContextBuilder()

  - ### Method Detail

    - #### getCurrentContextBuilder

          public static SimpleNamingContextBuilder getCurrentContextBuilder()

      Checks if a SimpleNamingContextBuilder is active.
      Returns:
        the current SimpleNamingContextBuilder instance, or `null` if none

    - #### emptyActivatedContextBuilder

          public static SimpleNamingContextBuilder emptyActivatedContextBuilder()
                                                                         throws NamingException

      If no SimpleNamingContextBuilder is already configuring JNDI, create and activate one. Otherwise take the existing activate SimpleNamingContextBuilder, clear it and return it.

      This is mainly intended for test suites that want to reinitialize JNDI bindings from scratch repeatedly.

      Returns:
        an empty SimpleNamingContextBuilder that can be used to control JNDI bindings
      Throws:
        `NamingException`

    - #### activate

          public void activate()
                        throws IllegalStateException,
                               NamingException

      Register the context builder by registering it with the JNDI NamingManager. Note that once this has been done, `new InitialContext()` will always return a context from this factory. Use the `emptyActivatedContextBuilder()` static method to get an empty context (for example, in test methods).
      Throws:
        `IllegalStateException` - if there's already a naming context builder registered with the JNDI NamingManager
        `NamingException`

    - #### deactivate

          public void deactivate()

      Temporarily deactivate this context builder. It will remain registered with the JNDI NamingManager but will delegate to the standard JNDI InitialContextFactory (if configured) instead of exposing its own bound objects.

      Call `activate()` again in order to expose this context builder's own bound objects again. Such activate/deactivate sequences can be applied any number of times (e.g. within a larger integration test suite running in the same VM).

      See Also:
        `activate()`

    - #### clear

          public void clear()

      Clear all bindings in this context builder, while keeping it active.

    - #### bind

          public void bind(String name,
                  Object obj)

      Bind the given object under the given name, for all naming contexts that this context builder will generate.
      Parameters:
        `name` - the JNDI name of the object (e.g. "java:comp/env/jdbc/myds")
        `obj` - the object to bind (e.g. a DataSource implementation)

    - #### createInitialContextFactory

          public InitialContextFactory createInitialContextFactory(Hashtable<?,?> environment)

      Simple InitialContextFactoryBuilder implementation, creating a new SimpleNamingContext instance.
      Specified by:
        `createInitialContextFactory` in interface `InitialContextFactoryBuilder`
      See Also:
        `SimpleNamingContext`