org.jpu.patterns.serviceLocator
Class Locator

java.lang.Object
  org.jpu.patterns.serviceLocator.Locator

All Implemented Interfaces:

ILocator

Direct Known Subclasses:

DataSourceLocator, HomeLocator, QueueCFLocator, QueueLocator, SLSBLocator, TopicCFLocator, TopicLocator, UserTransactionLocator, XAQueueCFLocator

public class Locator

extends java.lang.Object

implements ILocator

Implementation of the ILocator interface. See its documentation for more info.

Nested Class Summary

class	Locator.DefaultIdentifierParser
static class	Locator.DefaultLookupStrategy Simple lookup strategy implementation based on "new InitialContext(System.getProperties()).lookup()".
static class	Locator.DefaultNarrowStrategy Simple narrow strategy implementation based on "PortableRemoteObject.narrow()".
static class	Locator.NullCache Simple cache implementation based on HashMap.

Nested classes inherited from class org.jpu.patterns.serviceLocator.ILocator

ILocator.ICache, ILocator.IIdentifierParser, ILocator.ILookupStrategy, ILocator.INarrowStrategy

Constructor Summary

Locator()

Method Summary

void	clearCache() Removes all items from the cache.
ILocator.ICache	getCache() Returns the cache.
java.lang.Class	getDefaultCast() By default returns null, but subclasses can override to return the Class that should be passed as the second parameter to narrow(Object,Class) if no class is passed via the castTo attribute of the ServiceLocatorOptions instance.
ILocator.ILookupStrategy	getLookupStrategy() Returns the current ILocator.ILookupStrategy.
ILocator.INarrowStrategy	getNarrowStrategy() Returns the current ILocator.INarrowStrategy.
java.lang.Object	getObject(java.lang.String namingIdentifier) Convenience alias for "getObject(namingIdentifier, (ServiceLocatorOptions)null)".
java.lang.Object	getObject(java.lang.String namingIdentifier, java.lang.Class c) Convenience alias for "getObject( namingIdentifier, new ServiceLocatorOptions().setCastTo(c) )".
java.lang.Object	getObject(java.lang.String namingIdentifier, ServiceLocatorOptions options) Attempts to find the object with the given JNDI name using the given options.
java.lang.Object	lookup(java.lang.String namingIdentifier, ServiceLocatorOptions options) Simply calls "getLookupStrategy().lookup(namingIdentifier, options)".
java.lang.Object	narrow(java.lang.Object o, java.lang.Class c) Simply calls "getNarrowStrategy().narrow(o, c)".
java.lang.Object	narrow(java.lang.Object o, ServiceLocatorOptions options) If options.castTo is not null, call narrow(Object,Class) variant to narrow the given object to this type and return the result; else if getDefaultCast() is not null, call narrow(Object,Class) variant to narrow to this type and return the result; else return the original object passed via "o".
ILocator.ICache	newCache() By default instantiates a Locator.NullCache, but subclasses can override to supply their own cache implementation.
ILocator.IIdentifierParser	newIdentifier(java.lang.String str, java.util.Properties props)
ILocator.ILookupStrategy	newLookupStrategy() By default instantiates a Locator.DefaultLookupStrategy, but subclasses can override to supply their own ILocator.ILookupStrategy implementation.
ILocator.INarrowStrategy	newNarrowStrategy() By default instantiates a Locator.DefaultNarrowStrategy, but subclasses can override to supply their own ILocator.INarrowStrategy implementation.
void	removeFromCache(java.lang.String namingIdentifier) Removes the object with the specified JNDI name from the cache.
void	setCache(ILocator.ICache cache) Sets the cache, replacing the previous cache (and hence causing loss of previously cached objects).
void	setLookupStrategy(ILocator.ILookupStrategy ls) Sets the ILocator.ILookupStrategy, replacing the previous one.
void	setNarrowStrategy(ILocator.INarrowStrategy ls) Sets the ILocator.INarrowStrategy, replacing the previous one.

Methods inherited from class java.lang.Object

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

Constructor Detail

Locator

public Locator()

Method Detail

newIdentifier

public ILocator.IIdentifierParser newIdentifier(java.lang.String str,
                                                java.util.Properties props)
                                         throws InvalidIdentifierException

Throws:

InvalidIdentifierException

getObject

public java.lang.Object getObject(java.lang.String namingIdentifier)
                           throws ServiceLocatorException

Description copied from interface: ILocator

Convenience alias for "getObject(namingIdentifier, (ServiceLocatorOptions)null)". See ILocator.getObject(String, ServiceLocatorOptions).

Specified by:

getObject in interface ILocator

Throws:

ServiceLocatorException

removeFromCache

public void removeFromCache(java.lang.String namingIdentifier)

Description copied from interface: ILocator

Removes the object with the specified JNDI name from the cache.

Specified by:

removeFromCache in interface ILocator

clearCache

public void clearCache()

Description copied from interface: ILocator

Removes all items from the cache.

Specified by:

clearCache in interface ILocator

getObject

public java.lang.Object getObject(java.lang.String namingIdentifier,
                                  java.lang.Class c)
                           throws ServiceLocatorException

Description copied from interface: ILocator

Convenience alias for "getObject( namingIdentifier, new ServiceLocatorOptions().setCastTo(c) )". See ILocator.getObject(String, ServiceLocatorOptions).

Specified by:

getObject in interface ILocator

Throws:

ServiceLocatorException

getObject

public java.lang.Object getObject(java.lang.String namingIdentifier,
                                  ServiceLocatorOptions options)
                           throws ServiceLocatorException

Description copied from interface: ILocator

Attempts to find the object with the given JNDI name using the given options.

The method first checks the cache for an object with the given JNDI name, unless options.noCache is true in which case the cache is bypassed. If the object is not in the cache or the cache is being bypassed, the method will attempt to find the object using the protected lookup() method (which subclasses can override). Any exception thrown from that method will be allowed to propagate from this method. Any object found through JNDI is automatically entered into the cache via its public put() method.

If the object is found, either in the cache or via JNDI lookup, then if a narrow type is defined, either via options.castTo or ILocator.getDefaultCast(), the method will attempt to narrow the object to that type using the protected narrow() method (which subclasses are free to override). Narrow's default implementation uses PortableRemoteObject.narrow().

If the named object cannot be found, or if the narrow fails, ServiceLocatorException is thrown wrapping the underlying JNDI exception.

Specified by:

getObject in interface ILocator

Throws:

ServiceLocatorException

setCache

public void setCache(ILocator.ICache cache)

Description copied from interface: ILocator

Sets the cache, replacing the previous cache (and hence causing loss of previously cached objects).

Specified by:

setCache in interface ILocator

getCache

public ILocator.ICache getCache()

Description copied from interface: ILocator

Returns the cache. The returned object is unsynchronized, so the caller should synchronize on "this" while querying or modifying it.

Specified by:

getCache in interface ILocator

setNarrowStrategy

public void setNarrowStrategy(ILocator.INarrowStrategy ls)

Description copied from interface: ILocator

Sets the ILocator.INarrowStrategy, replacing the previous one.

Specified by:

setNarrowStrategy in interface ILocator

getNarrowStrategy

public ILocator.INarrowStrategy getNarrowStrategy()

Description copied from interface: ILocator

Returns the current ILocator.INarrowStrategy.

Specified by:

getNarrowStrategy in interface ILocator

setLookupStrategy

public void setLookupStrategy(ILocator.ILookupStrategy ls)

Description copied from interface: ILocator

Sets the ILocator.ILookupStrategy, replacing the previous one.

Specified by:

setLookupStrategy in interface ILocator

getLookupStrategy

public ILocator.ILookupStrategy getLookupStrategy()

Description copied from interface: ILocator

Returns the current ILocator.ILookupStrategy.

Specified by:

getLookupStrategy in interface ILocator

newCache

public ILocator.ICache newCache()

Description copied from interface: ILocator

By default instantiates a Locator.NullCache, but subclasses can override to supply their own cache implementation.

Specified by:

newCache in interface ILocator

newLookupStrategy

public ILocator.ILookupStrategy newLookupStrategy()

Description copied from interface: ILocator

By default instantiates a Locator.DefaultLookupStrategy, but subclasses can override to supply their own ILocator.ILookupStrategy implementation.

Specified by:

newLookupStrategy in interface ILocator

newNarrowStrategy

public ILocator.INarrowStrategy newNarrowStrategy()

Description copied from interface: ILocator

By default instantiates a Locator.DefaultNarrowStrategy, but subclasses can override to supply their own ILocator.INarrowStrategy implementation.

Specified by:

newNarrowStrategy in interface ILocator

narrow

public java.lang.Object narrow(java.lang.Object o,
                               ServiceLocatorOptions options)
                        throws ServiceLocatorException

Description copied from interface: ILocator

If options.castTo is not null, call narrow(Object,Class) variant to narrow the given object to this type and return the result; else if ILocator.getDefaultCast() is not null, call narrow(Object,Class) variant to narrow to this type and return the result; else return the original object passed via "o".

Specified by:

narrow in interface ILocator

Throws:

ServiceLocatorException

narrow

public java.lang.Object narrow(java.lang.Object o,
                               java.lang.Class c)
                        throws ServiceLocatorException

Description copied from interface: ILocator

Simply calls "getNarrowStrategy().narrow(o, c)". If you wish to change the way narrowing is performed, write your own ILocator.INarrowStrategy and either override ILocator.newNarrowStrategy() to instantiate it, or call the public ILocator.setNarrowStrategy(ILocator.INarrowStrategy) method to replace the existing strategy.

Specified by:

narrow in interface ILocator

Throws:

ServiceLocatorException

lookup

public java.lang.Object lookup(java.lang.String namingIdentifier,
                               ServiceLocatorOptions options)
                        throws ServiceLocatorException

Simply calls "getLookupStrategy().lookup(namingIdentifier, options)". If you wish to change the way lookups are performed, write your own ILocator.ILookupStrategy and either override newLookupStrategy() to instantiate it, or call the public setLookupStrategy(ILocator.ILookupStrategy) method to replace the existing lookup strategy.

Throws:

ServiceLocatorException

getDefaultCast

public java.lang.Class getDefaultCast()

Description copied from interface: ILocator

By default returns null, but subclasses can override to return the Class that should be passed as the second parameter to ILocator.narrow(Object,Class) if no class is passed via the castTo attribute of the ServiceLocatorOptions instance. If both castTo and the return value of this method are null, no cast is performed.

Specified by:

getDefaultCast in interface ILocator