de.aristaflow.adept2.core.worklistmanager

Interface WorklistUpdateManager

public interface WorklistUpdateManager

The WorklistUpdateManager handles the interaction between a worklist server and a worklist client. This includes creating client worklists, pulling updates, (de-)registering for pushed updates as well as updating and rejecting worklist items.

Additionally it allows to set the mail notification (sending worklists as mails) as well as the absence of a user.

Author:

Ulrich Kreher, Patrick Schmidt

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	WorklistUpdateManager.AbsenceInformation A simple data container for all absence information for a specific agent.

Method Summary

Modifier and Type	Method and Description
void	addUpdateableClientWorklist(SessionToken session, ClientWorklist worklist) Registers a client worklist so that it receives (pushed) updates.
ClientWorklist	createClientWorklist(SessionToken session, java.util.UUID worklistID, WorklistUpdateConfiguration configuration, boolean emptyWorklist) Creates a client-side worklist for the designated worklist ID with the designated configuration.
void	dropAbsence(SessionToken session, QualifiedAgent absentee) Drops the current and future absence of the designated agent.
WorklistUpdateManager.AbsenceInformation	getAbsenceInformation(SessionToken session, QualifiedAgent absentee) Gets the absence information of the designated agent (absentee).
ParameterDataContext	getAttachedDataContext(SessionToken session, java.util.UUID worklistItemID) Gets the data context for the provided worklist item which in turn provides the values of attached data elements.
WorklistUpdateConfiguration	getMailNotificationInformation(SessionToken session, QualifiedAgent mailReceiver) Gets the update configuration for the mail notification information of the designated worklist.
java.util.Set<QualifiedAgent>	getPossibleAbsentees(SessionToken session) Gets all agents for whom the designated agent (identified by the session token) may set the absence.
RemoteIterator<java.util.List<QualifiedAgent>>	getPossibleAbsenteesIterator(SessionToken session) The same as getPossibleAbsentees(SessionToken) but with partial retrieval of the agents.
WorklistUpdate	getWorklistUpdates(SessionToken session, java.util.UUID worklistID, WorklistRevision sinceRevision, Filter worklistFilter) Gets updates for the designated worklist since the designated revision (PULL by the client).
IncrementalWorklistUpdate	getWorklistUpdatesIncrementally(SessionToken session, java.util.UUID worklistID, WorklistRevision sinceRevision, Filter worklistFilter) The same as getWorklistUpdates(SessionToken, UUID, WorklistRevision, Filter) but with an update providing incremental access to the contained worklist item updates.
boolean	isRegisteredForUpdates(SessionToken session, java.util.UUID worklistId, long clientWorklistId) Gets whether the designated client worklist is currently registered for updates.
ClientWorklist	logonAndCreateClientWorklist(SessionToken session, WorklistUpdateConfiguration configuration, boolean emptyWorklist) Logs the designated agent on and creates a client-side worklist with the designated configuration.
void	rejectWorklistItem(SessionToken session, java.util.UUID worklistID, WorklistItem item) Rejects the designated worklist item by the client identified by its worklist ID.
void	removeUpdateableClientWorklist(SessionToken session, ClientWorklist worklist) Deregisters a client worklist so that it does not receive any (pushed) updates any more.
void	setAbsent(SessionToken session, QualifiedAgent absentee, long from, long to, java.lang.String substitutionRule) Sets the absence of the designated agent (absentee).
void	setMailNotification(SessionToken session, RichAgent mailReceiver, boolean mailNotify, WorklistUpdateConfiguration configuration) Activates or deactivates the mail notification for the designated agent (the explicitly provided, not the one from the session token).
void	setPresent(SessionToken session, QualifiedAgent absentee) Disables the current absence of the designated agent explicitly ignoring the to-time previously set.
boolean	updateIndividualSettings(SessionToken session, ClientWorklistItem item) Updates the worklist item according to the designated changes.

Method Detail

createClientWorklist

ClientWorklist createClientWorklist(SessionToken session,
                                    java.util.UUID worklistID,
                                    WorklistUpdateConfiguration configuration,
                                    boolean emptyWorklist)

Creates a client-side worklist for the designated worklist ID with the designated configuration. The worklist ID is the ID of the internal worklist which also applies to the returned client-side worklist. The configuration specifies which updates shall be pushed to the client worklist and which one not depending on their respective priority. The worklist configuration will only be taken into account if the client worklist is registered for updates (see addUpdateableClientWorklist(SessionToken, ClientWorklist)).

A client worklist may be retrieved several times, for instance, to allow multiple logons at the same time, and also with different configurations which supports different scenarios, for instance, a desktop computer and a PDA.

Depending on whether to retrieve an empty worklist, the returned client worklist will initially either contain no items at all or will be up-to-date. This significantly improves data transfers.
Note that an empty client worklist will have revision 0 and therefore may be registered for updates and will receive the updates normally.

In order to change the configuration, a new client worklist will have to be created. Do not forget to deregister the old client worklist and to register the new client worklist for updates! Also the client worklist listeners from the old list have to be registered with the new list.

Each worklist does contain items which represent top-level instances started by the agent owning the worklist. If that is not desired, they can be filtered out by specifying an appropriate filter in the WorklistUpdateConfiguration. WorklistFilters.noTopLevelInstances(de.aristaflow.adept2.model.filter.FilterFactory) will conveniently create such a filter. Using WorklistFilters.onlyTopLevelInstances(de.aristaflow.adept2.model.filter.FilterFactory) will result in a top-level-instance-only worklist.

Parameters:

session - The session token identifying the user to get the worklist.

worklistID - The unique ID of the worklist to retrieve.

configuration - The configuration which will apply to the returned client worklist if it is registered for updates. If this is null, a default update configuration will be used.

emptyWorklist - Whether the returned worklist should be empty and of revision 0. Otherwise it will be up-to-date containing the most recent worklist items.

Returns:

A client worklist for the designated worklist ID having the designated configuration.

logonAndCreateClientWorklist

ClientWorklist logonAndCreateClientWorklist(SessionToken session,
                                            WorklistUpdateConfiguration configuration,
                                            boolean emptyWorklist)

Logs the designated agent on and creates a client-side worklist with the designated configuration. The agent is identified by the designated session token. You need to logoff the agent when the worklist interaction is no longer needed for the agent.

The configuration specifies which updates shall be pushed to the client worklist and which one not depending on their respective priority. The worklist configuration will only be taken into account if the client worklist is registered for updates (see addUpdateableClientWorklist(SessionToken, ClientWorklist)).

A client worklist may be retrieved several times, for instance, to allow multiple logons at the same time, and also with different configurations which supports different scenarios, for instance, a desktop computer and a PDA. You will need to logoff from every concurrent logon.

Depending on whether to retrieve an empty worklist, the returned client worklist will initially either contain no items at all or will be up-to-date. This significantly improves data transfers.
Note that an empty client worklist will have revision 0 and therefore may be registered for updates and will receive the updates normally.

In order to change the configuration, a new client worklist will have to be created. Do not forget to deregister the old client worklist and to register the new client worklist for updates! Also the client worklist listeners from the old list have to be registered with the new list.

Each worklist does contain items which represent top-level instances started by the agent owning the worklist. If that is not desired, they can be filtered out by specifying an appropriate filter in the WorklistUpdateConfiguration. WorklistFilters.noTopLevelInstances(de.aristaflow.adept2.model.filter.FilterFactory) will conveniently create such a filter. Using WorklistFilters.onlyTopLevelInstances(de.aristaflow.adept2.model.filter.FilterFactory) will result in a top-level-instance-only worklist.

Parameters:

session - The session token identifying the user to logon and to get the worklist.

configuration - The configuration which will apply to the returned client worklist if it is registered for updates. If this is null, a default update configuration will be used.

emptyWorklist - Whether the returned worklist should be empty and of revision 0. Otherwise it will be up-to-date containing the most recent worklist items.

Returns:

A client worklist for the designated agent having the designated configuration.

getWorklistUpdates

WorklistUpdate getWorklistUpdates(SessionToken session,
                                  java.util.UUID worklistID,
                                  WorklistRevision sinceRevision,
                                  Filter worklistFilter)

Gets updates for the designated worklist since the designated revision (PULL by the client). If no update information for the designated revision exists any more or the initialisation date is different, a full update (i.e. with source revision ) will be returned.
A full update will also be returned if

• the designated initialisation date corresponds to the current initialisation date of the worklist,
• the designated initialisation is , or
• the designated worklist revision is null.

This method should not be used by clients when the worklist is registered for PUSH updates.

Parameters:

session - The session token identifying the user to get the worklist updates and the session for the update process.

worklistID - The ID of the worklist to retrieve updates for.

sinceRevision - The revision since when all updates are to be retrieved. This may be null.

worklistFilter - the filter used on the worklist items; may be {code null}; if the revision is greater than , this filter must be the same that has been used to retrieve previous updates; otherwise this might result in the inconsistent state of ClientWorklists

Returns:

The worklist updates containing all updates for the designated worklist since the designated revision or a full update (i.e. with source revision ) in case the revision is not explicitly managed any more.

getWorklistUpdatesIncrementally

IncrementalWorklistUpdate getWorklistUpdatesIncrementally(SessionToken session,
                                                          java.util.UUID worklistID,
                                                          WorklistRevision sinceRevision,
                                                          Filter worklistFilter)

The same as getWorklistUpdates(SessionToken, UUID, WorklistRevision, Filter) but with an update providing incremental access to the contained worklist item updates.

This method should also not be used by clients when the worklist is registered for PUSH updates.

Parameters:

session - The session token identifying the user to get the worklist updates and the session for the update process.

worklistID - The ID of the worklist to retrieve updates for.

sinceRevision - The revision since when all updates are to be retrieved. This may be null.

worklistFilter - the filter used on the worklist items; may be {code null}; if the revision is greater than , this filter must be the same that has been used to retrieve previous updates; otherwise this might result in the inconsistent state of ClientWorklists

Returns:

The worklist updates containing all updates for the designated worklist since the designated revision as incremental or a full incremental update (i.e. with source revision ) in case the revision is not explicitly managed any more.

addUpdateableClientWorklist

void addUpdateableClientWorklist(SessionToken session,
                                 ClientWorklist worklist)

Registers a client worklist so that it receives (pushed) updates.

Parameters:

session - The session token identifying the user to register the client worklist and the session for the adding process.

worklist - the worklist which should receive (pushed) updates.

removeUpdateableClientWorklist

void removeUpdateableClientWorklist(SessionToken session,
                                    ClientWorklist worklist)

Deregisters a client worklist so that it does not receive any (pushed) updates any more.

Parameters:

session - The session token identifying the user to deregister the client worklist and the session for the removal process.

worklist - the worklist which should not receive any (pushed) updates any more.

isRegisteredForUpdates

boolean isRegisteredForUpdates(SessionToken session,
                               java.util.UUID worklistId,
                               long clientWorklistId)

Gets whether the designated client worklist is currently registered for updates. In case the worklist manager is restarted, the client worklist is not registered any more but there is no way for it to detect this.

Parameters:

session - The session token identifying the user to check for the registered client worklist.

worklistId - The ID of the (internal) worklist of which to check whether a client worklist is registered for (pushed) updates.

clientWorklistId - The ID of the client worklist of which to check whether it is registered for (pushed) updates.

Returns:

Whether the designated client worklist is currently registered for (pushed) updates.

rejectWorklistItem

void rejectWorklistItem(SessionToken session,
                        java.util.UUID worklistID,
                        WorklistItem item)

Rejects the designated worklist item by the client identified by its worklist ID. If this has been the only worklist containing the item, the rejected item will be distributed to another worklist.
It is ensured that the distribution does not assign the item to the rejecting agent again.

Parameters:

session - The session token identifying the user to reject the worklist item and the session for the reject process.

worklistID - The ID of the worklist that contains the rejected worklist item. This must not be a grouping item. Such an item will lead to an IllegalArgumentException.

item - The worklist item that is rejected and needs to be distributed.

updateIndividualSettings

boolean updateIndividualSettings(SessionToken session,
                                 ClientWorklistItem item)

Updates the worklist item according to the designated changes. The updates are then propagated to the registered listeners, which implies, that the designated client worklist item may experience the same updates again.
The updates are determined by comparing the values retrieved from the designated worklist item with the internal worklist item. The latter still contains the old values.

Parameters:

session - The session token identifying the user updating the worklist item and the session for the update process.

item - The worklist item that has been changed and of which the changes are to be propagated.

Returns:

Whether the individual worklist item settings for the designated worklist item have been changed.

getAttachedDataContext

ParameterDataContext getAttachedDataContext(SessionToken session,
                                            java.util.UUID worklistItemID)

Gets the data context for the provided worklist item which in turn provides the values of attached data elements. This allows to display these values in worklists and use them for filtering and ordering.

Parameters:

session - The session token identifying the user updating the worklist item and the session for the update process.

worklistItemID - The ID of the Worklist Item the attached Data Context should be retrieved for.

Returns:

The data context containing data values attached to the Worklist Item which allow for filtering and ordering worklist items or null in case there is not data context attached or the worklist item has already been removed.

setMailNotification

void setMailNotification(SessionToken session,
                         RichAgent mailReceiver,
                         boolean mailNotify,
                         WorklistUpdateConfiguration configuration)

Activates or deactivates the mail notification for the designated agent (the explicitly provided, not the one from the session token). This allows a user to retrieve the worklist via mail. A mail contains the complete worklist and a mail is sent as soon as a normal worklist would receive a pushed update. This is specified in the designated WorklistUpdateConfiguration. Be sure to have a valid mail address for the user in the organisational model.

Parameters:

session - The session which is used to check for access rights on this method.

mailReceiver - The user to retrieve the mails. The corresponding mail address has to be set in the agent.

mailNotify - Whether the mail notification should be activated. Use false to deactivate the notification.

configuration - The worklist update configuration specifying when to sent mails. Unlike worklist updates, the sent mails always contain the complete worklist and not just the difference to the previous worklist revision. If this is null, a default update configuration will be used.

Throws:

NullArgumentException - If the mail receiver or the mail address in the rich agent is null, a NullArgumentException will be thrown.

java.lang.IllegalArgumentException - If the mail address of the receiver is invalid, an IllegalArgumentException will be thrown.

getMailNotificationInformation

WorklistUpdateConfiguration getMailNotificationInformation(SessionToken session,
                                                           QualifiedAgent mailReceiver)

Gets the update configuration for the mail notification information of the designated worklist. If the mail notification is not activated, null will be returned.

Parameters:

session - The session which is used to check for access rights on this method.

mailReceiver - The user of whom the worklist is sent as mail (if set).

Returns:

The update configuration of the worklist of the designated user for the mail notification or null in case the mail notification is not activated.

getPossibleAbsentees

java.util.Set<QualifiedAgent> getPossibleAbsentees(SessionToken session)

Gets all agents for whom the designated agent (identified by the session token) may set the absence.

Parameters:

session - The session token identifying the user to get the set of agents who may be set absent.

Returns:

A collection of agents who may be set absent by the designated agent.

getPossibleAbsenteesIterator

RemoteIterator<java.util.List<QualifiedAgent>> getPossibleAbsenteesIterator(SessionToken session)

The same as getPossibleAbsentees(SessionToken) but with partial retrieval of the agents.

Parameters:

session - The session token identifying the user to get the set of agents who may be set absent.

Returns:

An iterator providing the agents who may be set absent by the designated agent.

setAbsent

void setAbsent(SessionToken session,
               QualifiedAgent absentee,
               long from,
               long to,
               java.lang.String substitutionRule)

Sets the absence of the designated agent (absentee). All items received specifically for this agent are delegated via the designated substitutionRule

Parameters:

session - The session which is used to check for access rights on this method.

absentee - The agent who is absent for the designated time and whose worklist item will be distributed according to the designated substitution rule.

from - The absolute date from which on the agent is absent. 0 means from now on.

to - The absolute date until the agent is absent. 0 means the end date is not known and it will last until setPresent(SessionToken, QualifiedAgent).

substitutionRule - The rule which qualifies the substituting agents. This must be a valid (absolute) substitution rule. If this is null or the empty string, the agent will not have a substitute for this absence.

Throws:

ADEPT2ServiceException - If the designated substitution rule is invalid or does not qualify agents, that is, the agent set is empty, an ADEPT2ServiceException will be thrown.

dropAbsence

void dropAbsence(SessionToken session,
                 QualifiedAgent absentee)

Drops the current and future absence of the designated agent.

Parameters:

session - The session token identifying the agent who removes the (future) absence.

absentee - The agent for whom to remove the (future) absence.

getAbsenceInformation

WorklistUpdateManager.AbsenceInformation getAbsenceInformation(SessionToken session,
                                                               QualifiedAgent absentee)

Gets the absence information of the designated agent (absentee).

Parameters:

session - The session which is used to check for access rights on this method.

absentee - The agent of whom to get the absence information.

Returns:

All information concerning the absence of the designated agent, which include the time span (from- and to-date), the absentee and the staff assignment rule specifying the recipients for the worklist items. If the designated agent is not absent, null will be returned.

setPresent

void setPresent(SessionToken session,
                QualifiedAgent absentee)

Disables the current absence of the designated agent explicitly ignoring the to-time previously set.

Parameters:

session - The session token identifying the agent who sets the presence.

absentee - The agent who is present again.