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

org.springframework.jms.support.destination

## Class JndiDestinationResolver

- java.lang.Object
- - org.springframework.jndi.JndiAccessor
  - - org.springframework.jndi.JndiLocatorSupport
    - - org.springframework.jms.support.destination.JndiDestinationResolver

- All Implemented Interfaces:
    CachingDestinationResolver, DestinationResolver

      public class JndiDestinationResolver
      extends JndiLocatorSupport
      implements CachingDestinationResolver

  `DestinationResolver` implementation which interprets destination names as JNDI locations (with a configurable fallback strategy).

  Allows for customizing the JNDI environment if necessary, for example specifying appropriate JNDI environment properties.

  Dynamic queues and topics get cached by destination name. As a consequence, you need to use unique destination names across both queues and topics. Caching can be turned off through the `"cache"` flag.

  Note that the fallback to resolution of dynamic destinations is turned off by default. Switch the `"fallbackToDynamicDestination"` flag on to enable this functionality.

  Since:
    1.1
  Author:
    Mark Pollack, Juergen Hoeller
  See Also:
    `JndiAccessor.setJndiTemplate(org.springframework.jndi.JndiTemplate)`, `JndiAccessor.setJndiEnvironment(java.util.Properties)`, `setCache(boolean)`, `setFallbackToDynamicDestination(boolean)`

- - ### Field Summary

    - ### Fields inherited from class org.springframework.jndi.JndiLocatorSupport

      `CONTAINER_PREFIX`

    - ### Fields inherited from class org.springframework.jndi.JndiAccessor

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JndiDestinationResolver()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearCache()` Clear the entire destination cache.
    `void` | `removeFromCache(String destinationName)` Remove the destination with the given name from the cache (if cached by this resolver in the first place).
    `Destination` | `resolveDestinationName(Session session, String destinationName, boolean pubSubDomain)` Resolve the given destination name, either as located resource or as dynamic destination.
    `void` | `setCache(boolean cache)` Set whether to cache resolved destinations.
    `void` | `setDynamicDestinationResolver(DestinationResolver dynamicDestinationResolver)` Set the `DestinationResolver` to use when falling back to dynamic destinations.
    `void` | `setFallbackToDynamicDestination(boolean fallbackToDynamicDestination)` Set whether this resolver is supposed to create dynamic destinations if the destination name is not found in JNDI.
    `protected void` | `validateDestination(Destination destination, String destinationName, boolean pubSubDomain)` Validate the given Destination object, checking whether it matches the expected type.

    - ### Methods inherited from class org.springframework.jndi.JndiLocatorSupport

      `convertJndiName, isResourceRef, lookup, lookup, setResourceRef`

    - ### Methods inherited from class org.springframework.jndi.JndiAccessor

      `getJndiEnvironment, getJndiTemplate, setJndiEnvironment, setJndiTemplate`

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

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

- - ### Constructor Detail

    - #### JndiDestinationResolver

          public JndiDestinationResolver()

  - ### Method Detail

    - #### setCache

          public void setCache(boolean cache)

      Set whether to cache resolved destinations. Default is "true".

      This flag can be turned off to re-lookup a destination for each operation, which allows for hot restarting of destinations. This is mainly useful during development.

      Note that dynamic queues and topics get cached by destination name. As a consequence, you need to use unique destination names across both queues and topics.

    - #### setFallbackToDynamicDestination

          public void setFallbackToDynamicDestination(boolean fallbackToDynamicDestination)

      Set whether this resolver is supposed to create dynamic destinations if the destination name is not found in JNDI. Default is "false".

      Turn this flag on to enable transparent fallback to dynamic destinations.

      See Also:
        `setDynamicDestinationResolver(org.springframework.jms.support.destination.DestinationResolver)`

    - #### setDynamicDestinationResolver

          public void setDynamicDestinationResolver(DestinationResolver dynamicDestinationResolver)

      Set the `DestinationResolver` to use when falling back to dynamic destinations.

      The default is Spring's standard `DynamicDestinationResolver`.

      See Also:
        `setFallbackToDynamicDestination(boolean)`, `DynamicDestinationResolver`

    - #### resolveDestinationName

          public Destination resolveDestinationName(Session session,
                                           String destinationName,
                                           boolean pubSubDomain)
                                             throws JMSException

      Description copied from interface: `DestinationResolver`
      Resolve the given destination name, either as located resource or as dynamic destination.
      Specified by:
        `resolveDestinationName` in interface `DestinationResolver`
      Parameters:
        `session` - the current JMS Session (may be `null` if the resolver implementation is able to work without it)
        `destinationName` - the name of the destination
        `pubSubDomain` - `true` if the domain is pub-sub, `false` if P2P
      Returns:
        the JMS destination (either a topic or a queue)
      Throws:
        `JMSException` - if the JMS Session failed to resolve the destination

    - #### validateDestination

          protected void validateDestination(Destination destination,
                                 String destinationName,
                                 boolean pubSubDomain)

      Validate the given Destination object, checking whether it matches the expected type.
      Parameters:
        `destination` - the Destination object to validate
        `destinationName` - the name of the destination
        `pubSubDomain` - `true` if a Topic is expected, `false` in case of a Queue

    - #### removeFromCache

          public void removeFromCache(String destinationName)

      Description copied from interface: `CachingDestinationResolver`
      Remove the destination with the given name from the cache (if cached by this resolver in the first place).

      To be called if access to the specified destination failed, assuming that the JMS Destination object might have become invalid.

      Specified by:
        `removeFromCache` in interface `CachingDestinationResolver`
      Parameters:
        `destinationName` - the name of the destination

    - #### clearCache

          public void clearCache()

      Description copied from interface: `CachingDestinationResolver`
      Clear the entire destination cache.

      To be called in case of general JMS provider failure.

      Specified by:
        `clearCache` in interface `CachingDestinationResolver`