com.ibm.pim.collaboration
Interface CollaborationStep


public interface CollaborationStep

CollaborationStep represents an instance of a workflow step in a collaboration area. It lets a user access and manipulate collaboration objects, and set deadlines within the step.

Since:
6.0.0

Field Summary
static java.lang.String copyright
           
 
Method Summary
 CollaborationArea getCollaborationArea()
          Returns the collaboration area for this collaboration step.
 java.lang.String getCollaborationObjectsDetailAsXML(java.util.List<CollaborationItem> items, java.util.List<AttributeDefinition> attrPaths)
          Returns an XML representation of workflow step entries for the given Collaboration step.
 java.lang.String getCollaborationObjectsDetailAsXML(java.util.List<CollaborationItem> items, java.util.List<AttributeDefinition> attrPaths, java.lang.String dateFormat)
          Returns an XML representation of workflow step entries for the given Collaboration step, with specified date formatting.
 PIMCollection<CollaborationObject> getContents()
          Returns all the collaboration objects in this collaboration step.
 PIMCollection<CollaborationObject> getContents(Selection selection)
          Returns the collaboration objects in this collaboration step that are related to the given selection.
 PIMCollection<CollaborationObject> getContentsByAttributeValue(AttributeDefinition attributeDefinition, java.lang.Object attributeValue)
          Returns all the collaboration objects in this step whose attribute at the specified attribute definition contains the specified attribute value.
 PIMCollection<CollaborationObject> getContentsByAttributeValue(java.lang.String attributeDefinitionPath, java.lang.Object attributeValue)
          Returns all the collaboration objects in this step whose attribute at the specified path contains the specified attribute value.
 java.lang.String getName()
          Returns the name of this collaboration step.
 int getNumberOfObjects()
          Returns the number of collaboration objects in this collaboration step.
 java.util.Collection<CollaborationObject> getReservedObjects()
          Returns all collaboration objects in this collaboration step that are reserved.
 java.util.Collection<CollaborationObject> getReservedObjects(Performer performer)
          Returns all collaboration objects in this collaboration step that are reserved by the specified performer
 java.util.Collection<CollaborationObject> getReservedObjectsForCurrentUser()
          Returns all collaboration objects in this collaboration step that are reserved by the current user.
 java.util.Date getTimeout(CollaborationObject object)
          Returns the moment in time at which the specified collaboration object will timeout for this step.
 User getUserWhoReserved(CollaborationObject reservedObject)
          Returns the user to whom the specified collaboration object is reserved.
 WorkflowStep getWorkflowStep()
          Returns the workflow step for this collaboration step.
 boolean release(CollaborationObject reservedObject)
          Releases the lock on a collaboration object reserved in this step.
 boolean release(CollaborationObject reservedObject, java.lang.String comment)
          Releases the lock on a collaboration object reserved in this step, with a comment.
 boolean release(java.util.Collection<CollaborationObject> reservedObjects)
          Releases the lock on every collaboration object in the specified collection reserved in this step.
 boolean release(java.util.Collection<CollaborationObject> reservedObjects, java.lang.String comment)
          Releases the lock on every collaboration object in the specified collection reserved in this step, with a comment.
 void removeTimeout(CollaborationObject object)
          Removes any existing timeout for the given collaboration object.
 boolean reserve(CollaborationObject object)
          Acquires a lock to reserve a collaboration object in this step.
 boolean reserve(CollaborationObject object, java.lang.String comment)
          Acquires a lock to reserve a collaboration object in this step, with a comment.
 boolean reserve(java.util.Collection<CollaborationObject> objects)
          Acquires a lock on every collaboration object in the specified collection to reserve them all in this step.
 boolean reserve(java.util.Collection<CollaborationObject> objects, java.lang.String comment)
          Acquires a lock on every collaboration object in the specified collection to reserve them all in this step, with a comment.
 void setTimeout(CollaborationObject object, java.util.Date timeout)
          Sets the moment in time at which the specified collaboration object will timeout for this step.
 void setTimeout(CollaborationObject object, int duration)
          Sets the time period until the specified collaboration object will timeout for this step.
 

Field Detail

copyright

static final java.lang.String copyright
See Also:
Constant Field Values
Method Detail

getName

java.lang.String getName()
Returns the name of this collaboration step.

Returns:
the name of this collaboration step.
Throws:
PIMInternalException - if an internal error occurs.

getCollaborationArea

CollaborationArea getCollaborationArea()
Returns the collaboration area for this collaboration step.

Returns:
the collaboration area associated with this collaboration step.

getWorkflowStep

WorkflowStep getWorkflowStep()
Returns the workflow step for this collaboration step.

Returns:
the workflow step associated with this collaboration step.

getNumberOfObjects

int getNumberOfObjects()
Returns the number of collaboration objects in this collaboration step.

Note that since this method retrieves the count directly from the database, the returned count will differ from the result of getContents().size() if there have been any additions or deletions since the call to getContents.

Returns:
the number of collaboration objects in this collaboration step.
Throws:
PIMInternalException - if an internal error occurs.

getContents

PIMCollection<CollaborationObject> getContents()
Returns all the collaboration objects in this collaboration step.

Returns:
a collection of all the collaboration objects in this collaboration step, empty if there are none.
Throws:
PIMInternalException - if an internal error occurs.
See Also:
Note that this is a lazily instantiated collection.

getContents

PIMCollection<CollaborationObject> getContents(Selection selection)
Returns the collaboration objects in this collaboration step that are related to the given selection.

If the selection contains items from a catalog (the most common case), the returned collaboration objects are those whose source item is contained in the selection. If the selection contains collaboration objects, the returned collaboration objects are those that are also in the collaboration step.

Parameters:
selection - the selection to use. This parameter must not be null, and must refer to a valid selection.
Returns:
a collection of collaboration objects in this step which are also related to the specified selection, empty if there are no such collaboration objects.
Throws:
java.lang.IllegalArgumentException - if a parameter is null or refers to an invalid object.
PIMInternalException - if an internal error occurs.
java.lang.UnsupportedOperationException - if the type of the selection is not Static or Dynamic.
See Also:
Note that this is a lazily instantiated collection.

getContentsByAttributeValue

PIMCollection<CollaborationObject> getContentsByAttributeValue(java.lang.String attributeDefinitionPath,
                                                               java.lang.Object attributeValue)
Returns all the collaboration objects in this step whose attribute at the specified path contains the specified attribute value.

Note: this is supported only if this collaboration step is associated with an item collaboration area.

Parameters:
attributeDefinitionPath - the path for the attribute. This parameter must not be null.
attributeValue - the value for the attribute. This parameter must not be null, and must refer to an object of appropriate type to represent an attribute value.
Returns:
a collection containing all collaboration objects in this collaboration step whose attribute at the specified path contains the specified attribute value, empty if there are no such collaboration objects.
Throws:
java.lang.IllegalArgumentException - if either parameter is null, or if attributeValue does not refer to an object of appropriate type.
PIMInternalException - if an internal error occurs, or if this collaboration step is not associated with an item collaboration area.
See Also:
Note that this is a lazily instantiated collection.

getContentsByAttributeValue

PIMCollection<CollaborationObject> getContentsByAttributeValue(AttributeDefinition attributeDefinition,
                                                               java.lang.Object attributeValue)
Returns all the collaboration objects in this step whose attribute at the specified attribute definition contains the specified attribute value.

Note: this is supported only if this collaboration step is associated with an item collaboration area.

Parameters:
attributeDefinition - the attribute definition for the attribute to check. This parameter must not be null.
attributeValue - the value for the attribute. This parameter must not be null, and must refer to an object of appropriate type to represent an attribute value.
Returns:
a collection containing all collaboration objects in this step whose attribute at the specified attribute definition contains the specified attribute value, empty if there are no such collaboration objects.
Throws:
PIMInternalException - if an internal error occurs, or if this collaboration step is not associated with an item collaboration area.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if either parameter is null, or if attributeValue does not refer to an object of appropriate type.
See Also:
Note that this is a lazily instantiated collection.

getReservedObjects

java.util.Collection<CollaborationObject> getReservedObjects()
Returns all collaboration objects in this collaboration step that are reserved.

Returns:
a collection of all collaboration objects in this collaboration step that are reserved, empty if there are no such collaboration objects. If "reserve to edit" is not enabled in this step, the returned collection is empty.
Throws:
PIMInternalException - if an internal error occurs.

getReservedObjectsForCurrentUser

java.util.Collection<CollaborationObject> getReservedObjectsForCurrentUser()
Returns all collaboration objects in this collaboration step that are reserved by the current user.

Returns:
a collection of all collaboration objects in this collaboration step that are reserved by the current user, empty if there are no such CollaborationObjects. If "reserve to edit" is not enabled in this step, the returned collection is empty.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use

getReservedObjects

java.util.Collection<CollaborationObject> getReservedObjects(Performer performer)
Returns all collaboration objects in this collaboration step that are reserved by the specified performer

Parameters:
performer - the performer (user or role).
Returns:
a collection of collaboration objects in this collaboration step that are reserved by the specified performer, empty if there are no such collaboration objects. If "reserve to edit" is not enabled in this step, the returned collection is empty.
Throws:
PIMInternalException - if an internal error occurs.
java.lang.IllegalArgumentException - if the parameter is null.

getUserWhoReserved

User getUserWhoReserved(CollaborationObject reservedObject)
Returns the user to whom the specified collaboration object is reserved.

Parameters:
reservedObject - the collaboration object reserved in this step. This parameter must not be null.
Returns:
the User object corresponding to the user who reserved the specified collaboration object in this step.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if the parameter is null.
java.lang.UnsupportedOperationException - if the object is not in fact reserved (to anyone).

getTimeout

java.util.Date getTimeout(CollaborationObject object)
Returns the moment in time at which the specified collaboration object will timeout for this step.

Parameters:
object - the collaboration object whose timeout value is requested. This parameter must not be null.
Returns:
the date at which the specified collaboration object will timeout for this step. The precision of the value is seconds.
Throws:
PIMInternalException - if an internal error occurs.
java.lang.IllegalArgumentException - if the parameter is null.

setTimeout

void setTimeout(CollaborationObject object,
                java.util.Date timeout)
Sets the moment in time at which the specified collaboration object will timeout for this step.

Parameters:
object - the collaboration object for which to set the timeout. This parameter must not be null.
timeout - date at which the specified collaboration object will timeout for this step. The precision of the value is taken to be seconds. This parameter must not be null, and it must specify a time in the future.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - if the current user does not have the authorization to set the timeout.
java.lang.IllegalArgumentException - if either parameter is null.
java.lang.UnsupportedOperationException - if the timeout is a date in the past.

setTimeout

void setTimeout(CollaborationObject object,
                int duration)
Sets the time period until the specified collaboration object will timeout for this step.

Parameters:
object - the collaboration object for which to set the timeout. This parameter must not be null.
duration - the duration period of the timeout duration, in seconds. This parameter must be > 0.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - if the current user does not have the authorization to set the timeout.
java.lang.IllegalArgumentException - if the first parameter is null.
java.lang.UnsupportedOperationException - if the timeout is a date not in the future (that is, duration <= 0).

removeTimeout

void removeTimeout(CollaborationObject object)
Removes any existing timeout for the given collaboration object.

It is safe to invoke this method even if no timeout is defined for the collaboration object.

Parameters:
object - the collaboration object for which to remove the timeout. This parameter must not be null.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if the parameter is null.

release

boolean release(CollaborationObject reservedObject)
Releases the lock on a collaboration object reserved in this step.

This method does not return until the operation is complete.

Parameters:
reservedObject - the collaboration object reserved in this step. This parameter must not be null.
Returns:
true if the lock was released, false otherwise.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if the parameter is null.
java.lang.UnsupportedOperationException - if the object is not reserved.

release

boolean release(java.util.Collection<CollaborationObject> reservedObjects)
Releases the lock on every collaboration object in the specified collection reserved in this step.

This method does not return until the operation is complete.

This is an atomic operation - either all the locks are released, or none are.

Parameters:
reservedObjects - the collection of collaboration objects reserved in this step. This parameter must not be null.
Returns:
true if the locks on all the collaboration objects were released, false otherwise.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if the parameter is null.
java.lang.UnsupportedOperationException - if any object is not reserved.

reserve

boolean reserve(CollaborationObject object)
Acquires a lock to reserve a collaboration object in this step.

This method does not return until the operation is complete.

Parameters:
object - the collaboration object for which to acquire the lock in this step. This parameter must not be null.
Returns:
true if the lock was acquired, false otherwise.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if the parameter is null.
java.lang.UnsupportedOperationException - if the object is already reserved.

reserve

boolean reserve(java.util.Collection<CollaborationObject> objects)
Acquires a lock on every collaboration object in the specified collection to reserve them all in this step.

This method does not return until the operation is complete.

This is an atomic operation - either all the locks are acquired, or none are.

Parameters:
objects - the collection of collaboration objects to be reserved in this step. This parameter must not be null.
Returns:
true if locks were acquired for all the collaboration objects, false otherwise.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if the parameter is null.
java.lang.UnsupportedOperationException - if any object is already reserved.

release

boolean release(CollaborationObject reservedObject,
                java.lang.String comment)
Releases the lock on a collaboration object reserved in this step, with a comment.

This method does not return until the operation is complete.

Parameters:
reservedObject - the collaboration object reserved in this step. This parameter must not be null.
comment - the comment. This parameter must not be null.
Returns:
true if the lock was released, false otherwise.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if the first parameter is null.
java.lang.UnsupportedOperationException - if the object is not reserved.

release

boolean release(java.util.Collection<CollaborationObject> reservedObjects,
                java.lang.String comment)
Releases the lock on every collaboration object in the specified collection reserved in this step, with a comment.

This method does not return until the operation is complete.

This is an atomic operation - either all the locks are released, or none are.

Parameters:
reservedObjects - the collection of collaboration objects reserved in this step. This parameter must not be null.
comment - the comment. This parameter must not be null.
Returns:
true if the locks on all the collaboration objects were released, false otherwise.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if either parameter is null.
java.lang.UnsupportedOperationException - if any object is not reserved.

reserve

boolean reserve(CollaborationObject object,
                java.lang.String comment)
Acquires a lock to reserve a collaboration object in this step, with a comment.

This method does not return until the operation is complete.

Parameters:
object - the collaboration object for which to acquire the lock in this step. This parameter must not be null.
comment - the comment. This parameter must not be null.
Returns:
true if the lock was released, false otherwise.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if either parameter is null.
java.lang.UnsupportedOperationException - if the object is already reserved.

reserve

boolean reserve(java.util.Collection<CollaborationObject> objects,
                java.lang.String comment)
Acquires a lock on every collaboration object in the specified collection to reserve them all in this step, with a comment.

This method does not return until the operation is complete.

This is an atomic operation - either all the locks are acquired, or none are.

Parameters:
objects - the collection of collaboration objects for which to acquire a lock in this step. This parameter must not be null.
comment - the comment. This parameter must not be null.
Returns:
true if the lock was released, false otherwise.
Throws:
PIMInternalException - if an internal error occurs.
PIMAuthorizationException - Reserved for future use
java.lang.IllegalArgumentException - if either parameter is null.
java.lang.UnsupportedOperationException - if the object is already reserved.

getCollaborationObjectsDetailAsXML

java.lang.String getCollaborationObjectsDetailAsXML(java.util.List<CollaborationItem> items,
                                                    java.util.List<AttributeDefinition> attrPaths)
Returns an XML representation of workflow step entries for the given Collaboration step.

The attribute information of attributes present in attrPaths is included in the XML.

Parameters:
items - list of collaboration items.
attrPaths - list of attribute definitions.
Returns:
an XML representation of workflow step entries.
Throws:
PIMInternalException - if an internal error occurs.
java.lang.IllegalStateException - if the object is not in a stable persisted state.
java.lang.IllegalArgumentException - if any argument is null.
java.lang.UnsupportedOperationException - if this method is invoked on a step that belongs to a CategoryCollaborationArea.

getCollaborationObjectsDetailAsXML

java.lang.String getCollaborationObjectsDetailAsXML(java.util.List<CollaborationItem> items,
                                                    java.util.List<AttributeDefinition> attrPaths,
                                                    java.lang.String dateFormat)
Returns an XML representation of workflow step entries for the given Collaboration step, with specified date formatting.

The attribute information of attributes present in attrPaths is included in the XML. The dateFormat argument is used to control formating of the date values.

Parameters:
items - list of collaboration items.
attrPaths - list of attribute definitions.
dateFormat - the date format as required by java.text.SimpleDateFormat.
Returns:
an XML representation of workflow step entries.
Throws:
PIMInternalException - if an internal error occurs.
java.lang.IllegalStateException - if the object is not in a stable persisted state.
java.lang.IllegalArgumentException - if items or attrPaths is null or if dateFormat is null or empty.
java.lang.UnsupportedOperationException - if this method is invoked on a step that belongs to a CategoryCollaborationArea.