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

org.springframework.jndi

## Class JndiTemplate

- java.lang.Object
- - org.springframework.jndi.JndiTemplate

- Direct Known Subclasses:
    ExpectedLookupTemplate

      public class JndiTemplate
      extends Object

  Helper class that simplifies JNDI operations. It provides methods to lookup and bind objects, and allows implementations of the `JndiCallback` interface to perform any operation they like with a JNDI naming context provided.
  Author:
    Rod Johnson, Juergen Hoeller
  See Also:
    `JndiCallback`, `execute(org.springframework.jndi.JndiCallback<T>)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JndiTemplate()` Create a new JndiTemplate instance.
    `JndiTemplate(Properties environment)` Create a new JndiTemplate instance, using the given environment.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `bind(String name, Object object)` Bind the given object to the current JNDI context, using the given name.
    `protected Context` | `createInitialContext()` Create a new JNDI initial context.
    `<T> T` | `execute(JndiCallback<T> contextCallback)` Execute the given JNDI context callback implementation.
    `Context` | `getContext()` Obtain a JNDI context corresponding to this template's configuration.
    `Properties` | `getEnvironment()` Return the environment for the JNDI InitialContext, if any.
    `Object` | `lookup(String name)` Look up the object with the given name in the current JNDI context.
    `<T> T` | `lookup(String name, Class<T> requiredType)` Look up the object with the given name in the current JNDI context.
    `void` | `rebind(String name, Object object)` Rebind the given object to the current JNDI context, using the given name.
    `void` | `releaseContext(Context ctx)` Release a JNDI context as obtained from `getContext()`.
    `void` | `setEnvironment(Properties environment)` Set the environment for the JNDI InitialContext.
    `void` | `unbind(String name)` Remove the binding for the given name from the current JNDI context.

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

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

- - ### Field Detail

    - #### logger

          protected final Log logger

  - ### Constructor Detail

    - #### JndiTemplate

          public JndiTemplate()

      Create a new JndiTemplate instance.

    - #### JndiTemplate

          public JndiTemplate(Properties environment)

      Create a new JndiTemplate instance, using the given environment.

  - ### Method Detail

    - #### setEnvironment

          public void setEnvironment(Properties environment)

      Set the environment for the JNDI InitialContext.

    - #### getEnvironment

          public Properties getEnvironment()

      Return the environment for the JNDI InitialContext, if any.

    - #### execute

          public <T> T execute(JndiCallback<T> contextCallback)
                    throws NamingException

      Execute the given JNDI context callback implementation.
      Parameters:
        `contextCallback` - JndiCallback implementation
      Returns:
        a result object returned by the callback, or `null`
      Throws:
        `NamingException` - thrown by the callback implementation
      See Also:
        `createInitialContext()`

    - #### getContext

          public Context getContext()
                             throws NamingException

      Obtain a JNDI context corresponding to this template's configuration. Called by `execute(org.springframework.jndi.JndiCallback<T>)`; may also be called directly.

      The default implementation delegates to `createInitialContext()`.

      Returns:
        the JNDI context (never `null`)
      Throws:
        `NamingException` - if context retrieval failed
      See Also:
        `releaseContext(javax.naming.Context)`

    - #### releaseContext

          public void releaseContext(Context ctx)

      Release a JNDI context as obtained from `getContext()`.
      Parameters:
        `ctx` - the JNDI context to release (may be `null`)
      See Also:
        `getContext()`

    - #### createInitialContext

          protected Context createInitialContext()
                                          throws NamingException

      Create a new JNDI initial context. Invoked by `getContext()`.

      The default implementation use this template's environment settings. Can be subclassed for custom contexts, e.g. for testing.

      Returns:
        the initial Context instance
      Throws:
        `NamingException` - in case of initialization errors

    - #### lookup

          public Object lookup(String name)
                        throws NamingException

      Look up the object with the given name in the current JNDI context.
      Parameters:
        `name` - the JNDI name of the object
      Returns:
        object found (cannot be `null`; if a not so well-behaved JNDI implementations returns null, a NamingException gets thrown)
      Throws:
        `NamingException` - if there is no object with the given name bound to JNDI

    - #### lookup

          public <T> T lookup(String name,
                     Class<T> requiredType)
                   throws NamingException

      Look up the object with the given name in the current JNDI context.
      Parameters:
        `name` - the JNDI name of the object
        `requiredType` - type the JNDI object must match. Can be an interface or superclass of the actual class, or `null` for any match. For example, if the value is `Object.class`, this method will succeed whatever the class of the returned instance.
      Returns:
        object found (cannot be `null`; if a not so well-behaved JNDI implementations returns null, a NamingException gets thrown)
      Throws:
        `NamingException` - if there is no object with the given name bound to JNDI

    - #### bind

          public void bind(String name,
                  Object object)
                    throws NamingException

      Bind the given object to the current JNDI context, using the given name.
      Parameters:
        `name` - the JNDI name of the object
        `object` - the object to bind
      Throws:
        `NamingException` - thrown by JNDI, mostly name already bound

    - #### rebind

          public void rebind(String name,
                    Object object)
                      throws NamingException

      Rebind the given object to the current JNDI context, using the given name. Overwrites any existing binding.
      Parameters:
        `name` - the JNDI name of the object
        `object` - the object to rebind
      Throws:
        `NamingException` - thrown by JNDI

    - #### unbind

          public void unbind(String name)
                      throws NamingException

      Remove the binding for the given name from the current JNDI context.
      Parameters:
        `name` - the JNDI name of the object
      Throws:
        `NamingException` - thrown by JNDI, mostly name not found