org.cristalise.kernel.entity.agent

Class ActiveEntity

java.lang.Object

org.omg.PortableServer.Servant

org.cristalise.kernel.entity.AgentPOA

org.cristalise.kernel.entity.agent.ActiveEntity

All Implemented Interfaces:

AgentOperations, ItemOperations, InvokeHandler

public class ActiveEntity
extends AgentPOA

ActiveEntity - the CORBA object representing the Agent. All functionality is delegated to the AgentImplementation, which extends ItemImplementation, as this cannot extend its equivalent TraceableEntity

Constructor Summary

Constructors

Constructor and Description
ActiveEntity(AgentPath key, POA poa)

Method Summary

Modifier and Type	Method and Description
POA	_default_POA()
void	addRole(String roleName) Add this Agent to the given role
String	delegatedAction(SystemKey agentId, SystemKey delegateAgentId, String stepPath, int transitionID, String requestData, String attachmentType, byte[] attachment)
SystemKey	getSystemKey() System generated unique key of the Entity.
void	initialise(SystemKey agentId, String propString, String initWfString, String initCollsString, String initViewpointString, String initOutcomeString) 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 agentId, boolean filter) Returns a set of Jobs for this Agent on this Item.
void	refreshJobList(SystemKey sysKey, String stepPath, String newJobs) Called by an activity when it reckons we need to update our joblist for it
void	removeRole(String roleName) Remove this Agent from the given role
String	requestAction(SystemKey agentID, 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

ActiveEntity

public ActiveEntity(AgentPath key,
                    POA poa)

Method Detail

_default_POA

public POA _default_POA()

Overrides:

_default_POA in class Servant

getSystemKey

public SystemKey getSystemKey()

Description copied from interface: ItemOperations

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.

queryData

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

Description copied from interface: ItemOperations

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:

AccessRightsException - Not currently implemented

ObjectNotFoundException - when the path is not present in this Entity

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

See Also:

ClusterStorage.getPath(org.cristalise.kernel.entity.C2KLocalObject)

refreshJobList

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

Called by an activity when it reckons we need to update our joblist for it

Parameters:

sysKey - 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 CannotManageException,
                    ObjectNotFoundException

Description copied from interface: AgentOperations

Add this Agent to the given role

Parameters:

roleName - the new role to add

Throws:

CannotManageException - when an error occurs writing the data to LDAP

ObjectNotFoundException - when the role doesn't exist

removeRole

public void removeRole(String roleName)
                throws CannotManageException,
                       ObjectNotFoundException

Description copied from interface: AgentOperations

Remove this Agent from the given role

Throws:

CannotManageException - when an error occurs writing the data to LDAP

ObjectNotFoundException

initialise

public void initialise(SystemKey agentId,
                       String propString,
                       String initWfString,
                       String initCollsString,
                       String initViewpointString,
                       String initOutcomeString)
                throws AccessRightsException,
                       InvalidDataException,
                       PersistencyException,
                       ObjectNotFoundException

Description copied from interface: ItemOperations

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

Parameters:

agentId - the Agent doing the initialisation

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

initWfString - The XML marshalled new lifecycle of the Item

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

initOutcomeString - the XML data to be stored

Throws:

ObjectNotFoundException

AccessRightsException

InvalidDataException

PersistencyException

requestAction

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

Description copied from interface: ItemOperations

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:

agentID - 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 agentId,
                              SystemKey delegateAgentId,
                              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 agentId,
                             boolean filter)
                      throws AccessRightsException,
                             ObjectNotFoundException,
                             PersistencyException

Description copied from interface: ItemOperations

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:

agentId - 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