org.jpu.patterns.serviceLocator
Interface ILocator

All Known Subinterfaces:

IDataSourceLocator, IHomeLocator, IQueueCFLocator, IQueueLocator, ISLSBLocator, ITopicCFLocator, ITopicLocator, IUserTransactionLocator, IXAQueueCFLocator

All Known Implementing Classes:

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

public interface ILocator

Base class for all the locators in this package. These classes are extensible service locators that obtain--and optionally cache--references to various J2EE objects such as session beans, home objects, and data sources. They can also handle narrowing as appropriate and repackage the J2EE exceptions into a ServiceLocatorException.

In general these locators will just hand you the object you want and from there it's up to you; however, SLSBLocator will also use reflection to call the create() method, which (because the EJB is stateless) takes no arguments, and give you a reference to the SLSB itself, rather than its home. The EJB's remote reference, rather than its home, will then be returned (and optionally cached for subsequent requests).

The locators in this package are not implemented as singletons, in order to minimize assumptions about the application in which they are used and allow the developer to maintain locator instances any way he chooses. However, in the subpackage org.jpu.patterns.serviceLocator.onePerContext are versions that use the OnePerContextManager facility and define appropriate public getInstance() methods as described in OnePerContextManager. You can use these just like you would a traditional singleton, or you can supply an optional "context" parameter to the getInstance() calls.

The ServiceLocatorOptions class can be used by the client to govern the behavior of the public methods with respect to a single lookup. Among other options, the client can indicate that the lookup should bypass the cache.

Strategies
By default the actual JNDI lookup is based on "InitialContext.lookup()", but you can change this by supplying your own ILocator.ILookupStrategy via setLookupStrategy(org.jpu.patterns.serviceLocator.ILocator.ILookupStrategy).

The default caching implementation is a "null" cache, which does no caching, but you can change this by supplying your own ILocator.ICache via setCache(org.jpu.patterns.serviceLocator.ILocator.ICache).

The default approach to narrowing is based on PortableRemoteObject.narrow(), but you can change this by supplying your own ILocator.INarrowStrategy via setNarrowStrategy(org.jpu.patterns.serviceLocator.ILocator.INarrowStrategy).

InitialContext Properties
For JNDI-based lookups, the caller must always specify the JNDI name to be passed to InitialContext.lookup(). In addition, these service locators give you the option of explicitly specifying a naming provider URL, initial context factory, or any other properies interpreted by InitialContext. You can do this either by explicitly adjusting the Properties instance associated with the ILocator.ILookupStrategy (which would affect all lookups performed by that strategy), or by using the following special syntax for the naming identifiers (which only affects a single lookup operation):

 jndiName{;name=value}*
 

where name is a property name and value is its value. Here is an example illustrating an LDAP lookup:

 
 MyQueue;java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory;java.naming.provider.url=ldap://ldap.foo.com:389/ou=myqueues,o=foo.com,c=us
 
 

Thus these service locators allow your application to reference objects defined in any number of different naming directories and refer to all these objects via simple strings. Of course these strings would normally reside in an external configuration source.

Properties passed using the above syntax override any settings in the ILocator.ILookupStrategy's Properties instance, which in turn override any "java.naming" system properties.

Nested Class Summary

static interface	ILocator.ICache Defines the interface that the cache must fulfill.
static interface	ILocator.IIdentifierParser
static interface	ILocator.ILookupStrategy Defines the interface for strategies that perform the actual lookup of objects (usually but not necessarily using JNDI).
static interface	ILocator.INarrowStrategy Defines the interface for strategies that narrow objects.

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	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 Locator.narrow(Object,Class) variant to narrow the given object to this type and return the result; else if getDefaultCast() is not null, call Locator.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.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.

Method Detail

removeFromCache

public void removeFromCache(java.lang.String namingIdentifier)

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

clearCache

public void clearCache()

Removes all items from the cache.

getObject

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

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

Throws:

ServiceLocatorException

getObject

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

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

Throws:

ServiceLocatorException

getObject

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

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 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.

Throws:

ServiceLocatorException

setCache

public void setCache(ILocator.ICache cache)

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

getCache

public ILocator.ICache getCache()

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

setNarrowStrategy

public void setNarrowStrategy(ILocator.INarrowStrategy ls)

Sets the ILocator.INarrowStrategy, replacing the previous one.

getNarrowStrategy

public ILocator.INarrowStrategy getNarrowStrategy()

Returns the current ILocator.INarrowStrategy.

setLookupStrategy

public void setLookupStrategy(ILocator.ILookupStrategy ls)

Sets the ILocator.ILookupStrategy, replacing the previous one.

getLookupStrategy

public ILocator.ILookupStrategy getLookupStrategy()

Returns the current ILocator.ILookupStrategy.

newCache

public ILocator.ICache newCache()

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

newLookupStrategy

public ILocator.ILookupStrategy newLookupStrategy()

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

newNarrowStrategy

public ILocator.INarrowStrategy newNarrowStrategy()

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

narrow

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

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

Throws:

ServiceLocatorException

narrow

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

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

Throws:

ServiceLocatorException

getDefaultCast

public 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. If both castTo and the return value of this method are null, no cast is performed.