java.beans.beancontext
Class BeanContextServicesSupport

java.lang.Object
  extended by java.beans.beancontext.BeanContextChildSupport
      extended by java.beans.beancontext.BeanContextSupport
          extended by java.beans.beancontext.BeanContextServicesSupport
All Implemented Interfaces:
BeanContext, BeanContextChild, BeanContextServiceRevokedListener, BeanContextServices, BeanContextServicesListener, DesignMode, PropertyChangeListener, VetoableChangeListener, Visibility, Serializable, Iterable, Collection, EventListener

public class BeanContextServicesSupport
extends BeanContextSupport
implements BeanContextServices

This is a helper class for implementing a bean context which supplies services. It is intended to be used either by subclassing or by calling methods of this implementation from another.

Since:
1.2
See Also:
Serialized Form

Nested Class Summary
protected  class BeanContextServicesSupport.BCSSChild
           
protected  class BeanContextServicesSupport.BCSSProxyServiceProvider
           
protected static class BeanContextServicesSupport.BCSSServiceProvider
           
 
Nested classes/interfaces inherited from class java.beans.beancontext.BeanContextSupport
BeanContextSupport.BCSChild, BeanContextSupport.BCSIterator
 
Field Summary
protected  ArrayList bcsListeners
          A collection of listeners who receive availability and revocation notifications.
protected  BeanContextServicesSupport.BCSSProxyServiceProvider proxy
           
protected  int serializable
          The number of serializable service providers.
protected  HashMap services
          A map of registered services, linking the service class to its associated BeanContextServicesSupport.BCSSServiceProvider.
 
Fields inherited from class java.beans.beancontext.BeanContextSupport
bcmListeners, children, designTime, locale, okToUseGui
 
Fields inherited from class java.beans.beancontext.BeanContextChildSupport
beanContext, beanContextChildPeer, pcSupport, rejectedSetBCOnce, vcSupport
 
Fields inherited from interface java.beans.beancontext.BeanContext
globalHierarchyLock
 
Fields inherited from interface java.beans.DesignMode
PROPERTYNAME
 
Constructor Summary
BeanContextServicesSupport()
          Construct a BeanContextServicesSupport instance.
BeanContextServicesSupport(BeanContextServices peer)
          Construct a BeanContextServicesSupport instance.
BeanContextServicesSupport(BeanContextServices peer, Locale locale)
          Construct a BeanContextServicesSupport instance.
BeanContextServicesSupport(BeanContextServices peer, Locale locale, boolean dtime)
          Construct a BeanContextServicesSupport instance.
BeanContextServicesSupport(BeanContextServices peer, Locale locale, boolean dtime, boolean visible)
          Construct a BeanContextServicesSupport instance.
 
Method Summary
 void addBeanContextServicesListener(BeanContextServicesListener listener)
          Adds a new listener for service availability and revocation events.
 boolean addService(Class serviceClass, BeanContextServiceProvider bcsp)
          Registers a new service from the specified service provider.
protected  boolean addService(Class serviceClass, BeanContextServiceProvider bcsp, boolean fireEvent)
          Registers a new service from the specified service provider.
protected  void bcsPreDeserializationHook(ObjectInputStream ois)
          Deserializes any service providers which are serializable.
protected  void bcsPreSerializationHook(ObjectOutputStream oos)
          Serializes any service providers which are serializable.
protected  void childJustRemovedHook(Object child, BeanContextSupport.BCSChild bcsc)
          Revokes any services used by a child that has just been removed.
protected  BeanContextSupport.BCSChild createBCSChild(Object targetChild, Object peer)
          Overrides the BeanContextSupport.createBCSChild(java.lang.Object, java.lang.Object) method so as to use a BeanContextServicesSupport.BCSSChild instead.
protected  BeanContextServicesSupport.BCSSServiceProvider createBCSSServiceProvider(Class sc, BeanContextServiceProvider bcsp)
          Provides a hook so that subclasses can replace the BeanContextServicesSupport.BCSSServiceProvider class, used to store registered service providers, with a subclass without replacing the addService(Class, BeanContextServiceProvider) method.
protected  void fireServiceAdded(BeanContextServiceAvailableEvent bcssae)
          Sends a BeanContextServiceAvailableEvent to all registered listeners.
protected  void fireServiceAdded(Class serviceClass)
          Sends a BeanContextServiceAvailableEvent to all registered listeners.
protected  void fireServiceRevoked(BeanContextServiceRevokedEvent event)
          Sends a BeanContextServiceRevokedEvent to all registered listeners.
protected  void fireServiceRevoked(Class serviceClass, boolean revokeNow)
          Sends a BeanContextServiceRevokedEvent to all registered listeners.
 BeanContextServices getBeanContextServicesPeer()
          Returns the services peer given at construction time, or null if no peer was given.
protected static BeanContextServicesListener getChildBeanContextServicesListener(Object child)
          Returns child as an instance of BeanContextServicesListener, or null if child does not implement that interface.
 Iterator getCurrentServiceClasses()
          Returns an iterator over the currently available services.
 Iterator getCurrentServiceSelectors(Class serviceClass)
          Returns an iterator over the service selectors of the service provider for the given service.
 Object getService(BeanContextChild child, Object requestor, Class serviceClass, Object serviceSelector, BeanContextServiceRevokedListener bcsrl)
          Retrieves the specified service.
 boolean hasService(Class serviceClass)
          Returns true if the specified service is available.
 void initialize()
           
protected  void initializeBeanContextResources()
          Subclasses may override this method to allocate resources from the nesting bean context.
protected  void releaseBeanContextResources()
          Relinquishes any resources obtained from the parent context.
 void releaseService(BeanContextChild child, Object requestor, Object service)
          Releases the reference to a service held by a BeanContextChild (or an arbitrary object associated with it).
 void removeBeanContextServicesListener(BeanContextServicesListener listener)
          Remove a listener on all adds and removes of services.
 void revokeService(Class serviceClass, BeanContextServiceProvider bcsp, boolean revokeCurrentServicesNow)
          Revokes the given service.
 void serviceAvailable(BeanContextServiceAvailableEvent bcssae)
          Called by BeanContextServices whenever a service is made available.
 void serviceRevoked(BeanContextServiceRevokedEvent bcssre)
          Called by BeanContextServices.revokeService() to indicate that a service has been revoked.
 
Methods inherited from class java.beans.beancontext.BeanContextSupport
add, addAll, addBeanContextMembershipListener, avoidingGui, bcsChildren, childDeserializedHook, childJustAddedHook, classEquals, clear, contains, containsAll, containsKey, copyChildren, deserialize, dontUseGui, fireChildrenAdded, fireChildrenRemoved, getBeanContextPeer, getChildBeanContextChild, getChildBeanContextMembershipListener, getChildPropertyChangeListener, getChildSerializable, getChildVetoableChangeListener, getChildVisibility, getLocale, getResource, getResourceAsStream, instantiateChild, isDesignTime, isEmpty, isSerializing, iterator, needsGui, okToUseGui, propertyChange, readChildren, remove, remove, removeAll, removeBeanContextMembershipListener, retainAll, serialize, setDesignTime, setLocale, size, toArray, toArray, validatePendingAdd, validatePendingRemove, vetoableChange, writeChildren
 
Methods inherited from class java.beans.beancontext.BeanContextChildSupport
addPropertyChangeListener, addVetoableChangeListener, firePropertyChange, fireVetoableChange, getBeanContext, getBeanContextChildPeer, isDelegated, removePropertyChangeListener, removeVetoableChangeListener, setBeanContext, validatePendingSetBeanContext
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.beans.beancontext.BeanContext
addBeanContextMembershipListener, getResource, getResourceAsStream, instantiateChild, removeBeanContextMembershipListener
 
Methods inherited from interface java.util.Collection
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray
 
Methods inherited from interface java.beans.beancontext.BeanContextChild
addPropertyChangeListener, addVetoableChangeListener, getBeanContext, removePropertyChangeListener, removeVetoableChangeListener, setBeanContext
 
Methods inherited from interface java.beans.Visibility
avoidingGui, dontUseGui, needsGui, okToUseGui
 
Methods inherited from interface java.beans.DesignMode
isDesignTime, setDesignTime
 

Field Detail

bcsListeners

protected transient ArrayList bcsListeners
A collection of listeners who receive availability and revocation notifications.


proxy

protected transient BeanContextServicesSupport.BCSSProxyServiceProvider proxy

serializable

protected transient int serializable
The number of serializable service providers.


services

protected transient HashMap services
A map of registered services, linking the service class to its associated BeanContextServicesSupport.BCSSServiceProvider.

Constructor Detail

BeanContextServicesSupport

public BeanContextServicesSupport()
Construct a BeanContextServicesSupport instance.


BeanContextServicesSupport

public BeanContextServicesSupport(BeanContextServices peer)
Construct a BeanContextServicesSupport instance.

Parameters:
peer - the bean context services peer (null permitted).

BeanContextServicesSupport

public BeanContextServicesSupport(BeanContextServices peer,
                                  Locale locale)
Construct a BeanContextServicesSupport instance.

Parameters:
peer - the bean context peer (null permitted).
locale - the locale (null permitted, equivalent to the default locale).

BeanContextServicesSupport

public BeanContextServicesSupport(BeanContextServices peer,
                                  Locale locale,
                                  boolean dtime)
Construct a BeanContextServicesSupport instance.

Parameters:
peer - the bean context peer (null permitted).
locale - the locale (null permitted, equivalent to the default locale).
dtime - a flag indicating whether or not the bean context is in design time mode.

BeanContextServicesSupport

public BeanContextServicesSupport(BeanContextServices peer,
                                  Locale locale,
                                  boolean dtime,
                                  boolean visible)
Construct a BeanContextServicesSupport instance.

Parameters:
peer - the bean context peer (null permitted).
locale - the locale (null permitted, equivalent to the default locale).
dtime - a flag indicating whether or not the bean context is in design time mode.
visible - initial value of the okToUseGui flag.
Method Detail

addBeanContextServicesListener

public void addBeanContextServicesListener(BeanContextServicesListener listener)
Adds a new listener for service availability and revocation events.

Specified by:
addBeanContextServicesListener in interface BeanContextServices
Parameters:
listener - the listener to add.

addService

public boolean addService(Class serviceClass,
                          BeanContextServiceProvider bcsp)
Registers a new service from the specified service provider. The service is internally associated with the service provider and a BeanContextServiceAvailableEvent is fired. If the service is already registered, then this method instead returns false. This is equivalent to calling addService(serviceClass, bcsp, true).

Specified by:
addService in interface BeanContextServices
Parameters:
serviceClass - the class of the service to be registered.
bcsp - the provider of the given service.
Returns:
true if the service was registered successfully.
See Also:
addService(Class, BeanContextServiceProvider, boolean)

addService

protected boolean addService(Class serviceClass,
                             BeanContextServiceProvider bcsp,
                             boolean fireEvent)
Registers a new service from the specified service provider. The service is internally associated with the service provider and (if fireEvent is true) a BeanContextServiceAvailableEvent is fired. If the service is already registered, then this method instead returns false.

Parameters:
serviceClass - the class of the service to be registered.
bcsp - the provider of the given service.
fireEvent - true if a service availability event should be fired.
Returns:
true if the service was registered successfully.

bcsPreDeserializationHook

protected void bcsPreDeserializationHook(ObjectInputStream ois)
                                  throws ClassNotFoundException,
                                         IOException
Deserializes any service providers which are serializable. This method is called by the readObject method of BeanContextSupport prior to deserialization of the children. Subclasses may envelope its behaviour in order to read further serialized data to the stream.

Overrides:
bcsPreDeserializationHook in class BeanContextSupport
Parameters:
ois - the stream from which data is being deserialized.
Throws:
IOException - if an I/O error occurs.
ClassNotFoundException - if the class of a deserialized object can not be found.

bcsPreSerializationHook

protected void bcsPreSerializationHook(ObjectOutputStream oos)
                                throws IOException
Serializes any service providers which are serializable. This method is called by the writeObject method of BeanContextSupport prior to serialization of the children. Subclasses may envelope its behaviour in order to add further serialized data to the stream.

Overrides:
bcsPreSerializationHook in class BeanContextSupport
Parameters:
oos - the stream to which data is being serialized.
Throws:
IOException - if an I/O error occurs.

childJustRemovedHook

protected void childJustRemovedHook(Object child,
                                    BeanContextSupport.BCSChild bcsc)
Revokes any services used by a child that has just been removed. The superclass (BeanContextSupport) calls this method when a child has just been successfully removed. Subclasses can extend this method in order to perform additional operations on child removal.

Overrides:
childJustRemovedHook in class BeanContextSupport
Parameters:
child - the child being removed.
bcsc - the support object for the child.

createBCSChild

protected BeanContextSupport.BCSChild createBCSChild(Object targetChild,
                                                     Object peer)
Overrides the BeanContextSupport.createBCSChild(java.lang.Object, java.lang.Object) method so as to use a BeanContextServicesSupport.BCSSChild instead.

Overrides:
createBCSChild in class BeanContextSupport
Parameters:
targetChild - the child to create the child for.
peer - the peer which relates to the child if a proxy is used.
Returns:
a new instance of BeanContextServicesSupport.BCSSChild.

createBCSSServiceProvider

protected BeanContextServicesSupport.BCSSServiceProvider createBCSSServiceProvider(Class sc,
                                                                                   BeanContextServiceProvider bcsp)
Provides a hook so that subclasses can replace the BeanContextServicesSupport.BCSSServiceProvider class, used to store registered service providers, with a subclass without replacing the addService(Class, BeanContextServiceProvider) method.

Parameters:
sc - the class of service being registered.
bcsp - the provider of the service.
Returns:
a instance of BeanContextServicesSupport.BCSSServiceProvider wrapping the provider.

fireServiceAdded

protected final void fireServiceAdded(BeanContextServiceAvailableEvent bcssae)
Sends a BeanContextServiceAvailableEvent to all registered listeners.

Parameters:
bcssae - the event to send.

fireServiceAdded

protected final void fireServiceAdded(Class serviceClass)
Sends a BeanContextServiceAvailableEvent to all registered listeners.

Parameters:
serviceClass - the service that is now available.
See Also:
fireServiceAdded(BeanContextServiceAvailableEvent)

fireServiceRevoked

protected final void fireServiceRevoked(BeanContextServiceRevokedEvent event)
Sends a BeanContextServiceRevokedEvent to all registered listeners.

Parameters:
event - the event to send.

fireServiceRevoked

protected final void fireServiceRevoked(Class serviceClass,
                                        boolean revokeNow)
Sends a BeanContextServiceRevokedEvent to all registered listeners.

Parameters:
serviceClass - the service that has been revoked.
See Also:
fireServiceRevoked(BeanContextServiceRevokedEvent)

getBeanContextServicesPeer

public BeanContextServices getBeanContextServicesPeer()
Returns the services peer given at construction time, or null if no peer was given.

Returns:
the BeanContextServices peer.

getChildBeanContextServicesListener

protected static final BeanContextServicesListener getChildBeanContextServicesListener(Object child)
Returns child as an instance of BeanContextServicesListener, or null if child does not implement that interface.

Parameters:
child - the child (null permitted).
Returns:
The child cast to BeanContextServicesListener.

getCurrentServiceClasses

public Iterator getCurrentServiceClasses()
Returns an iterator over the currently available services.

Specified by:
getCurrentServiceClasses in interface BeanContextServices
Returns:
an iterator over the currently available services.
See Also:
BeanContext.globalHierarchyLock

getCurrentServiceSelectors

public Iterator getCurrentServiceSelectors(Class serviceClass)
Returns an iterator over the service selectors of the service provider for the given service. The iterator is actually obtained by calling the BeanContextServiceProvider.getCurrentServiceSelectors(java.beans.beancontext.BeanContextServices, java.lang.Class) of the provider itself. If the specified service is not available, null is returned.

Specified by:
getCurrentServiceSelectors in interface BeanContextServices
Parameters:
serviceClass - the service whose provider's selectors should be iterated over.
Returns:
an Iterator over the service selectors of the provider of the given service.

getService

public Object getService(BeanContextChild child,
                         Object requestor,
                         Class serviceClass,
                         Object serviceSelector,
                         BeanContextServiceRevokedListener bcsrl)
                  throws TooManyListenersException
Retrieves the specified service. If a provider for the service is registered in this context, then the request is passed on to the provider and the service returned. Otherwise, the request is delegated to a parent BeanContextServices, if possible. If the service can not be found at all, then null is returned.

Specified by:
getService in interface BeanContextServices
Parameters:
child - the child obtaining the reference.
requestor - the requestor of the service, which may be the child itself.
serviceClass - the service being requested.
serviceSelector - an additional service-dependent parameter (may be null if not appropriate).
bcsrl - a listener used to notify the requestor that the service has since been revoked.
Returns:
a reference to the service requested, or null.
Throws:
TooManyListenersException - according to Sun's documentation.

hasService

public boolean hasService(Class serviceClass)
Returns true if the specified service is available.

Specified by:
hasService in interface BeanContextServices
Parameters:
serviceClass - the service to check for.
Returns:
true if the service is available.

initialize

public void initialize()
Overrides:
initialize in class BeanContextSupport

initializeBeanContextResources

protected void initializeBeanContextResources()
Subclasses may override this method to allocate resources from the nesting bean context.

Overrides:
initializeBeanContextResources in class BeanContextChildSupport

releaseBeanContextResources

protected void releaseBeanContextResources()
Relinquishes any resources obtained from the parent context. Specifically, those services obtained from the parent are revoked. Subclasses may override this method to deallocate resources from the nesting bean context.

Overrides:
releaseBeanContextResources in class BeanContextChildSupport

releaseService

public void releaseService(BeanContextChild child,
                           Object requestor,
                           Object service)
Releases the reference to a service held by a BeanContextChild (or an arbitrary object associated with it). It simply calls the appropriate method on the underlying provider.

Specified by:
releaseService in interface BeanContextServices
Parameters:
child - the child who holds the reference.
requestor - the object that requested the reference.
service - the service being released.
See Also:
BeanContextServices.getService(java.beans.beancontext.BeanContextChild,java.lang.Object,java.lang.Class,java.lang.Object,java.beans.beancontext.BeanContextServiceRevokedListener)

removeBeanContextServicesListener

public void removeBeanContextServicesListener(BeanContextServicesListener listener)
Description copied from interface: BeanContextServices
Remove a listener on all adds and removes of services.

Specified by:
removeBeanContextServicesListener in interface BeanContextServices
Parameters:
listener - the listener to add.

revokeService

public void revokeService(Class serviceClass,
                          BeanContextServiceProvider bcsp,
                          boolean revokeCurrentServicesNow)
Revokes the given service. A BeanContextServiceRevokedEvent is emitted to all registered BeanContextServiceRevokedListeners and BeanContextServiceListeners. If revokeCurrentServicesNow is true, termination of the service is immediate. Otherwise, prior acquisitions of the service by requestors remain valid.

Specified by:
revokeService in interface BeanContextServices
Parameters:
serviceClass - the service to revoke.
bcsp - the provider of the revoked service.
revokeCurrentServicesNow - true if this is an exceptional circumstance where service should be immediately revoked.

serviceAvailable

public void serviceAvailable(BeanContextServiceAvailableEvent bcssae)
Description copied from class: BeanContextChildSupport
Called by BeanContextServices whenever a service is made available.

This method is meant to be overriden. BeanContextChildSupport's implementation does nothing.

Specified by:
serviceAvailable in interface BeanContextServicesListener
Overrides:
serviceAvailable in class BeanContextChildSupport
Parameters:
bcssae - the service revoked event, with useful information about the new service.

serviceRevoked

public void serviceRevoked(BeanContextServiceRevokedEvent bcssre)
Description copied from class: BeanContextChildSupport
Called by BeanContextServices.revokeService() to indicate that a service has been revoked. If you have a reference to such a service, it should be discarded and may no longer function properly. getService() will no longer work on the specified service class after this event has been fired.

This method is meant to be overriden. BeanContextChildSupport's implementation does nothing.

Specified by:
serviceRevoked in interface BeanContextServiceRevokedListener
Overrides:
serviceRevoked in class BeanContextChildSupport
Parameters:
bcssre - the service revoked event.
See Also:
BeanContextServices.revokeService(java.lang.Class,java.beans.beancontext.BeanContextServiceProvider,boolean)