com.sdm.quasar.client.core.dialog.impl
Interface DialogServiceProvider

All Known Subinterfaces:

DialogServiceManager

All Known Implementing Classes:

DefaultDialogServiceManager

public interface DialogServiceProvider

Offers access to services organized along a hierarchy of dialogs.

A service is defined by an interface extending the tagging interface Service and implemented by a class that implements the defining interface.

Services are organized in a hierarchy defined by a HierarchyProvider. In that hierarchy, services are registered at a node identified by an ID. Only nodes known in that hierarchy may have services registered to.

There are two methods for requesting a service:

1. You may either ask for a service that is defined somewhere in the hierarchy between the root node and one specific node by using findServiceInHierarchy(ID, Class). This method is useful if you are looking for a hierarchy dependent service or a service that may vary within a hierarchy, e.g. a display oriented service within a dialog hierarchy.
2. You may ask for a service registered at a specific node using getServiceDirect(ID, Class). This method is useful if you want to initiate a direct communication with one specific node, e.g. one specific sub dialog.

Please note that the service provider does not use any possible inheritance in the interfaces used to define service. If you have an service interface ServiceA and a service interface ServiceB that extends ServiceA, a request for ServiceA will fail if only the interface ServiceB is registered.

This interface provides only access to the service hierarchy but does not allow any modification. Services may be registered using a DialogServiceManager.

Implementations of this interface should be threadsafe.

Note: if we'd use java 1.5, this would be a generic.

Version:

1.0

Author:

Martin Haft, sd&m AG, Thomas Wolf, sd&m AG, Bernd Olleck, sd&m AG

Method Summary

void	collectSystemInfo(ID id, SystemInfoNode root, SystemInfoOptions options) Builds the system information tree upon local information of the implementor about the dialog with the ID given.
Service	findServiceInHierarchy(ID id, java.lang.Class service) Returns the first implementation of a desired service in the hierarchy starting from the node with the given id to the root node.
Service	findServiceInHierarchy(ID id, ID rootID, java.lang.Class service) Returns the first implementation of a desired service in the hierarchy starting from the node with the given id to the specified root node.
Service	getServiceDirect(ID id, java.lang.Class service) Returns the implementation of a desired service registered at the node with the given id.
boolean	hasServiceDirect(ID id, java.lang.Class service) Tests whether a specific node offers a service.
boolean	hasServiceInHierarchy(ID id, java.lang.Class service) Tests whether the service is offered in the hierarchy starting from the node with the given id.
boolean	hasServiceInHierarchy(ID id, ID rootID, java.lang.Class service) Tests whether the service is offered in the hierarchy starting from the node with the given id to the specified root node.

Method Detail

hasServiceInHierarchy

public boolean hasServiceInHierarchy(ID id,
                                     java.lang.Class service)

Tests whether the service is offered in the hierarchy starting from the node with the given id.

Parameters:

id - the id of the node at which the search starts towards the root node

service - the class of the service interface that is searched for

Returns:

true iff the service is available.

Throws:

java.lang.IllegalArgumentException - if the id is unknown or if the service class is not an interface that extends Service.

hasServiceInHierarchy

public boolean hasServiceInHierarchy(ID id,
                                     ID rootID,
                                     java.lang.Class service)

Tests whether the service is offered in the hierarchy starting from the node with the given id to the specified root node.

Parameters:

id - the id of the node at which the search starts towards the root node

rootID - the root id where to stop looking for a parent provider (may be null or not contained in id's hierarchy tree, which will be threated at the root of the current hierarchy tree)

service - the class of the service interface that is searched for

Returns:

true iff the service is available.

Throws:

java.lang.IllegalArgumentException - if the id is unknown or if the service class is not an interface that extends Service.

findServiceInHierarchy

public Service findServiceInHierarchy(ID id,
                                      java.lang.Class service)

Returns the first implementation of a desired service in the hierarchy starting from the node with the given id to the root node. The returned Object will implement the service interface.

Parameters:

id - the id of the node at which the search starts towards the root node

service - the class of the service interface that is searched for

Returns:

the object implementing the service that is registered closest to the node with the given id

Throws:

java.lang.IllegalArgumentException - if the id is unknown, if the service class is not an interface that extends Service, or if the service is not available.

findServiceInHierarchy

public Service findServiceInHierarchy(ID id,
                                      ID rootID,
                                      java.lang.Class service)

Returns the first implementation of a desired service in the hierarchy starting from the node with the given id to the specified root node. The returned Object will implement the service interface.

Parameters:

id - the id of the node at which the search starts towards the root node

rootID - the root id where to stop looking for a parent provider (may be null or not contained in id's hierarchy tree, which will be threated at the root of the current hierarchy tree)

service - the class of the service interface that is searched for

Returns:

the object implementing the service that is registered closest to the node with the given id

Throws:

java.lang.IllegalArgumentException - if the id is unknown, if the service class is not an interface that extends Service, or if the service is not available.

hasServiceDirect

public boolean hasServiceDirect(ID id,
                                java.lang.Class service)

Tests whether a specific node offers a service. In this case, the hierarchical dependency is ignored.

Parameters:

id - the id of the node

service - the class of the service interface that is searched for

Returns:

true iff the service is available.

Throws:

java.lang.IllegalArgumentException - if the id is unknown or if the service class is not an interface that extends Service.

getServiceDirect

public Service getServiceDirect(ID id,
                                java.lang.Class service)

Returns the implementation of a desired service registered at the node with the given id. The returned Object will implement the service interface.

Parameters:

id - the id of the node

service - the class of the service interface that is requested

Returns:

the object implementing the service that is registered at the specified node

Throws:

java.lang.IllegalArgumentException - if the id is unknown, if the service class is not an interface that extends Service, or if the service is not available at the given node

collectSystemInfo

public void collectSystemInfo(ID id,
                              SystemInfoNode root,
                              SystemInfoOptions options)

Builds the system information tree upon local information of the implementor about the dialog with the ID given.

Parameters:

id - the ID to append system information to the node given

root - the SystemInfoNode to add information to (guaranteed to be not null)

options - contains additional options, that might influence the amount of information added to the tree (guaranteed to be not null)