com.waveset.object
Class TaskInstance

java.lang.Object
  extended bycom.waveset.object.PersistentObject
      extended bycom.waveset.object.TaskInstance
All Implemented Interfaces:
java.lang.Comparable, javax.naming.Referenceable, XmlObject

public class TaskInstance
extends PersistentObject

A class used to represent instances of background tasks.


Nested Class Summary
 
Nested classes inherited from class com.waveset.object.PersistentObject
PersistentObject.Comparator, PersistentObject.InitialInstance
 
Field Summary
static java.lang.String code_id
           
static java.lang.String DATE_FORMAT
          Deprecated. Use Util.getCanonicalDateString and Util.stringToDate instead.
static java.lang.String OWNER_PREFIX_TEMP
           
static java.lang.String OWNER_PREFIX_USER
          Originally only Administrators could launch tasks, but eventually end-users also could launch tasks.
static java.lang.String VAR_RESULT_LIMIT
          Deprecated. - use setResultLimit(int) instead.
static java.lang.String VAR_TASK_STATUS
          Deprecated. This will be removed when VAR_RESULT_LIMIT is refactored.
 
Fields inherited from class com.waveset.object.PersistentObject
_trace, trace
 
Constructor Summary
TaskInstance()
          Create an empty task instance.
TaskInstance(org.w3c.dom.Element e)
          Create the task instance by parsing its DOM representation.
 
Method Summary
protected  void addSubclassAttributes(java.lang.StringBuffer b)
          Each concrete subclass may append to the buffer an XML representation of any fields it adds to PersistentObject (if those field values must persist).
protected  void addSubclassElements(java.lang.StringBuffer b)
          Each concrete subclass may append to the buffer an XML representation of any fields it adds to PersistentObject (if those field values must persist).
protected  WSAttribute getAttributeValues(java.lang.String attrName)
           
 TaskDefinition getDefinition()
          Get the task definition object.
 ObjectRef getDefinitionRef()
          Get the reference to the task definition.
 java.lang.String getDescription()
          Get the optional task description.
 int getExecutionTime()
          Get the cumulative execution time in seconds.
 java.util.Date getExpirationDate()
          Get the task expiration date.
 java.lang.String getExtendedStatus()
           
 XmlObject getExtension()
          Get the optional extension object.
 java.lang.String getHost()
          Get the execution host name.
 java.util.List getHosts()
           
 java.lang.String getOutputDir()
           
 java.lang.String getOwner()
          Get the task owner.
 boolean getProcessed()
           
 java.lang.String getProgress()
           
 java.util.ArrayList getReferences()
          Return the list of references within this object.
 TaskState getRequestedState()
          Get the requested task state.
 WavesetResult getResult()
          Get the result object.
 int getResultLimit()
           
 java.util.Date getResumeDate()
          Get the task resume date.
 TaskSchedule getSchedule()
          Get the task schedule object.
 ObjectRef getScheduleRef()
          Get the reference to the task schedule.
 java.util.Date getStartDate()
          Get the task start date.
 TaskState getState()
          Get the task state.
 java.lang.String getSubject()
          Get the authorization subject (serialized as XML).
 Subject getSubjectObject()
          Rebuild the Subject object.
 WSAttributes getSummaryAttributes()
           
 java.lang.String getTrackingId()
          Get the optional tracking id.
 Type getType()
          Returns the associated Type object.
 java.lang.Object getVariable(java.lang.String name)
          Get the value of one runtime variable.
 GenericObject getVariables()
          Get the runtime variables.
 boolean hasExtendedResult()
           
 void hasExtendedResult(boolean b)
           
 boolean isFinished()
          Test task completion.
 boolean isTerminated()
          Get the termation flag.
 java.util.List listQueryableAttributes()
           
 java.util.List listSummaryAttributes()
          Returns the complete list of defined attributes that this type of persistent object exposes as summary attributes (regardless of whether this particular object has a value for each).
protected  void parseSubclassAttributes(org.w3c.dom.Element e)
          Each concrete subclass should parse from the XML buffer any persisted subclass-specific fields (generally, the same ones that it writes into the buffer).
protected  void parseSubclassElements(org.w3c.dom.Element e)
          Each concrete subclass should parse from the XML buffer any persisted subclass-specific elements (generally, the same ones that it writes into the buffer).
 void setDefinition(TaskDefinition def)
          Set the task definition.
 void setDefinitionRef(ObjectRef ref)
          Set the reference to the definition.
 void setDescription(java.lang.String d)
          Set the optional task description.
 void setExecutionTime(int t)
          Set the cumulative execution time in seconds.
 void setExpirationDate(java.util.Date d)
          Set the task expiration date.
 void setExtendedStatus(java.lang.String status)
           
 void setExtension(XmlObject obj)
          Set the optional extension object.
 void setHost(java.lang.String h)
          Set the execution host.
 void setHosts(java.util.List l)
           
 void setOutputDir(java.lang.String outputDir)
           
 void setOwner(java.lang.String o)
          Set the task owner.
 void setProcessed(boolean processed)
           
 void setProgress(java.lang.String msg)
           
 void setRequestedState(TaskState s)
          Set the requsted task state.
 void setResult(WavesetResult res)
          Set the result object.
 void setResultLimit(int l)
          Set the limit in seconds that a task instance is allowed to live after the task has completed.
 void setResumeDate(java.util.Date d)
          Get the task wakup date.
 void setSchedule(TaskSchedule sched)
          Set the task schedule.
 void setScheduleRef(ObjectRef ref)
          Set the reference to the schedule.
 void setStartDate(java.util.Date d)
          Set the task start date.
 void setState(TaskState s)
          Set the task state.
 void setSubject(java.lang.String s)
          Set the authorization subject (serialized as XML).
 void setTerminated(boolean b)
          Set the termation flag.
 void setTrackingId(java.lang.String id)
          Set an optional tracking ID.
 void setVariable(java.lang.String name, java.lang.Object value)
          Set the value of one runtime variable.
 void setVariables(GenericObject vars)
          Set the entire collection of runtime variables.
 void visit(Visitor v)
          Visitor interface.
 
Methods inherited from class com.waveset.object.PersistentObject
addCommonElements, addEndTag, addMemberObjectGroup, addMemberObjectGroup, addPersistentAttributes, addStartTag, addSummaryAttributes, addXmlHeader, attributesMatch, attributesMatch, attributesMatch, checkReference, checkReferences, clearId, cloneAs, cloneObject, compareTo, create, create, create, create, createLastModItem, createLastModItem, createLastModItemList, directObjectGroupMember, dump, dumpFile, equals, fakeId, getAttribute, getAttributeValues, getAuthReferences, getAuthType, getBasicAttributes, getBasicAttributes, getBasicAttributes, getCache, getCounterValue, getCreateDate, getCreator, getDisplayableName, getDisplayName, getElementName, getEncryptedValues, getId, getIdOrName, getInitialInstances, getLastMod, getLastModDate, getLastModifier, getLastModItemId, getLockInfo, getMemberObjectGroupRefs, getMemberObjectGroupRefsUpTo, getMemberObjectGroups, getName, getNameOrId, getProperties, getProperty, getPropertyAsString, getPropertyList, getQueryableAttributes, getReference, getRuleDrivenMemberObjectGroupRefs, getRuleDrivenMemberObjectGroupRefsUpTo, getRuleDrivenMemberObjectGroups, getSubtype, getSummaryString, hasEncryptedData, hashCode, identityEquals, isAlias, isHidden, isId, isProtected, isProtectedFromDelete, isReferencedIn, listOperationalAttributes, listQueryableReferenceAttributes, objectGroupMember, objectGroupMemberRef, parseCommonElement, parseCommonElements, parsePersistentAttributes, parseXml, parseXml, prepareForSerialization, prepareToSerialize, println, reEncrypt, reEncryptSubclassAttributes, removeMemberObjectGroup, removeProperty, resolve, resolve, resolve, resolveArray, resolveArrayByFetching, resolveObjectReference, resolveObjectReferences, resolveReference, resolveSummaryAttributes, resolveSummaryAttributes, ruleDrivenObjectGroupMemberRef, setAuthType, setAuthType, setCache, setCreateDate, setCreator, setDisplayName, setDisplayName, setHidden, setIsAlias, setLastMod, setLastMod, setLastModDate, setLastModifier, setMemberObjectGroupRef, setMemberObjectGroupRefs, setMemberObjectGroups, setName, setProperties, setProperty, setPropertyList, setProtected, setProtectedFromDelete, setRuleDrivenMembersCache, setSubtype, setTrace, toString, toXml, toXml, toXml, toXmlFile
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

code_id

public static final java.lang.String code_id
See Also:
Constant Field Values

OWNER_PREFIX_USER

public static final java.lang.String OWNER_PREFIX_USER
Originally only Administrators could launch tasks, but eventually end-users also could launch tasks. Since the namespaces for administrators and users were different, this made name collisions possible. Prefixing the name of an end-user prevented such collisions. As of version 3.x, this is no longer necessary.

We do however continue to use a special prefix for tasks launched by the anonymous user GUI.

See Also:
Constant Field Values

OWNER_PREFIX_TEMP

public static final java.lang.String OWNER_PREFIX_TEMP
See Also:
Constant Field Values

VAR_RESULT_LIMIT

public static final java.lang.String VAR_RESULT_LIMIT
Deprecated. - use setResultLimit(int) instead.

The name of a variable that, if set, will override the result limit specified in the TaskDefinition. The Scheduler checks this as soon as the task completes execution. However, this value has no effect once an expiration date has been calculated.

See Also:
Constant Field Values

VAR_TASK_STATUS

public static final java.lang.String VAR_TASK_STATUS
Deprecated. This will be removed when VAR_RESULT_LIMIT is refactored.

The name of a variable that, if set, will override the "pending" that appears in executing tasks.

See Also:
Constant Field Values

DATE_FORMAT

public static final java.lang.String DATE_FORMAT
Deprecated. Use Util.getCanonicalDateString and Util.stringToDate instead.

Format string for dates.

See Also:
Constant Field Values
Constructor Detail

TaskInstance

public TaskInstance()
Create an empty task instance.


TaskInstance

public TaskInstance(org.w3c.dom.Element e)
             throws WavesetException
Create the task instance by parsing its DOM representation.

Method Detail

getType

public Type getType()
Returns the associated Type object.

Specified by:
getType in class PersistentObject

getReferences

public java.util.ArrayList getReferences()
Return the list of references within this object.

Overrides:
getReferences in class PersistentObject

visit

public void visit(Visitor v)
           throws WavesetException
Visitor interface.

Overrides:
visit in class PersistentObject
Throws:
WavesetException

getDefinitionRef

public ObjectRef getDefinitionRef()
Get the reference to the task definition.


setDefinitionRef

public void setDefinitionRef(ObjectRef ref)
Set the reference to the definition. This should only be called if you're building an instance from scratch before storing it. Don't go changing the definition of an instance that's already stored in the repository.


getDefinition

public TaskDefinition getDefinition()
                             throws WavesetException
Get the task definition object.

Throws:
WavesetException

setDefinition

public void setDefinition(TaskDefinition def)
Set the task definition. This should only be called if you're building an instance from scratch before storing it. Don't go changing the definition of an instance that's already stored in the repository.


getScheduleRef

public ObjectRef getScheduleRef()
Get the reference to the task schedule.


setScheduleRef

public void setScheduleRef(ObjectRef ref)
Set the reference to the schedule. This should only be called if you're building an instance from scratch before storing it. Don't go changing the schedule of an instance that's already stored in the repository.


getSchedule

public TaskSchedule getSchedule()
                         throws WavesetException
Get the task schedule object.

Throws:
WavesetException

setSchedule

public void setSchedule(TaskSchedule sched)
Set the task schedule. This should only be called if you're building an instance from scratch before storing it. Don't go changing the schedule of an instance that's already stored in the repository.


getDescription

public java.lang.String getDescription()
Get the optional task description.


setDescription

public void setDescription(java.lang.String d)
Set the optional task description.


getOwner

public java.lang.String getOwner()
Get the task owner.


setOwner

public void setOwner(java.lang.String o)
Set the task owner.


getState

public TaskState getState()
Get the task state.


setState

public void setState(TaskState s)
Set the task state.


isFinished

public boolean isFinished()
Test task completion.


isTerminated

public boolean isTerminated()
Get the termation flag. This will be set if the task was terminated prematurely through user intervention. The completion code must be TaskState.FINISHED for this flag to be relevant.


setTerminated

public void setTerminated(boolean b)
Set the termation flag. This will be set if the task was terminated prematurely through user intervention. The completion code must be TaskState.FINISHED for this flag to be relevant.


getStartDate

public java.util.Date getStartDate()
Get the task start date. This is the time at which the scheduler launched the task.


setStartDate

public void setStartDate(java.util.Date d)
Set the task start date.


getExpirationDate

public java.util.Date getExpirationDate()
Get the task expiration date. This is the date on which the result of a FINISHED task expires and will be removed. A date of null means there is no expiration.


setExpirationDate

public void setExpirationDate(java.util.Date d)
Set the task expiration date.

This should only be set by the scheduler when the task reaches the FINISHED state, it is used by the scheduler in queries to check for task expiry. We could use this to terminate long running EXECUTING tasks as well.

See Also:
getExpirationDate()

getExecutionTime

public int getExecutionTime()
Get the cumulative execution time in seconds.


setExecutionTime

public void setExecutionTime(int t)
Set the cumulative execution time in seconds.


setResumeDate

public void setResumeDate(java.util.Date d)
Get the task wakup date. This is relevant only for SUSPENDED tasks, when set, the scheduler will resume the task at the specified time, allowing it to run without an external trigger.


getResumeDate

public java.util.Date getResumeDate()
Get the task resume date.


getSubject

public java.lang.String getSubject()
Get the authorization subject (serialized as XML).


setSubject

public void setSubject(java.lang.String s)
Set the authorization subject (serialized as XML).


getSubjectObject

public Subject getSubjectObject()
                         throws WavesetException
Rebuild the Subject object. // !! This should be the default method, why again do we have // to maintain this as a String?

Throws:
WavesetException

setTrackingId

public void setTrackingId(java.lang.String id)
Set an optional tracking ID. This ID is one of the inline parameters and can be used in queries to find related TaskInstance objects.


getTrackingId

public java.lang.String getTrackingId()
Get the optional tracking id. This ID is one of the inline parameters and can be used in queries to find related TaskInstance objects..


getVariables

public GenericObject getVariables()
Get the runtime variables. Note that we retain a reference to the object, so if you modify it, the changes will be stored.


setVariables

public void setVariables(GenericObject vars)
Set the entire collection of runtime variables.


getVariable

public java.lang.Object getVariable(java.lang.String name)
Get the value of one runtime variable.


setVariable

public void setVariable(java.lang.String name,
                        java.lang.Object value)
Set the value of one runtime variable.


getResult

public WavesetResult getResult()
Get the result object. Depending on the executor and the task state, we may either not have a result object, or it may be an incomplete result. Note that we retain a reference to this, so if you modify the result object, the changes will be stored with the task instance.

A task always has a result object, we'll create one if necessary.


setResult

public void setResult(WavesetResult res)
Set the result object.


getHost

public java.lang.String getHost()
Get the execution host name.


setHost

public void setHost(java.lang.String h)
Set the execution host.


getExtension

public XmlObject getExtension()
Get the optional extension object.


setExtension

public void setExtension(XmlObject obj)
Set the optional extension object.


getHosts

public java.util.List getHosts()

setHosts

public void setHosts(java.util.List l)

setResultLimit

public void setResultLimit(int l)
Set the limit in seconds that a task instance is allowed to live after the task has completed.

A limit of zero means that the TaskInstance will be deleted immediately after the task is complete.

A limit of -1 means that the TaskInstance will never be automatically deleted, though it may be manually deleted by the user.


getResultLimit

public int getResultLimit()

setExtendedStatus

public void setExtendedStatus(java.lang.String status)

getExtendedStatus

public java.lang.String getExtendedStatus()

getProgress

public java.lang.String getProgress()

setProgress

public void setProgress(java.lang.String msg)

setProcessed

public void setProcessed(boolean processed)

getProcessed

public boolean getProcessed()

getOutputDir

public java.lang.String getOutputDir()

setOutputDir

public void setOutputDir(java.lang.String outputDir)

hasExtendedResult

public boolean hasExtendedResult()
Returns:
true if the associated WavesetResult object has (or objects have) been stored outside this task instance; otherwise false;

An application must call getExtendedResult() (on an instance of LocalSession, TaskManager, or Executor) in order to retrieve the associated result object(s).


hasExtendedResult

public void hasExtendedResult(boolean b)

listSummaryAttributes

public java.util.List listSummaryAttributes()
Description copied from class: PersistentObject
Returns the complete list of defined attributes that this type of persistent object exposes as summary attributes (regardless of whether this particular object has a value for each).

Any subclass of PersistentObject that overrides this method should first invoke super.listSummaryAttributes() to ensure that the subclass includes summary attributes that are common to all PersistentObjects.

Any subclass that overrides this implementation must also consider the length of the summary string that will be generated from these attributes.

Overrides:
listSummaryAttributes in class PersistentObject
Returns:
the complete list of defined attributes that this type of PersistentObject exposes as summary attributes (regardless of whether this object has a value for each).

Any subclass of PersistentObject that overrides this method should first invoke super.listSummaryAttributes() to ensure that the subclass includes summary attributes that are common to all PersistentObjects.

See Also:
Constants.MAX_SUMMARY_STRING_LENGTH, PersistentObject.getSummaryString()

listQueryableAttributes

public java.util.List listQueryableAttributes()
Overrides:
listQueryableAttributes in class PersistentObject
Returns:
the complete list of defined attributes that this type of PersistentObject exposes as queryable attributes (regardless of whether this object has a value for each).

Any subclass of PersistentObject that overrides this method should first invoke super.listQueryableAttributes() to ensure that the subclass includes queryable attributes that are common to all PersistentObjects.


getSummaryAttributes

public WSAttributes getSummaryAttributes()
Overrides:
getSummaryAttributes in class PersistentObject
Returns:
attribute values to be displayed when this object appears in a list. The WSAttributes contains a WSAttribute for each summary attribute. Each WSAttribute may contain multiple values.

Any subclass of PersistentObject that overrides this method should first invoke super.getSummaryAttributes() to ensure that the subclass includes summary attributes that are common to all PersistentObjects.

See Also:

If a subclass wants to expose a different set of summary attributes, that subclass should override {@link #listSummaryAttributes}. In order to supply values for summary attributes that may not be available in PersistentObject (e.g., from a field specified to that subclass), such a subclass may also override {@link #getAttributeValues(Attribute)}.

A subclass should not need to override this method (except to limit the number of values for a summary attribute).


getAttributeValues

protected WSAttribute getAttributeValues(java.lang.String attrName)
Overrides:
getAttributeValues in class PersistentObject
Parameters:
attrName - - the name of the attribute for which to return values.
Returns:
a WSAttribute that represents the value (or values) that this object contains for the specified attribute.


getRequestedState

public TaskState getRequestedState()
Get the requested task state. // * Temporary kludge for workflow.


setRequestedState

public void setRequestedState(TaskState s)
Set the requsted task state. // * Temporary kludge for workflow.


addSubclassAttributes

protected void addSubclassAttributes(java.lang.StringBuffer b)
Description copied from class: PersistentObject
Each concrete subclass may append to the buffer an XML representation of any fields it adds to PersistentObject (if those field values must persist). PersistentObject's default implementation is a no-op.

NOTE: Any subclass that overrides this method must similarly override parseSubclassAttributes() so that the subclass attributes are restored.

Overrides:
addSubclassAttributes in class PersistentObject
See Also:


addSubclassElements

protected void addSubclassElements(java.lang.StringBuffer b)
Description copied from class: PersistentObject
Each concrete subclass may append to the buffer an XML representation of any fields it adds to PersistentObject (if those field values must persist). PersistentObject's default implementation is a no-op.

NOTE: Any subclass that overrides this method must similarly override parseSubclassElements() so that the subclass elements are restored.

Overrides:
addSubclassElements in class PersistentObject
See Also:


parseSubclassAttributes

protected void parseSubclassAttributes(org.w3c.dom.Element e)
                                throws WavesetException
Description copied from class: PersistentObject
Each concrete subclass should parse from the XML buffer any persisted subclass-specific fields (generally, the same ones that it writes into the buffer).

Overrides:
parseSubclassAttributes in class PersistentObject
Throws:
WavesetException
See Also:

PersistentObject's default implementation is a no-op.

, PersistentObject.parseXml(Element)

parseSubclassElements

protected void parseSubclassElements(org.w3c.dom.Element e)
                              throws WavesetException
Description copied from class: PersistentObject
Each concrete subclass should parse from the XML buffer any persisted subclass-specific elements (generally, the same ones that it writes into the buffer).

Overrides:
parseSubclassElements in class PersistentObject
Throws:
WavesetException
See Also:

PersistentObject's default implementation is a no-op.

, PersistentObject.parseXml(Element)