org.cristalise.kernel.entity

Class AgentPOATie

java.lang.Object

org.omg.PortableServer.Servant

org.cristalise.kernel.entity.AgentPOA

org.cristalise.kernel.entity.AgentPOATie

All Implemented Interfaces:

AgentOperations, ItemOperations, InvokeHandler

public class AgentPOATie
extends AgentPOA

Agent is a ManageableEntity that represents an Activity executor in the system. It holds a job list, which are persistent requests for execution from waiting activities assigned to a role that has such Job pushing enabled.

Constructor Summary

Constructors

Constructor and Description
AgentPOATie(AgentOperations delegate)
AgentPOATie(AgentOperations delegate, POA poa)

Method Summary

Modifier and Type	Method and Description
POA	_default_POA()
AgentOperations	_delegate()
void	_delegate(AgentOperations delegate)
void	addRole(String roleName) Add this Agent to the given role
String	delegatedAction(SystemKey agentKey, SystemKey delegateAgentKey, String stepPath, int transitionID, String requestData, String attachmentType, byte[] attachment)
SystemKey	getSystemKey() System generated unique key of the Entity.
void	initialise(SystemKey agentKey, String itemProps, String workflow, String collections, String viewpoint, String outcome) Initialises a new Item.
String	queryData(String path) Returns a chunk of XML which may be a serialized C2KLocalObject, or in the case of Outcomes is merely a fragment of XML.
String	queryLifeCycle(SystemKey agentKey, boolean filter) Returns a set of Jobs for this Agent on this Item.
void	refreshJobList(SystemKey itemKey, String stepPath, String newJobs) Supplies the new set of jobs for the given item and activity.
void	removeRole(String roleName) Remove this Agent from the given role
String	requestAction(SystemKey agentKey, String stepPath, int transitionID, String requestData, String attachmentType, byte[] attachment) Requests a transition of an Activity in this Item's workflow.

Methods inherited from class org.cristalise.kernel.entity.AgentPOA

_all_interfaces, _invoke, _this, _this

Methods inherited from class org.omg.PortableServer.Servant

_get_delegate, _get_interface_def, _is_a, _non_existent, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AgentPOATie

public AgentPOATie(AgentOperations delegate)

AgentPOATie

public AgentPOATie(AgentOperations delegate,
                   POA poa)

Method Detail

_delegate

public AgentOperations _delegate()

_delegate

public void _delegate(AgentOperations delegate)

_default_POA

public POA _default_POA()

Overrides:

_default_POA in class Servant

refreshJobList

public void refreshJobList(SystemKey itemKey,
                           String stepPath,
                           String newJobs)

Supplies the new set of jobs for the given item and activity. The Agent should replace all existing jobs for that activity with the given set. This method should generally only be called by a workflow while performing an execution.

Parameters:

itemKey - the item which generated the jobs. The Agent should discard any existing jobs for that Item.

stepPath - the Activity within the lifecycle of the item which the jobs relate to

newJobs - an XML marshalled JobArrayList containing the new Jobs

addRole

public void addRole(String roleName)
             throws ObjectNotFoundException,
                    CannotManageException

Add this Agent to the given role

Parameters:

roleName - the new role to add

Throws:

ObjectNotFoundException - when the role doesn't exist

CannotManageException - when an error occurs writing the data to LDAP

removeRole

public void removeRole(String roleName)
                throws ObjectNotFoundException,
                       CannotManageException

Remove this Agent from the given role

Parameters:

the - role name to remove

Throws:

CannotManageException - when an error occurs writing the data to LDAP

ObjectNotFoundException

getSystemKey

public SystemKey getSystemKey()

System generated unique key of the Entity. It is a 128 bit UUID, expressed as two 64 bit longs in the IDLs, but as a UUID object in the Java kernel. The ItemPath is used as the Item identifier in the kernel and its API, which can be derived from either a UUID object or a SystemKey structure.

initialise

public void initialise(SystemKey agentKey,
                       String itemProps,
                       String workflow,
                       String collections,
                       String viewpoint,
                       String outcome)
                throws AccessRightsException,
                       InvalidDataException,
                       PersistencyException,
                       ObjectNotFoundException,
                       InvalidCollectionModification

Initialises a new Item. Initial properties and the lifecycle are supplied. They should come from the Item's description.

Parameters:

agentKey - the Agent doing the initialisation

itemProps - The XML marshalled PropertyArrayList containing the initial Property objects of the Item

workflow - The XML marshalled new lifecycle of the Item

collection - The XML marshalled CollectionArrayList of the initial state of the Item's collections

viewpoint - the XML marshalled Viewpoint to be stored to find the Outcome

outcome - the XML data to be stored

Throws:

ObjectNotFoundException

AccessRightsException

InvalidDataException

PersistencyException

InvalidCollectionModification

queryData

public String queryData(String path)
                 throws AccessRightsException,
                        ObjectNotFoundException,
                        PersistencyException

Returns a chunk of XML which may be a serialized C2KLocalObject, or in the case of Outcomes is merely a fragment of XML.

Parameters:

path - - All Entity data is arranged in a tree structure which uniquely identifies that object within the Entity it is contained, according to the following scheme:

• LifeCycle/workflow (Items only): The Workflow object for this Item, containing the graph of activities defining the Item's lifecycle, and the Predefined Step container for data modification
• Collection/{Name} (Items only): Collection objects defining links between Items
• Property/{Name}: Name value pairs to idenfity this Entity, define its type, and hold any other oft-changing indicators that would be heavy to extract from Outcomes
• AuditTrail/{ID} (Items only): Events describing all activity state changes in this Item.
• Outcome/{Schema name}/{Schema version}/{Event ID} (Items only): XML fragments resulting from the execution of an Activity, validated against the XML Schema defined by that activity.
• ViewPoint/{Schema name}/{Name} (Items only): A named pointer to the latest version of an Outcome, defined by the Activity.
• Job/{ID} (Agents only): A persistent Job, reflecting a request for execution of an Activity to this Agent. Not all roles create persistent Jobs like this, only those specifically flagged to do so.

Returns:

The XML string of the data. All fragments except Outcomes will deserialize into objects with the kernel CastorXMLUtility available in the Gateway.

Throws:

ObjectNotFoundException - when the path is not present in this Entity

AccessRightsException - Not currently implemented

PersistencyException - when the path could not be loaded because of a problem with the storage subsystem.

See Also:

org.cristalise.kernel.persistency.ClusterStorage#getPath

requestAction

public String requestAction(SystemKey agentKey,
                            String stepPath,
                            int transitionID,
                            String requestData,
                            String attachmentType,
                            byte[] attachment)
                     throws AccessRightsException,
                            InvalidTransitionException,
                            ObjectNotFoundException,
                            InvalidDataException,
                            PersistencyException,
                            ObjectAlreadyExistsException,
                            InvalidCollectionModification

Requests a transition of an Activity in this Item's workflow. If possible and permitted, an Event is generated and stored, the Activity's state is updated, which may cause the Workflow to proceed. If this transition requires Outcome data, this is supplied and stored, and a Viewpoint will be created or updated to point to this latest version. In the case of PredefinedSteps, additional data changes may be performed in the server data. This method should not be called directly, as there is a large client side to activity execution implemented in the Proxy objects, such as script execution and schema validation.

Parameters:

agentKey - The SystemKey of the Agent. Some activities may be restricted in which roles may execute them. Some transitions cause the activity to be assigned to the executing Agent.

stepPath - The path in the Workflow to the desired Activity

transitionID - The transition to be performed

requestData - The XML Outcome of the work defined by the Activity. Must be valid to the XML Schema, though this is not verified on the server, rather in the AgentProxy in the Client API.

attachmentType - the MimeType of the attachment (can be empty)

attachment - binary data associated with the Outcome (can be empty)

Throws:

AccessRightsException - The Agent is not permitted to perform the operation. Either it does not have the correct role, or the Activity is reserved by another Agent. Also thrown when the given Agent ID doesn't exist.

InvalidTransitionException - The Activity is not in the correct state to make the requested transition.

ObjectNotFoundException - The Activity or a container of it does not exist.

InvalidDataException - An activity property for the requested Activity was invalid e.g. SchemaVersion was not a number. Also thrown when an uncaught Java exception or error occurred.

PersistencyException - There was a problem committing the changes to storage.

ObjectAlreadyExistsException - Not normally thrown, but reserved for PredefinedSteps to throw if they need to.

InvalidCollectionModification

delegatedAction

public String delegatedAction(SystemKey agentKey,
                              SystemKey delegateAgentKey,
                              String stepPath,
                              int transitionID,
                              String requestData,
                              String attachmentType,
                              byte[] attachment)
                       throws AccessRightsException,
                              InvalidTransitionException,
                              ObjectNotFoundException,
                              InvalidDataException,
                              PersistencyException,
                              ObjectAlreadyExistsException,
                              InvalidCollectionModification

Throws:

AccessRightsException

InvalidTransitionException

ObjectNotFoundException

InvalidDataException

PersistencyException

ObjectAlreadyExistsException

InvalidCollectionModification

queryLifeCycle

public String queryLifeCycle(SystemKey agentKey,
                             boolean filter)
                      throws AccessRightsException,
                             ObjectNotFoundException,
                             PersistencyException

Returns a set of Jobs for this Agent on this Item. Each Job represents a possible transition of a particular Activity in the Item's lifecycle. The list may be filtered to only refer to currently active activities.

Parameters:

agentKey - The system key of the Agent requesting Jobs.

filter - If true, then only Activities which are currently active will be included.

Returns:

An XML marshalled JobArrayList

Throws:

AccessRightsException - - when the Agent doesn't exist

ObjectNotFoundException - - when the Item doesn't have a lifecycle

PersistencyException - - when there was a storage or other unknown error