BeanContext to provide services to its children.
*
* @specnote it is unclear whether a BeanContextServices
* should delegate unhandled requests to parents. I assume so.
* @author John Keiser
* @since 1.2
*/
public interface BeanContextServices
extends BeanContext, BeanContextServicesListener
{
/**
* Register a service to make it available to others.
* This class may refuse to add the service based on whatever
* information it can gather, including whether the service
* provider is trusted.
*
* @param serviceClass the service class.
* @param provider the factory that will actually provide the service.
* @return whether the service was added or not.
*/
boolean addService (Class serviceClass,
BeanContextServiceProvider provider);
/**
* Make it so that no one else can use this service.
*
*
* If revokeNow is false, the only
* effect of this method is to make all subsequent calls to
* getService() on this service class fail.
*
*
* If it is true, a message is also sent out to all
* listeners on the service and all references to it are released.
*
* @param serviceClass the service class to revoke.
* @param provider the service provider providing the service class.
* @param revokeNow whether to release all current references to
* the service.
*/
void revokeService (Class serviceClass,
BeanContextServiceProvider provider,
boolean revokeNow);
/**
* Release your copy of this service.
*
*
* If all copies of the service's class have been relinquished by
* the requestor, the BeanContextServiceRevokedListener
* previously registered by getService() will be
* unregistered.
*
* @param requestorChild the original BeanContextChild
* requesting the service.
* @param requestor the original requestor of the service.
* @param service the service to relinquish
* @see #getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener)
*/
void releaseService (BeanContextChild requestorChild, Object requestor,
Object service);
/**
* Get a service from this BeanContextServices.
*
* * The specified listener will be registered to receive a * revocation notice for the specified serviceClass. One * notification per service class per requestor object will be * sent. *
* * The listener will be unregistered when all services that were * obtained by that requestor for that service class are released. *
*
* If the requested service class is not available, or if this
* BeanContextServices object chooses not honor the
* request because the service class has been revoked or for some
* other reason, then this method will return null.
*
*
* This method may throw unchecked exceptions, so watch out.
*
* @specnote it is not specified what happens when two subsequent
* calls are made to getService() with the
* same requestor object and service class but different
* listeners. Which listener is to be notified?
*
* @param requestorChild the BeanContextChild
* associated with the requestor. Typically this will be
* the same as the requestor itself, but since any
* Object, even one outside the hierarchy, may
* make a request, this parameter is necessary. Only weak
* references to this will be retained, and it will never
* be changed, only queried in a read-only manner.
* @param requestor the actual requestor of the service. Only
* weak references to this will be retained, and it will
* never be changed, only queried in a read-only manner.
* @param serviceClass the Class of the service being
* requested.
* @param serviceSelector a parameter to customize the service
* returned with.
* @param listener a listener that will be notified if the service
* being requested is revoked.
* @return an instance of serviceClass (such that
* instanceof serviceClass is true), or
* null.
*/
Object getService (BeanContextChild requestorChild, Object requestor,
Class serviceClass, Object serviceSelector,
BeanContextServiceRevokedListener listener)
throws TooManyListenersException;
/**
* Get a list of all service classes supported.
*
*
* This method must synchronize on
* BeanContext.globalHierarchyLock.
*
* @return a list of all service classes supported.
* @see java.beans.beancontext.BeanContext#globalHierarchyLock
*/
Iterator getCurrentServiceClasses ();
/**
* Get a list of valid service selectors for the specified service class.
*
*
* If the specified service class does not have a finite number of
* valid service selectors, it should return null.
* If it takes a general Integer parameter, for
* example, you may as well return null or the poor
* soul who called this method will be iterating all day.
*
*
* If it has no valid service selectors, it should still return an empty
* Iterator.
*
* @param serviceClass the service class to get selectors for.
* @return a list of valid service selectors for the service
* class, or null.
*/
Iterator getCurrentServiceSelectors (Class serviceClass);
/**
* Tell whether the specified service class is available.
* Iff getService() could return a non-null value for the
* specified service, this method will return true.
*
* @param serviceClass the service class to check on.
* @return whether the specified service class is available.
*/
boolean hasService (Class serviceClass);
/**
* Add a listener on all adds and removes of services.
* @param listener the listener to add.
*/
void addBeanContextServicesListener (BeanContextServicesListener listener);
/**
* Remove a listener on all adds and removes of services.
* @specnote it is not certain whether this should remove this
* listener if it was specified in
* getService().
* @param listener the listener to add.
*/
void removeBeanContextServicesListener (BeanContextServicesListener listener);
}