com.sdm.quasar.client.core.dialog
Interface SubDialogServiceAccess

All Known Subinterfaces:

SubDialogControl

All Known Implementing Classes:

DefaultSubDialogControl

public interface SubDialogServiceAccess

Allows to register, unregister and access Services for a subdialog.

The functionality of SubDialogServiceAccess is an integral part of SubDialogControl. Every SubDialogControl is (per inheritence) a SubDialogServiceAccess!

The Services can only be found by the subdialog and it's childs using their DialogControl.findServiceInHierarchy(Class) methods - they are not part of the public interface of the subdialog. Public interfaces can only be provided by the subdialog itself.

To ease service handling, the subdialog cannot overwrite services provided for it using this interface (in this case the registration would throw an error (depending on where the subdialog was embedded to), because services must be uninstalled and cannot be overwritten). It just can shadow the service implementation. This can happen only when looking for service implementations along the hierarchy (see DialogControl.findServiceInHierarchy(Class)) where services are searched along the following order (on each dialog node for a special service key class):

1. first look for a service implementation provided for childs,
2. then look for public provided services,
3. then look for services provided by the parent (by this SubDialogServiceAccess)
4. and finally look in the parent node the same way (and so on)

The first service implementation found will be returned.

Version:

1.$Revision$

Author:

Thomas Wolf

Method Summary

Service	getService(java.lang.Class service) Returns the implementation of a desired service registered at the controlled dialog.
boolean	hasService(java.lang.Class service) Tests if a service is registered at the controlled dialog.
void	registerService(java.lang.Class service, Service implementation) Registers a service for this node.
void	registerService(java.lang.Class service, Service implementation, java.lang.String registrationContext) Registers a service for this node.
void	unregisterService(java.lang.Class service, Service implementation) Unregisters a service for this node.
void	unregisterServices(java.lang.String registrationContext) Unregisters all services registered with the same registration context

Method Detail

getService

public Service getService(java.lang.Class service)

Returns the implementation of a desired service registered at the controlled dialog. It is unimportend for this method, if the service was registered for hierarchical search or for direct access. The returned Object will implement the service interface. TODO: Wir müssen dokumentieren, welche Services man hier sieht (hierarchy, direct und FromParent)!

Parameters:

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

hasService

public boolean hasService(java.lang.Class service)

Tests if a service is registered at the controlled dialog. TODO: Wir müssen dokumentieren, welche Services man hier sieht (hierarchy, direct und FromParent)!

Parameters:

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

Returns:

true, iff the service is available.

registerService

public void registerService(java.lang.Class service,
                            Service implementation,
                            java.lang.String registrationContext)

Registers a service for this node. The service class must be an interface that extend Service, and the implementation implement that interface.

If there is already an implementation registered for that service, that implementation is replaced by the passed as a parameter.

Please note that a a registered service should be unregistered when the life cycle of the provider ends.

Parameters:

service - the interface that defines the service

implementation - the implementation of the service

registrationContext - an optional registration context (may be null); may be used for easy unregistration of services to an context (see #unregisterServices(Object))

Throws:

java.lang.IllegalArgumentException - if the providerId is unknown, service is not an interface or does not extend Service, or the implementation does not implement the interface that defines the service.

registerService

public void registerService(java.lang.Class service,
                            Service implementation)

Registers a service for this node. The service class must be an interface that extend Service, and the implementation implement that interface.

If there is already an implementation registered for that service, that implementation is replaced by the passed as a parameter.

Please note that a a registered service should be unregistered when the life cycle of the provider ends.

Parameters:

service - the interface that defines the service

implementation - the implementation of the service

Throws:

java.lang.IllegalArgumentException - if the providerId is unknown, service is not an interface or does not extend Service, or the implementation does not implement the interface that defines the service.

unregisterService

public void unregisterService(java.lang.Class service,
                              Service implementation)

Unregisters a service for this node.

If the service is not registered for this node or the given implementation is not the one that is registered, nothing happens.

Therefore, if a service implementation is replaced by another implementation, the unregistering of the first implementation is harmless since the second implementation will stay registered. However, if the second implementation is unregistered first, then no service will be available, even though the first service implementation hasn't been unregistered yet.

Parameters:

service - the interface that defines the service

implementation - the registered implementation of the service

Throws:

java.lang.IllegalArgumentException - if the providerId is unknown, service is not an interface or does not extend Service, or the implementation does not implement the interface that defines the service.

unregisterServices

public void unregisterServices(java.lang.String registrationContext)

Unregisters all services registered with the same registration context

Parameters:

registrationContext - the registration context object that mark the services to unregister