net.openwings.component
Interface Component

All Known Subinterfaces:

ComponentComplex

public interface Component

This interface is the centerpiece of the service-based component architecture provided by Openwings. The Component interface abstracts the details of using synchronous (method based) and asynchronous (messaging or event based) communication between components.

Synchronous services are provided or used by components. These semantics unite the provide/use semantics of the EJB Component model and the discovery/join/lookup semantics of the Jini architecture.

• "discovery" refers to the way a Component locates repository/ naming services. In Openwings, discovery is not exposed in the Component interface.
• "join" refers to the way a Component publishes its services with naming services. In Openwings, join is made available through the provideService() methods.
• "lookup" refers to the way a Component locates services it wishes to use. In Openwings, lookup is made available through the useService() methods.

Asynchronous services are published or subscribed to by components. These semantics abstract the details of event spaces in various 3rd party messaging protocols.

Method Summary

void	connectDistributedObject(java.lang.Object serviceObject) This method can be used on the client side of a connection to enable a distributed object to be used.
void	discardUsedService(UniqueID serviceID) This method releases a synchronous (remote method) service provided by another component.
void	disconnectDistributedObject(java.lang.Object serviceObject) This method can be used on the client side of a connection to disable the connection of a distributed object.
java.lang.Object	distributeObject(java.lang.Class serviceInterface, java.lang.Object service) This method is used to make an object available remotely.
java.lang.Object	distributeObject(java.lang.Class serviceInterface, java.lang.Object service, java.lang.Class connectorInterface) This method is used to make an object available remotely.
ComponentDescriptor	getComponentDescriptor() This method is used to retrieve metadata about a component
UniqueID	getComponentID() This method is used to retrieve a unique identifier for the component.
UniqueID	provideService(java.lang.Class serviceInterface, java.lang.Object service) This method is used to make a synchronous (remote method) service available to other components (join).
void	provideService(java.lang.Class serviceInterface, java.lang.Object service, UniqueID uniqueID) This method is used to make a synchronous (remote method) service available to other components (join).
ServiceResult	publishService(java.lang.Class serviceInterface) This method is used to indicate that the component will publish an asynchronous (event or messaging) service.
void	publishService(java.lang.Class serviceInterface, EventServiceListener listener) This method registers for notification of the ability to publish an asynchronous (event or messaging) service.
void	removeEventServiceListener(java.lang.Class serviceInterface, EventServiceListener listener) This method stops notification of asynchronous (event or messaging) services created by other components.
void	removeProvidedService(UniqueID serviceID) This method is used to make a synchronous (remote method) service unavailable for use by other components.
void	removeUseServiceListener(java.lang.Class serviceInterface, UseServiceListener listener) This method stops notification of synchronous services provided by other components.
void	shutdown() This method is used to terminate all service connections and processing provided by a Component.
UniqueID	subscribeService(java.lang.Class serviceInterface, java.lang.Object service) This method is used to subscribe to a an asynchronous (event or messaging) service.
void	subscribeService(java.lang.Class serviceInterface, java.lang.Object service, EventServiceListener listener) This method registers for notification of the ability to subscribe to an asynchronous (event or messaging) service.
void	undistributeObject(java.lang.Class serviceInterface, java.lang.Object service) This method is used to make an object unavailable remotely.
void	unpublishService(UniqueID serviceID) This method is used to indicate that the component will no longer publish an asynchronous (event or messaging) service.
void	unsubscribeService(UniqueID serviceID) This method is used to stop subscription to a an asynchronous (event or messaging) service.
ServiceResult	useService(java.lang.Class serviceInterface) This method finds a synchronous (remote method) service provided by another component (lookup).
void	useService(java.lang.Class serviceInterface, UseServiceListener listener) This method registers for notification of synchronous (remote method) services provided other components (lookup).

Method Detail

provideService

public UniqueID provideService(java.lang.Class serviceInterface,
                               java.lang.Object service)
                        throws InvalidServiceException

This method is used to make a synchronous (remote method) service available to other components (join).

Repeated calls to this method with identical parameters have no effect unless removeProvidedService() has been called.

A service object that is intended to receive remote calls should be a distributed object, that is, an object returned from the distributeObject() method.

If a service is provided with the correct serviceInterface and service but there is a problem with a particular discovery plug-in, no Exception is thrown. Instead the component continues using other discovery plug-ins to try to provide the service.

Parameters:

serviceInterface - interface describing the service provided

service - object implementing the specified interface

Returns:

unique identifier used to reference this service

Throws:

InvalidServiceException - thrown if service does not implement Serializable and serviceInterface

provideService

public void provideService(java.lang.Class serviceInterface,
                           java.lang.Object service,
                           UniqueID uniqueID)
                    throws InvalidServiceException

This method is used to make a synchronous (remote method) service available to other components (join).

This method allows the uniqueID to be specified

Repeated calls to this method with identical parameters have no effect unless removeProvidedService() has been called.

A service object that is intended to receive remote calls should be a distributed object, that is, an object returned from the distributeObject() method.

If a service is provided with the correct serviceInterface and service but there is a problem with a particular discovery plug-in, no Exception is thrown. Instead the component continues using other discovery plug-ins to try to provide the service.

Parameters:

serviceInterface - interface describing the service provided

service - object implementing the specified interface

uniqueID - unique identifier for the service

Throws:

InvalidServiceException - thrown if service does not implement Serializable and serviceInterface

removeProvidedService

public void removeProvidedService(UniqueID serviceID)

This method is used to make a synchronous (remote method) service unavailable for use by other components. Note that a distributed service objects is not disconnected from any clients. The undistributeObject() method must be called to disconnect the service. Thus the service can be removed as a means of limiting the number of users, and then provided again later.

Repeated calls to this method with identical parameters have no effect.

Parameters:

serviceID - unique service identifier returned from provideService()

useService

public ServiceResult useService(java.lang.Class serviceInterface)
                         throws InvalidServiceException

This method finds a synchronous (remote method) service provided by another component (lookup).

Repeated calls to this method with the same serviceInterface are not guaranteed to return different service objects.

Parameters:

serviceInterface - interface describing the desired service

Returns:

result object containing a service object implementing the specified interface and its unique identifier, or null if the service could be located

Throws:

InvalidServiceException - thrown if:

• serviceInterface is not a valid interface

useService

public void useService(java.lang.Class serviceInterface,
                       UseServiceListener listener)
                throws InvalidServiceException

This method registers for notification of synchronous (remote method) services provided other components (lookup).

Repeated calls to this method with the same serviceInterface and listener have no effect.

Parameters:

serviceInterface - interface describing the desired service

listener - notification object

Throws:

InvalidServiceException - thrown if serviceInterface is not a valid interface

removeUseServiceListener

public void removeUseServiceListener(java.lang.Class serviceInterface,
                                     UseServiceListener listener)

This method stops notification of synchronous services provided by other components.

Pending callbacks may still be made to listener due to race conditions.

Service objects previously passed to the serviceProvided() method of listener are not affected by this call.

Repeated calls to this method with identical parameters have no effect.

Parameters:

serviceInterface - interface describing the service provided

listener - a UseServiceListener previously passed to one of the useService() methods.

distributeObject

public java.lang.Object distributeObject(java.lang.Class serviceInterface,
                                         java.lang.Object service)
                                  throws InvalidServiceException

This method is used to make an object available remotely.

This can be used for objects provided as services or objects passed to or returned from services. For example, a component using a service uses this method to make an object available remotely so it can be passed to a service method. A component providing a service uses this method to make an object available remotely so it can be returned from a service method.

Repeated calls to this method with the same serviceInterface and service are guaranteed to return the same object.

Repeated calls to this method with the same service but a different serviceInterface will return different objects. This allows the same object to be provided as several distinct services.

This method attempts to distribute an object using a net.openwings.connnector.synchronous.SynchronousConnector. If asynchronous behavior is needed, the other variant of distributeObject should be used.

Parameters:

serviceInterface - interface describing the service provided

service - object implementing the specified interface

Returns:

a remote version of the object that can be passed to a service method or returned from a service method. If Openwings Connectors are used, the object will implement the interface net.openwings.connector.synchronous.UserProxy.

Throws:

InvalidServiceException - thrown if service does not implement serviceInterface

distributeObject

public java.lang.Object distributeObject(java.lang.Class serviceInterface,
                                         java.lang.Object service,
                                         java.lang.Class connectorInterface)
                                  throws InvalidServiceException

This method is used to make an object available remotely.

This can be used for objects provided as services or objects passed to or returned from services. For example, a component using a service uses this method to make an object available remotely so it can be passed to a service method. A component providing a service uses this method to make an object available remotely so it can be returned from a service method.

Repeated calls to this method with the same serviceInterface, service, and connectorInterface are guaranteed to return the same object.

Repeated calls to this method with the same service but a different serviceInterface will return different objects. This allows the same object to be provided as several distinct services.

Repeated calls to this method with the same service and serviceInterface, but a different connectorInterface will return different objects. Each new object will cause the previous to be replaced.

This method returns the type of connector specified in the connectorInterface parameter. For example, if an asynchronous connector is needed, net.openwings.connector.asynchronous.AsynchronousConnector.class could be used as the connectorInterface parameter.

Parameters:

serviceInterface - interface describing the service provided

service - object implementing the specified interface

connectorInterface - class used to make the object available remotely

Returns:

a remote version of the object that can be passed to a service method or returned from a service method. If Openwings Connectors are used, the object will implement the interface net.openwings.connector.SenderProxy and one or more of its subinterfaces.

Throws:

InvalidServiceException - thrown if service does not implement serviceInterface

undistributeObject

public void undistributeObject(java.lang.Class serviceInterface,
                               java.lang.Object service)

This method is used to make an object unavailable remotely.

This can be used for objects provided as services or objects passed to or returned from services. For example, A component using a service uses this method to make an object previously passed to a service method unavailable to the service provider. A component providing a service uses this method to make an object previously returned from a service method unavailable to the service user.

Repeated calls to this method with identical parameters have no effect.

Parameters:

serviceInterface - interface describing the service provided

service - object previously made available remotely by calling distributeObject().

connectDistributedObject

public void connectDistributedObject(java.lang.Object serviceObject)
                              throws java.rmi.RemoteException

This method can be used on the client side of a connection to enable a distributed object to be used. The default behavior when a service is used is for distributed objects to be connected, but the connectDistributedObjectsImmediately parameter in UseServiceParameters can be set to override this. In that case, this method would be called to connect the distributed object.

This method is also useful when dealing with a distributed object that is not a used service. For example, many service interfaces allow callback objects to be passed. To implement this behavior, the user of a service would call distributeObject() to make their callback object available remotely, pass the distributed object to the service, and the service implementation would call connectDistributedObject() to begin using the object.

Parameters:

serviceObject - a distributed object.

Throws:

java.rmi.RemoteException

disconnectDistributedObject

public void disconnectDistributedObject(java.lang.Object serviceObject)
                                 throws java.rmi.RemoteException

This method can be used on the client side of a connection to disable the connection of a distributed object. Used services are disconnected automatically on calls to discardUsedService().

This method is also useful when dealing with a distributed object that is not a used service.

Parameters:

serviceObject - a distributed object.

Throws:

java.rmi.RemoteException

discardUsedService

public void discardUsedService(UniqueID serviceID)

This method releases a synchronous (remote method) service provided by another component. This method is used to discard a service object that was being used.

Repeated calls to this method with identical parameters have no effect.

Behavior of method calls on service after calling this method is undefined, but will likely result in a RemoteException being thrown.

Parameters:

serviceID - unique service identifier returned from useService() or passed to UseServiceListener.serviceProvided().

publishService

public ServiceResult publishService(java.lang.Class serviceInterface)
                             throws InvalidServiceException

This method is used to indicate that the component will publish an asynchronous (event or messaging) service. If the topic for this interface does not exist, one is created implicitly.

Repeated calls to this method with identical parameters have no effect unless unpublishService() has been called.

Parameters:

serviceInterface - interface describing the service

Returns:

result object containing an object implementing the specified interface and a unique identifier for the service (topic)

Throws:

InvalidServiceException - thrown if serviceInterface is not a valid interface

Since:

0.9

publishService

public void publishService(java.lang.Class serviceInterface,
                           EventServiceListener listener)
                    throws InvalidServiceException

This method registers for notification of the ability to publish an asynchronous (event or messaging) service. The EventServiceListener is notified when the desired topic becomes available.

Repeated calls to this method with identical parameters have no effect unless removeEventServiceListener() has been called.

Parameters:

serviceInterface - interface describing the service

listener - notification object

Throws:

InvalidServiceException - thrown if serviceInterface is not a valid interface

Since:

0.9

unpublishService

public void unpublishService(UniqueID serviceID)

This method is used to indicate that the component will no longer publish an asynchronous (event or messaging) service. If the topic was created (implicitly or explicitly) by calling publishService(), it will be destroyed.

Repeated calls to this method with identical parameters have no effect.

Since:

0.9

removeEventServiceListener

public void removeEventServiceListener(java.lang.Class serviceInterface,
                                       EventServiceListener listener)

This method stops notification of asynchronous (event or messaging) services created by other components.

Pending callbacks may still be made to listener due to race conditions.

Service objects previously passed to the serviceAvailable() method of listener are not affected by this call.

Repeated calls to this method with identical parameters have no effect.

Parameters:

serviceInterface - interface describing the service provided

listener - a EventServiceListener previously passed to one of the publishService() / subscribeService() methods.

subscribeService

public UniqueID subscribeService(java.lang.Class serviceInterface,
                                 java.lang.Object service)
                          throws InvalidServiceException

This method is used to subscribe to a an asynchronous (event or messaging) service.

Repeated calls to this method with identical parameters have no effect unless unsubscribeService() has been called.

Parameters:

serviceInterface - interface describing the service

service - object implementing the specified interface that will receive messages

Returns:

unique identifier for the service (topic)

Throws:

InvalidServiceException - thrown if

• service does not implement serviceInterface
• serviceInterface is not a valid interface

Since:

0.9

subscribeService

public void subscribeService(java.lang.Class serviceInterface,
                             java.lang.Object service,
                             EventServiceListener listener)
                      throws InvalidServiceException

This method registers for notification of the ability to subscribe to an asynchronous (event or messaging) service. The EventServiceListener is notified when the desired topic becomes available.

Repeated calls to this method with identical arguments have no effect unless removeEventServiceListener() has been called.

Parameters:

serviceInterface - interface describing the service

service - object implementing the specified interface

listener - notification object

Throws:

InvalidServiceException - thrown if

• service does not implement serviceInterface
• serviceInterfaceis not a valid interface

Since:

0.9

unsubscribeService

public void unsubscribeService(UniqueID serviceID)

This method is used to stop subscription to a an asynchronous (event or messaging) service.

Repeated calls to this method with identical parameters have no effect.

Parameters:

serviceID - unique service identifier for the topic returned from subscribeService() or passed to EventServiceListener.serviceSubscribed().

Since:

0.9

getComponentDescriptor

public ComponentDescriptor getComponentDescriptor()

This method is used to retrieve metadata about a component

Returns:

ComponentDescriptor descriptor of this components installation

See Also:

ComponentDescriptor

getComponentID

public UniqueID getComponentID()

This method is used to retrieve a unique identifier for the component.

Returns:

unique identifier used to reference this component

shutdown

public void shutdown()

This method is used to terminate all service connections and processing provided by a Component. All objects that have been distributed by the Component are undistributed. All services provided by the Component are removed. All services being used by the Component are discarded. All services being published by the Component are unpublished. All services the Component subscribes to are unsubscribed. Any threads created by the Component implementation must exit. After this method is called, any operation on the Component is undefined.