All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface uhr.core.attract.ServiceClientAide

public interface ServiceClientAide
This serves as an "aide-de-camp" to a ServiceClient. An aide-de-camp is a subordinate acting as a confidential assistant to a superior. This is similar to a delegate. The benefit is fewer methods in the ServiceClient interface and greater reuse.

Our first design for the ServiceClient interface had 4 methods. By introducing the aide, we reduced this to 2 methods and eliminated lots of repetative needer code.

Method Index

o addDeferredNeed(String, String, Object)
Creates and adds a deferred ServiceNeed with the type and a single attribute.
o addNeed(ServiceNeed)
Adds a ServiceNeed.
o addNeed(String, String, Object)
Creates and adds a ServiceNeed with the type and a single attribute.
o enumerateServiceNeeds()
Returns the client's attractors.
o getService(Attractor)
Returns the service for the attractor or null if none is stored in this class.
o getServiceNeed(Attractor)
Returns the ServiceItem having the attractor or null if none.
o satisfyDeferredNeed(Attractor)
Satisfies the deferred need with the attractor.
o setServiceNeeded(ServiceNeed, Object)
Sets the service provided by a host and identifed by the need.

Methods

o addNeed 
 public abstract void addNeed(ServiceNeed need)
Adds a ServiceNeed. The needer uses this method to populate the aide with needs, which MUST be done before the aide is exposed. This method also adds the client to the need.

Parameters:
need - describes the service needed.
Throws: IllegalArgumentException
if the attractor is null.
Throws: IllegalStateException
if the attractor in the need has already been added. Identical attractors in the same need are ambiguous.
o addNeed 
 public abstract ServiceNeed addNeed(String type,
                                     String attributeName,
                                     Object attributeValue)
Creates and adds a ServiceNeed with the type and a single attribute. This is a convenience method.

Parameters:
type - the need type.
attributeName - the attribute name.
attributeValue - the attribute value.
Returns:
the need created.
o addDeferredNeed 
 public abstract ServiceNeed addDeferredNeed(String type,
                                             String attributeName,
                                             Object attributeValue)
Creates and adds a deferred ServiceNeed with the type and a single attribute. This is a convenience method.

Parameters:
type - the need type.
attributeName - the attribute name.
attributeValue - the attribute value.
Returns:
the need created.
o enumerateServiceNeeds 
 public abstract Enumeration enumerateServiceNeeds()
Returns the client's attractors. There is usually at least one.

Returns:
all the client's ServiceNeeds. The order is irrelevant.
o getServiceNeed 
 public abstract ServiceNeed getServiceNeed(Attractor attractor)
Returns the ServiceItem having the attractor or null if none. Note that any attractor can be used, not just the one in the need. This allows lookup without the original attractor.

Parameters:
attractor - identifies the desired ServiceNeed.
Returns:
the desired need or null.
o setServiceNeeded 
 public abstract void setServiceNeeded(ServiceNeed need,
                                       Object service)
Sets the service provided by a host and identifed by the need. This method is a callback from whoever is performing the hookup.

If this is called and the client's service is not null, this is a replacement call. Hereafter the client should use the new reference and should release the old reference.

Parameters:
id - the service id. Normally this is no extra work on the client's part at all.
need - the need that described the service.
service - the attracted service, which must be cast to the type for that service.
Throws: IllegalArgumentException
if the id is unrecognized.
o getService 
 public abstract Object getService(Attractor attractor)
Returns the service for the attractor or null if none is stored in this class.

If null is returned the service may be unavailable, not available yet, the ServiceNeed was optional, an exception has occured, etc. If null ServiceSource can be used if set. If null the attraction is said to be unsatisfied.

If not null then the attraction is currently satisfied. This method is used to check satisfaction integrity and for service replacement.

Parameters:
attractor - identifies the ServiceNeed.
Returns:
the service for the id stored here.
o satisfyDeferredNeed 
 public abstract void satisfyDeferredNeed(Attractor attractor)
Satisfies the deferred need with the attractor. Does nothing if already satisfied.

Parameters:
attractor - identifies the ServiceNeed.
Throws: IllegalStateException
if the serviceID is not found or the need is not deferred. 
All Packages  Class Hierarchy  This Package  Previous  Next  Index