Rio Project 4.2 API Documentation

org.rioproject.associations
Interface AssociationManagement

All Known Implementing Classes:

AssociationMgmt

public interface AssociationManagement

AssociationManagement provides the necessary support to manage Associations a ServiceBean has to other services. Associations provide a mechanism to model and enforce uses and requires associations between services in an OperationalString. Associations are optional and may be declared as part of a ServiceBean element's specification. Associations take 2 forms:

• Uses
  A weak association relationship where if A uses B exists then, then B may be present for A
• Requires
  A stronger association relationship where if A requires B exists then B must be present for A
• Colocated
  An association which requires that A be colocated with B in the same JVM. If B does not exist, or cannot be located, A shall not be created without B
• Opposed
  An association which requires that A exist in a different JVM then B.
• Isolated
  An association which requires that A exist in a different machine then B.

Associations are created during the design/modelling phase and enforced during runtime The AssociationManager will discover and monitor services described in each Association. An Association will either be discovered, changed or broken. Each state transition an Association goes through will result in the notification of any AssociationListener objects which have registered to this AssociationManagement instance. If the Association is of type AssociationType.REQUIRES and the Association state becomes Association.BROKEN and there are no services that match the Association type that have a state of Association.DISCOVERED, then the AssociationManagement object will unadvertise the ServiceBean using the provided ServiceBeanControl interface. Conversely, if the Association is of type AssociationType.REQUIRES and a service is discovered which matches the service type(s), then the Association state becomes Association.DISCOVERED. If the ServiceBean is not advertised, the AssociationManager will advertise the ServiceBean

Author:

Dennis Reedy

Method Summary

<T> Association<T>	addAssociationDescriptor(AssociationDescriptor descriptor) Add an association to the managed set of associations.
List<Association<?>>	addAssociationDescriptors(AssociationDescriptor... descriptors) Add associations to the managed set of associations.
<T> Association<T>	getAssociation(Class<T> serviceType, String serviceName, String opStringName) Get the first matching Association.
List<Association<?>>	getAssociations() Get all managed associations.
void	register(AssociationListener... listeners) Register AssociationListeners.
void	remove(AssociationListener... listeners) Remove AssociationListeners
void	setServiceBeanContainer(ServiceBeanContainer container) Set the ServiceBeanContainer object
void	setServiceBeanContext(ServiceBeanContext context) Set the ServiceBeanContext object for the ServiceBean
void	setServiceBeanControl(ServiceBeanControl control) Set the ServiceBeanControl object for the ServiceBean
void	setUnadvertiseOnBroken(boolean unadvertiseOnBroken) Set unadvertiseOnBroken
void	terminate() Terminate AssociationManagement, cleaning up all connections

Method Detail

setServiceBeanControl

void setServiceBeanControl(ServiceBeanControl control)

Set the ServiceBeanControl object for the ServiceBean

Parameters:

control - The ServiceBeanControl object for the ServiceBean

setServiceBeanContext

void setServiceBeanContext(ServiceBeanContext context)

Set the ServiceBeanContext object for the ServiceBean

Parameters:

context - The ServiceBeanContest object for the ServiceBean

setServiceBeanContainer

void setServiceBeanContainer(ServiceBeanContainer container)

Set the ServiceBeanContainer object

Parameters:

container - The ServiceBeanContainer that the ServiceBean is running in

register

void register(AssociationListener... listeners)

Register AssociationListeners. Each listener object will receive notifications of Association state changes. Once a listener is registered, it will be notified of all Association references discovered to date, and will be notified as Associations are discovered, changed or broken. If the parameter value duplicates (using equals) another element in the set of listeners, no action is taken. If the parameter value is null, an IllegalArgumentException is thrown

Parameters:

listeners - the AssociationListeners

remove

void remove(AssociationListener... listeners)

Remove AssociationListeners

Parameters:

listeners - the AssociationListeners

terminate

void terminate()

Terminate AssociationManagement, cleaning up all connections

getAssociation

<T> Association<T> getAssociation(Class<T> serviceType,
                                  String serviceName,
                                  String opStringName)

Get the first matching Association.

Parameters:

serviceType - The service type to match, must not be null

serviceName - String name of the associated service. If null will be ignored

opStringName - String name of the OperationalString. If null will be ignored

Returns:

The first Association instance that matches the provided criteria. If there no matching associations, a null will be returned.

Throws:

IllegalArgumentException - if the serviceType is null

addAssociationDescriptor

<T> Association<T> addAssociationDescriptor(AssociationDescriptor descriptor)

Add an association to the managed set of associations. If the association already exists, it will not be added.

Parameters:

descriptor - The AssociationDescriptor

Returns:

An Association object.

Throws:

IllegalArgumentException - if the AssociationDescriptor is null.

See Also:

AssociationProxy, ServiceSelectionStrategy

addAssociationDescriptors

List<Association<?>> addAssociationDescriptors(AssociationDescriptor... descriptors)

Add associations to the managed set of associations. If any of the associations already exists, it will not be added.

Parameters:

descriptors - AssociationDescriptor instances

Returns:

An unmodifiable List of Association objects corresponding to the submitted descriptors. A new list is created each time.

Throws:

IllegalArgumentException - if the AssociationDescriptor is null.

See Also:

AssociationProxy, ServiceSelectionStrategy

getAssociations

List<Association<?>> getAssociations()

Get all managed associations.

Returns:

An unmodifiable List of Association objects. A new list is created each time.

setUnadvertiseOnBroken

void setUnadvertiseOnBroken(boolean unadvertiseOnBroken)

Set unadvertiseOnBroken

Parameters:

unadvertiseOnBroken - If true, and the service has an Association with a type of AssociationType.REQUIRES and the Association is broken, the AssociationManagement object will unadvertise the ServiceBean using the ServiceBean instance's ServiceBeanControl object. If false, the AssociationManagement object will not unadvertise the ServiceBean