Rio Project 4.2 API Documentation

org.rioproject.associations
Class Association<T>

java.lang.Object
  org.rioproject.associations.Association<T>

All Implemented Interfaces:

Iterable<T>

public class Association<T>
extends Object
implements Iterable<T>

Associations provide a mechanism to model and enforce uses and requires associations between services in an OperationalString. Associations take 5 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 optional and may be declared as part of a service's OperationalString declaration. An example :

associations {
association name:"JavaSpace", type:'requires', property:"space"
}
}

Once provisioned a service can obtain it's Associations from the ServiceBeanContext.getAssociationManagement() method.

Author:

Dennis Reedy

Nested Class Summary

static class

Association.State Association State enums indicate the following: PENDING: Indicates that an associated service has not been discovered DISCOVERED: Indicates that an associated service has been discovered CHANGED: Indicates that an associated service has changed, that is an end-point has changed, and the association now points a different service BROKEN: Indicates that the association is broken

Constructor Summary

Association(AssociationDescriptor descriptor)
Create an Association

Method Summary

boolean	addServiceItem(ServiceItem item) Add a service to the Association
AssociationDescriptor	getAssociationDescriptor() Get the AssociationDescriptor
AssociationType	getAssociationType() Get the AssociationType
String	getName() Get the associated service's name
ServiceItem	getNextServiceItem() Get the next ServiceItem in the collection of associated services.
String	getOperationalStringName() Get the associated service's OperationalString name
T	getService() Get the first service Object that can be used to communicate to the associated service.
int	getServiceCount() Get the number of associated services
Future<T>	getServiceFuture() Get a future representing pending service association.
ServiceItem	getServiceItem() Get the ServiceItem for the service thats first in the List of services.
ServiceItem	getServiceItem(T service) Get the ServiceItem for the associated service.
ServiceItem[]	getServiceItems() Get ServiceItem instances for all known associated service instances.
Collection<T>	getServices() Get all Objects that can be used to communicate to all known associated services.
Association.State	getState() Get the Association state
Iterator<T>	iterator() Satisfies the contract of an Iterable, allowing the associated services to be the target of a "foreach" statement
void	registerAssociationServiceListener(AssociationServiceListener<T> al) Register an AssociationServiceListener for notification.
void	removeAssociationServiceListener(AssociationServiceListener<T> al) Remove a AssociationServiceListener for notification.
ServiceItem	removeService(T service) Remove a service from the Association
void	setState(Association.State state) Set the Association state

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Association

public Association(AssociationDescriptor descriptor)

Create an Association

Parameters:

descriptor - The AssociationDescriptor for this association

Method Detail

getAssociationType

public AssociationType getAssociationType()

Get the AssociationType

Returns:

The AssociationType

setState

public void setState(Association.State state)

Set the Association state

Parameters:

state - The Association state

getState

public Association.State getState()

Get the Association state

Returns:

The Association state

getName

public String getName()

Get the associated service's name

Returns:

The associated service's name

getOperationalStringName

public String getOperationalStringName()

Get the associated service's OperationalString name

Returns:

The associated service's OperationalString name

getAssociationDescriptor

public AssociationDescriptor getAssociationDescriptor()

Get the AssociationDescriptor

Returns:

The AssociationDescriptor used to create this Association

getServiceCount

public int getServiceCount()

Get the number of associated services

Returns:

The number of associated services

getService

public T getService()

Get the first service Object that can be used to communicate to the associated service.

Returns:

The first service (proxy) Object in the collection of associated services. If there are no services a null will be returned.

getServiceFuture

public Future<T> getServiceFuture()

Get a future representing pending service association.

Returns:

a Future representing pending service association. A new Future is created each time.

See Also:

AssociationProxy, ServiceSelectionStrategy

getServices

public Collection<T> getServices()

Get all Objects that can be used to communicate to all known associated services.

Returns:

Array of service Object instances that can be used to communicate to all known associated service instances. A new collection is allocated each time. If there are no services, an empty collection will be returned

iterator

public Iterator<T> iterator()

Satisfies the contract of an Iterable, allowing the associated services to be the target of a "foreach" statement

Specified by:

iterator in interface Iterable<T>

Returns:

An Iterable that can be used to iterate over the collection of associated services. A new Iterable is created each time.

getServiceItem

public ServiceItem getServiceItem()

Get the ServiceItem for the service thats first in the List of services.

Returns:

The ServiceItem for an associated service. If there are no services, a null will be returned

getServiceItem

public ServiceItem getServiceItem(T service)

Get the ServiceItem for the associated service. The collection of associated services will be searched and if the service proxy is equal to a known associated service proxy, the ServiceID for that service will be returned

Parameters:

service - The proxy of an associated service

Returns:

The ServiceItem for an associated service. If the service is unknown, a null will be returned

getServiceItems

public ServiceItem[] getServiceItems()

Get ServiceItem instances for all known associated service instances.

Returns:

Array of ServiceItem instances for all known associated service instances. A new array is allocated each time. If there are no services, an empty array will be returned

getNextServiceItem

public ServiceItem getNextServiceItem()

Get the next ServiceItem in the collection of associated services.

Returns:

The next ServiceItem in the collection of associated services. If there are services, a null will be returned. If the current ServiceItem is the last in the collection, the first ServiceItem in the collection will be returned

addServiceItem

public boolean addServiceItem(ServiceItem item)

Add a service to the Association

Parameters:

item - The ServiceItem for the service to add

Returns:

True if added, false if the ServiceItem already exists

removeService

public ServiceItem removeService(T service)

Remove a service from the Association

Parameters:

service - The proxy for the Service to remove

Returns:

The ServiceItem of the removed service

registerAssociationServiceListener

public void registerAssociationServiceListener(AssociationServiceListener<T> al)

Register an AssociationServiceListener for notification.

Parameters:

al - The AssociationServiceListener. If the AssociationServiceListener is not null and not already registered it will be added to the collection of AssociationServiceListeners

removeAssociationServiceListener

public void removeAssociationServiceListener(AssociationServiceListener<T> al)

Remove a AssociationServiceListener for notification.

Parameters:

al - The AssociationServiceListener. If the AssociationServiceListener is not null and registered, it will be removed from the collection of AssociationServiceListeners