de.aristaflow.adept2.core.client

Interface ClientService

All Superinterfaces:

ADEPT2Service, RemoteClient

All Known Subinterfaces:

ActivityManagerService, ADEPT2ClientService, AdministrationService, ExecutionClientService, LocalExecutionClientService, ModellingClientService, RemoteExecutionClientService, WorklistClientService

All Known Implementing Classes:

MultiplexingClientService

public interface ClientService
extends ADEPT2Service, RemoteClient

This interface provides the basic logic for client components/plugins for an AristaFlow-server. Usually client components do not use this interface directly but its sub-interfaces. These provide convenient access to the required AristaFlow-services. The sub-interfaces combine sets of services that are needed for specific client logic, for instance modelling, administration or execution. Depending on its intended usage, the basic logic of a specific client (which handles the bootstrapping) provides the appropriate client services. These may also be several client services for sophisticated clients.

The ClientService manages the connection to the AristaFlow-server. Thus a client may be connected (online) or offline. Depending on its usage, some components/plugins may work offline, others do not. This has to be handled by the components/plugins but they may use the corresponding methods of this interface.
Additionally, the ClientService keeps track of the active agents of the client. One client can handle several active QualifiedAgents, which is usually used for one person having several organisational position but switching these positions spontaneously without logging off and on again. However, most (server-side) services depend on the person as well as the current organisational position. Therefore the ClientService encapsulates this by creating session tokens for accessing (server-side) services for the currently active agent (including the active organisational position).

Besides the active agent, this interface also allows to track the currently selected GUI element in case it represents a model element. For instance, there may be several client components that display related information like a worklist with worklist items and separate components displaying the user- interface of a running activities, which are based on worklist items. If several components are displayed at the same time on the screen, the coupling will have to be reflected in the user-interface. That is, when choosing a worklist item which is currently executed, the component with the corresponding user-interface should be highlighted. Vice versa, when manipulating a running activity, the corresponding item in the worklist should be highlighted.
The GUI element tracking is not restricted to worklist items (process nodes) but may include every model element, like process templates or process instances. All this kind of information may be exchanged via a client service. Components/plugins registering for GUI element changes have to check for the current selection and whether they have to respond to this. For instance, selecting a template may not be reasonably be reflected in a worklist. Bug selecting a process instance may by highlighting the items belonging to this process instance.

Author:

Ulrich Kreher

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ClientService.ActiveAgentChangedListener Listener for events that the active agent has changed.
static interface	ClientService.ServiceStateListener Listener for events that the availability of an ADEPT2Service has changed.

Method Summary

Modifier and Type	Method and Description
void	addActiveAgentListener(ClientService.ActiveAgentChangedListener listener) Adds the listener to receive events when the active agent has been changed.
void	addGUIListener(SelectedGUIElementChangedListener selectedElementChangedListener) Registers a listener to be informed about a change in the currently selected GUI element representing a model element.
boolean	addServiceStateListener(ADEPT2Service service, ClientService.ServiceStateListener listener) Registers a listener to be informed about a change in the availability of an ADEPT2Service.
RichAgent[]	agentsChanged(QualifiedAgent... agents) Signals this client service that the designated agents changed.
boolean	connectAll() Tries to connect this client service to all AristaFlow-services.
void	disconnectAll() Disconnects this client service from the AristaFlow-services.
RichAgent	getActiveAgent() Gets the currently active agent.
RichAgent[]	getAuthenticatedAgents() Gets all authenticated agents of this clients usually this is one agent holding multiple organisational positions.
Authentication	getAuthentication() Gets the manager that handles authentication for the users of this client.
java.util.Locale[]	getAvailableLocales() Gets the locales the client supports, that is, the locales found as resources.
java.lang.String	getClusterName() Gets the name of the cluster this service belongs to.
java.util.concurrent.ExecutorService	getExecutorService() Gets an ExecutorService for executing long lasting tasks asynchronously.
FilterFactory	getFilterFactory() Gets a filter factory for creating objects that allow to filter specific elements, for instance, process templates having a specific node or worklist items with specific attributes,...
SystemDataFormatterFactory	getFormatterFactory() Gets the system data formatter factory.
LicenceManager	getLicenceManager() Gets the licence manager that provides the licence for all AristaFlow-services and products.
LocalisationFactory	getLocalisationFactory() Gets the localisation factory.
LoggingScheduledThreadPoolExecutor	getScheduledExecutorService() Gets a ScheduledExecutorService for scheduling long lasting tasks asynchronously.
SessionToken	getSessionToken() Gets a session token for currently active agent and the URIs of this client.
SessionToken	getSessionToken(java.util.Map<java.lang.String,java.lang.String> additionalAttributes) Gets a session token for currently active agent and the URIs of this client having the designated additional attributes.
SessionToken	getSessionToken(QualifiedAgent agent) Gets a session token for the designated agent ignoring the currently active agent.
SessionToken	getSessionToken(QualifiedAgent agent, java.util.Map<java.lang.String,java.lang.String> additionalAttributes) Gets a session token for the designated agent ignoring the currently active agent having the designated additional attributes.
void	guiSelectionChanged(SelectedGUIElementChangedEvent selectionChangeEvent) This method informs all interested listeners about a change in the currently selected graphical representation of a model element, for instance, selecting an instance from a list of instances or the GUI element that displays the user interface of a process step and thus represents a (running) EBP-instance.
boolean	isConnected(java.lang.String serviceName) Returns whether this client is connected to the designated service or not.
void	logoff() Logs the agent (that is with all organisational positions) off and invalidates the session factories.
void	removeActiveAgentListener(ClientService.ActiveAgentChangedListener listener) Removes the listener to receive events when the active agent has been changed.
void	removeGUIListener(SelectedGUIElementChangedListener selectedElementChangedListener) Removes a listener from further notifications of the selected GUI element.
void	removeServiceStateListener(ADEPT2Service service, ClientService.ServiceStateListener listener) Removes a listener from further notifications of the designated ADEPT2Service.
void	setActiveAgent(QualifiedAgent activeAgent) Sets the currently active agent.
void	setAuthenticatedAgents(ClientSessionFactory... clientSessionFactories) Sets the client session factories for this service which provide the session tokens for the using components.

Methods inherited from interface de.aristaflow.adept2.base.service.ADEPT2Service

getLocalUris, getRelease, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, init, ping, preShutdown, shutdown, start

Methods inherited from interface de.aristaflow.adept2.core.client.RemoteClient

getDefaultCharset, getDefaultLocale, getJavaVersion, getLoggedOnAgents, getOperatingSystemArchitecture, getOperatingSystemName, getOperatingSystemVersion, getRuntimeManagerURIs, getUsedLocale, ping, serverReturned, serverShutdown

Method Detail

getAvailableLocales

java.util.Locale[] getAvailableLocales()

Gets the locales the client supports, that is, the locales found as resources. This allows the user to choose an appropriate one in case the client does not have the locale the user prefers.

Returns:

The locales available for the client.

getExecutorService

java.util.concurrent.ExecutorService getExecutorService()

Gets an ExecutorService for executing long lasting tasks asynchronously. Please do not start own threads but use this executor service instead otherwise the shutdown of the client will not work correctly since the threads cannot be reached. However, if you do, you will be responsible for terminating the threads correctly when shutting down.
The returned service must not be shutdown; this is done by implementations of the client service. Additionally, it must not be configured since it is re-used for all users of the client service.

Returns:

An ExecutorService for executing long lasting task asynchronously instead of creating own (local) threads.

getScheduledExecutorService

LoggingScheduledThreadPoolExecutor getScheduledExecutorService()

Gets a ScheduledExecutorService for scheduling long lasting tasks asynchronously. Please do not start own threads but use this executor service instead otherwise the shutdown of the client will not work correctly since the threads cannot be reached. However, if you do, you will be responsible for terminating the threads correctly when shutting down.
The returned service must not be shutdown; this is done by implementations of the client service. Additionally, it must not be configured since it is re-used for all users of the client service.

Returns:

A ScheduledExecutorService for scheduling long lasting task asynchronously instead of creating own (local) threads.

isConnected

boolean isConnected(java.lang.String serviceName)

Returns whether this client is connected to the designated service or not. If the client is not connected, the corresponding (AristaFlow-)service (managers) will be available. Components using this service have to adhere to this. A connectAll() can be tried, but this need not be successful. If the component could work offline, it should do so without accessing any server logic. Otherwise the component would have to terminate.

Parameters:

serviceName - The name of the service of which to check whether this client service is connected to.

Returns:

Whether this client is connected to the designated AristaFlow-service.

connectAll

boolean connectAll()

Tries to connect this client service to all AristaFlow-services. Whether connecting has been successful will be indicated by the return value.
Connecting an online client is a no-op.

Returns:

Whether connecting to the AristaFlow-services has been successful and the client is online now.

disconnectAll

void disconnectAll()

Disconnects this client service from the AristaFlow-services. This does all the cleanup necessary when disconnecting, for instance logging off from the appropriate server-side services. However, the client (service) will not be shut down. This is done via the registry and incorporates logging off and shutting down local services.
Disconnecting an offline client is a no-op.

addServiceStateListener

boolean addServiceStateListener(ADEPT2Service service,
                                ClientService.ServiceStateListener listener)

Registers a listener to be informed about a change in the availability of an ADEPT2Service.

Parameters:

service - The service for which to be informed about its availability.

listener - The instance which to notify in case the availability of the designated service changes.

Returns:

Whether the designated service is currently available.

removeServiceStateListener

void removeServiceStateListener(ADEPT2Service service,
                                ClientService.ServiceStateListener listener)

Removes a listener from further notifications of the designated ADEPT2Service.

Parameters:

service - The service for which to no longer be informed about its availability.

listener - The instance which to remove from availability notifications.

setAuthenticatedAgents

void setAuthenticatedAgents(ClientSessionFactory... clientSessionFactories)

Sets the client session factories for this service which provide the session tokens for the using components. This method must only be called by the component managing the logon/logoff. The session factories have to be the ones provided by the authentication (Authentication.authenticate(String, long, String)).

Parameters:

clientSessionFactories - The client session factories provided when authenticating.

agentsChanged

RichAgent[] agentsChanged(QualifiedAgent... agents)

Signals this client service that the designated agents changed. Implementations should do best effort to update the corresponding client session factory. If one of the designated agents is unknown by this client service, it will be ignored.

Parameters:

agents - The agents that have changed on the server.

Returns:

The designated agents which have been updated by this client service.

logoff

void logoff()

Logs the agent (that is with all organisational positions) off and invalidates the session factories. Afterwards no session token can be created any more.
Active agent listeners will be notified with null as active agent.

getAuthenticatedAgents

RichAgent[] getAuthenticatedAgents()

Gets all authenticated agents of this clients usually this is one agent holding multiple organisational positions. In case of no logged in agent, an empty array will be returned.

Returns:

All authenticated agents of this client (which may be an empty array).

getActiveAgent

RichAgent getActiveAgent()

Gets the currently active agent. This is normally determined by a drop-down list or the active worklist if worklists are position-specific.

Returns:

The currently active agent or null in case no agent is logged on.

setActiveAgent

void setActiveAgent(QualifiedAgent activeAgent)

Sets the currently active agent. This is either determined by a drop-down list or the active worklist if worklists are position-specific. All registered listeners will be notified (asynchronously) about this.

Parameters:

activeAgent - The currently active agent, this must not be null.

Throws:

ServiceAccessControlException - If the active agent is not one of the authenticated agents.

addActiveAgentListener

void addActiveAgentListener(ClientService.ActiveAgentChangedListener listener)

Adds the listener to receive events when the active agent has been changed.

Parameters:

listener - The listener to receive events when the active agent has been changed.

removeActiveAgentListener

void removeActiveAgentListener(ClientService.ActiveAgentChangedListener listener)

Removes the listener to receive events when the active agent has been changed.

Parameters:

listener - The active agent listener to remove.

guiSelectionChanged

void guiSelectionChanged(SelectedGUIElementChangedEvent selectionChangeEvent)

This method informs all interested listeners about a change in the currently selected graphical representation of a model element, for instance, selecting an instance from a list of instances or the GUI element that displays the user interface of a process step and thus represents a (running) EBP-instance.

Implementations for the GUI element tracking should respect the order in which events are retrieved. Otherwise it may happen that some UI elements display an old event which has been signalled after a newer event.

Parameters:

selectionChangeEvent - The event containing information like the selected element as well as the source of the event.

addGUIListener

void addGUIListener(SelectedGUIElementChangedListener selectedElementChangedListener)

Registers a listener to be informed about a change in the currently selected GUI element representing a model element.

Parameters:

selectedElementChangedListener - The listener to be informed about a change in the currently selected GUI element representing a model element.

removeGUIListener

void removeGUIListener(SelectedGUIElementChangedListener selectedElementChangedListener)

Removes a listener from further notifications of the selected GUI element.

Parameters:

selectedElementChangedListener - The listener not to be informed any more about GUI selection changes.

getSessionToken

SessionToken getSessionToken()

Gets a session token for currently active agent and the URIs of this client.

Returns:

A session token for the currently active agent and the URIs of this client or null in case no agent is active.

See Also:

ClientSessionFactory.getSessionToken()

getSessionToken

SessionToken getSessionToken(java.util.Map<java.lang.String,java.lang.String> additionalAttributes)

Gets a session token for currently active agent and the URIs of this client having the designated additional attributes.

Parameters:

additionalAttributes - Additional attributes which are provided by the created session token. This may be null.

Returns:

A session token for the currently active agent having the designated additional attributes and the URIs of this client or null in case no agent is active.

See Also:

ClientSessionFactory.getSessionToken(Map)

getSessionToken

SessionToken getSessionToken(QualifiedAgent agent)

Gets a session token for the designated agent ignoring the currently active agent. If the designated agent is not logged on, an IllegalArgumentException will be thrown.

Parameters:

agent - The agent to retrieve a session token for.

Returns:

A session token for the designated agent.

Throws:

java.lang.IllegalArgumentException - If the designated agent is currently not logged on, an IllegalArgumentException will be thrown.

getSessionToken

SessionToken getSessionToken(QualifiedAgent agent,
                             java.util.Map<java.lang.String,java.lang.String> additionalAttributes)

Gets a session token for the designated agent ignoring the currently active agent having the designated additional attributes. If the designated agent is not logged on, an IllegalArgumentException will be thrown.

Parameters:

agent - The agent to retrieve a session token for.

additionalAttributes - Additional attributes which are provided by the created session token. This may be null.

Returns:

A session token for the designated agent having the designated additional attributes.

Throws:

java.lang.IllegalArgumentException - If the designated agent is currently not logged on, an IllegalArgumentException will be thrown.

getFilterFactory

FilterFactory getFilterFactory()

Gets a filter factory for creating objects that allow to filter specific elements, for instance, process templates having a specific node or worklist items with specific attributes,... The filters apply to all model elements.

Returns:

The factory for creating filters for models for this client.

getLocalisationFactory

LocalisationFactory getLocalisationFactory()

Gets the localisation factory.

Returns:

the localisation factory

getFormatterFactory

SystemDataFormatterFactory getFormatterFactory()

Gets the system data formatter factory.

Returns:

the system data formatter factory

getAuthentication

Authentication getAuthentication()

Gets the manager that handles authentication for the users of this client.

Returns:

The manager handling authentication for the users of this client.

getLicenceManager

LicenceManager getLicenceManager()
                          throws ServiceNotKnownException

Gets the licence manager that provides the licence for all AristaFlow-services and products.

Returns:

The licence manager providing the licence for all AristaFlow-services and products.

Throws:

ServiceNotKnownException - If there are problems retrieving the licence manager, a ServiceNotKnownException will be thrown.

getClusterName

java.lang.String getClusterName()

Gets the name of the cluster this service belongs to. Use this name for identification purpose across clusters.

Returns:

The name of the cluster this service belongs to.