edu.nrao.sss.model.project
Class ExecutionBlock

java.lang.Object
  edu.nrao.sss.model.project.ExecutionBlock

All Implemented Interfaces:

ScheduleEntry, Identifiable, Cloneable

public class ExecutionBlock
extends Object
implements Cloneable, Identifiable, ScheduleEntry

A single execution of a SchedulingBlock. A scheduling block is a template for what should happen; an execution block is a record of what actually happened.

Version Info:

$Revision: 2190 $

$Date: 2009-04-13 15:15:03 -0600 (Mon, 13 Apr 2009) $

$Author: dharland $

Since:

2006-02-24

Author:

David M. Harland

Field Summary

Fields inherited from interface edu.nrao.sss.util.Identifiable

UNIDENTIFIED

Constructor Summary

ExecutionBlock()
Creates a new instance.

Method Summary

void	appendComments(String additionalComments) Adds additional comments to those already associated with this execution block.
void	clearId() Resets this ExecutionBlock's id to UNIDENTIFIED.
ExecutionBlock	clone() Returns a copy of this execution block.
boolean	equals(Object o) Returns true if o is equal to this execution block.
static ExecutionBlock	fromXml(Reader reader) Creates a new execution block based on the XML data read from reader.
static ExecutionBlock	fromXml(String xmlFile) Creates a new execution block from the XML data in the given file.
String	getComments() Returns comments about this execution block.
StringBuilder	getExecScript() Returns a copy of the execution script held by this block.
String	getExecutionScript() Returns the execution script held by this block.
EventStatus	getExecutionStatus() Returns information about where this entry is in its life cycle.
Date	getExecutionStatusChangeDate() Returns the point in time when this entry's status changed to its current value.
Long	getId()
SchedulingBlock	getSchedulingBlock() Returns the scheduling block to which this execution block belongs.
int	hashCode()
boolean	hasSchedulingBlock() Returns true if this execution block has a non-null scheduling block.
void	holdThisAndSiblings() Will attempt to put this EB and any of its eligible siblings on hold.
boolean	isTest() Returns true if this block is part of a test scheduling block.
void	releaseThisAndSiblings() Will attempt to release this EB and any of its eligible siblings from the on-hold status.
void	setComments(String replacementComments) Sets comments about this execution block.
void	setExecScript(StringBuilder newScript) Sets the execution script that represents this execution block.
void	setExecutionScript(String newScript) Sets the execution script that represents this execution block.
String	toXml() Returns an XML representation of this execution block.
void	updateStatusCancel() Cancels this entry so that it will never be executed or rescheduled.
void	updateStatusComplete() Brings this entry to a successful completion.
void	updateStatusExecute() Executes this entry.
void	updateStatusFail() Indicates that an execution in progress failed to complete.
void	updateStatusHold() Removes this entry from the schedule, with the intention of doing so temporarily.
void	updateStatusRelease() Releases this entry from the on-hold state so that it may be rescheduled.
void	updateStatusReschedule() Puts this entry back in the not-yet-scheduled state, thereby making it available for rescheduling.
void	updateStatusSchedule() Schedules this entry to be executed at the given time.
void	updateStatusSubmit() Submits this entry for scheduling.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this execution block to writer.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExecutionBlock

public ExecutionBlock()

Creates a new instance.

Method Detail

getId

public Long getId()

Specified by:

getId in interface Identifiable

clearId

public void clearId()

Resets this ExecutionBlock's id to UNIDENTIFIED.

getSchedulingBlock

public SchedulingBlock getSchedulingBlock()

Returns the scheduling block to which this execution block belongs.

This execution block may be one of several that belong to the same scheduling block. If this execution block belongs to no scheduling block, the value returned is null.

Specified by:

getSchedulingBlock in interface ScheduleEntry

Returns:

the scheduling block that contains this execution block.

See Also:

hasSchedulingBlock()

hasSchedulingBlock

public boolean hasSchedulingBlock()

Returns true if this execution block has a non-null scheduling block.

Execution blocks should normally be contained within, and therefore have a non-null, scheduling block. However, there are some situations where this method will return false:

1. This execution block has just been created and its scheduling block has not yet been set.
2. A client removed this execution block from its scheduling block and did not place it in a new scheduling block.
3. A client explicitly set this execution block's scheduling block to null.

Returns:

true if this execution block has a non-null scheduling block. Therefore a return value of true means that you can call getSchedulingBlock() and know that it will return a non-null object.

setExecScript

public void setExecScript(StringBuilder newScript)

Sets the execution script that represents this execution block.

Parameters:

newScript - a new execution script. This value is copied into this block, not held by it directly. If this value is null this block will hold a one-line script, where that one line is a comment.

getExecScript

public StringBuilder getExecScript()

Returns a copy of the execution script held by this block.

This method never returns null. If no script has been set, or if an attempt was made to store a null script, the returned script will be one line long and that one line will be a comment.

Returns:

a copy of the execution script held by this block.

setExecutionScript

public void setExecutionScript(String newScript)

Sets the execution script that represents this execution block. This is a convenience method that is equivalent to calling setExecScript(new StringBuilder(newScript)), provided newScript is not null.

Parameters:

newScript - a new execution script. If this value is null this block will hold a one-line script, where that one line is a comment.

getExecutionScript

public String getExecutionScript()

Returns the execution script held by this block. This is a convenience method that is equivalent to calling getExecScript().toString().

Returns:

the execution script held by this block.

See Also:

getExecScript()

setComments

public void setComments(String replacementComments)

Sets comments about this execution block. The most common use of comments for execution blocks is expected to occur when an operator wants to make note of why a block failed to execute.

Parameters:

replacementComments - free-form text about this execution block. These comments replace all previously set comments. A null value will be replaced by the empty string ("").

See Also:

appendComments(String)

appendComments

public void appendComments(String additionalComments)

Adds additional comments to those already associated with this execution block.

Parameters:

additionalComments - new, additional, comments about this execution block.

See Also:

setComments(String)

getComments

public String getComments()

Returns comments about this execution block. The value returned is guaranteed to be non-null.

Returns:

free-form text about this execution block.

See Also:

getComments(), appendComments(String), setComments(String)

isTest

public boolean isTest()

Returns true if this block is part of a test scheduling block.

Returns:

true if this block is part of a test scheduling block.

getExecutionStatus

public EventStatus getExecutionStatus()

Description copied from interface: ScheduleEntry

Returns information about where this entry is in its life cycle.

Specified by:

getExecutionStatus in interface ScheduleEntry

Returns:

the execution status of this entry.

getExecutionStatusChangeDate

public Date getExecutionStatusChangeDate()

Description copied from interface: ScheduleEntry

Returns the point in time when this entry's status changed to its current value.

Specified by:

getExecutionStatusChangeDate in interface ScheduleEntry

Returns:

the point in time when this entry's status changed to its current value.

updateStatusSubmit

public void updateStatusSubmit()
                        throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Submits this entry for scheduling.

This method is called on an entry that has just been made ready for scheduling. Typically such an entry has a status of not-ready-for-scheduling. This method will change the entry's status to not-yet-scheduled.

(The reason for the new updateStatus prefix is two fold. First, it is meant to indicate that we're not truly performing the action that the final verb indicates; only a controller of this model can really do that. The model does, though, ensure the transition is legal and may update more things than just a status property. The second reason is that using a common prefix puts all status-altering methods next to each other in an alphabetical listing. We could have collapsed these into one method with a parameter, but the EventStatus and EventSetStatus enumeration elements do not map one-to-one with these methods.)

Specified by:

updateStatusSubmit in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not in a state where it may be submitted for scheduling. For example, it would be illegal to schedule an entry that has already been canceled.

updateStatusSchedule

public void updateStatusSchedule()
                          throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Schedules this entry to be executed at the given time.

This method may be called on an entry that has already been scheduled if the client wishes to change the time at which it should be executed.

See ScheduleEntry.updateStatusSubmit() for an explanation of the new updateStatus prefix.

Specified by:

updateStatusSchedule in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not in a state where it may be scheduled. For example, it would be illegal to schedule an entry that has already been executed.

See Also:

#reschedule()

updateStatusExecute

public void updateStatusExecute()
                         throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Executes this entry.

This method is called on an entry that has been scheduled but has not yet been executed.

See ScheduleEntry.updateStatusSubmit() for an explanation of the new updateStatus prefix.

Specified by:

updateStatusExecute in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not in the scheduled-but-not-started state.

updateStatusComplete

public void updateStatusComplete()
                          throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Brings this entry to a successful completion.

This method is called on an entry that has was most recently in the in-progress state.

See ScheduleEntry.updateStatusSubmit() for an explanation of the new updateStatus prefix.

Specified by:

updateStatusComplete in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not currently in-progress.

updateStatusFail

public void updateStatusFail()
                      throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Indicates that an execution in progress failed to complete.

This method is called on an entry that has was most recently in the in-progress state. If a human wishes to stop an in-progress entry, the cancel method should be used. This method should be called by the execution process, or its proxy, to indicate that execution failed.

Specified by:

updateStatusFail in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not in-progress.

updateStatusCancel

public void updateStatusCancel()
                        throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Cancels this entry so that it will never be executed or rescheduled.

See ScheduleEntry.updateStatusSubmit() for an explanation of the new updateStatus prefix.

Specified by:

updateStatusCancel in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not in a state where it may be canceled. For example, it would be illegal to cancel an entry that has already been completed successfully.

updateStatusReschedule

public void updateStatusReschedule()
                            throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Puts this entry back in the not-yet-scheduled state, thereby making it available for rescheduling.

See ScheduleEntry.updateStatusSubmit() for an explanation of the new updateStatus prefix.

Specified by:

updateStatusReschedule in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not in a state where it may be rescheduled. Only entries that have been scheduled but not yet started may be rescheduled.

updateStatusHold

public void updateStatusHold()
                      throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Removes this entry from the schedule, with the intention of doing so temporarily. Once on hold, only the #release() and #cancel() methods can take it out of the on-hold state.

See ScheduleEntry.updateStatusSubmit() for an explanation of the new updateStatus prefix.

Specified by:

updateStatusHold in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not in a state where it may be held. An entry may be placed on hold only if it has not yet been scheduled, or if it has been scheduled but not yet started.

updateStatusRelease

public void updateStatusRelease()
                         throws IllegalTransitionException

Description copied from interface: ScheduleEntry

Releases this entry from the on-hold state so that it may be rescheduled. Once released, this entry's status will be not-yet-scheduled and it will be ready for reconsideration.

See ScheduleEntry.updateStatusSubmit() for an explanation of the new updateStatus prefix.

Specified by:

updateStatusRelease in interface ScheduleEntry

Throws:

IllegalTransitionException - if this entry is not in a state where it may be released. Only entries that are on hold may be released.

holdThisAndSiblings

public void holdThisAndSiblings()

Will attempt to put this EB and any of its eligible siblings on hold. If neither this EB nor any of its siblings may be held, this method will do nothing.

releaseThisAndSiblings

public void releaseThisAndSiblings()

Will attempt to release this EB and any of its eligible siblings from the on-hold status. If neither this EB nor any of its siblings may be released, this method will do nothing.

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this execution block.

Specified by:

toXml in interface ScheduleEntry

Returns:

an XML representation of this execution block.

Throws:

JAXBException - if anything goes wrong during the conversion to XML.

See Also:

writeAsXmlTo(Writer)

writeAsXmlTo

public void writeAsXmlTo(Writer writer)
                  throws JAXBException

Writes an XML representation of this execution block to writer.

Specified by:

writeAsXmlTo in interface ScheduleEntry

Parameters:

writer - the device to which XML is written.

Throws:

JAXBException - if anything goes wrong during the conversion to XML.

fromXml

public static ExecutionBlock fromXml(String xmlFile)
                              throws JAXBException,
                                     XMLStreamException,
                                     FileNotFoundException

Creates a new execution block from the XML data in the given file.

Parameters:

xmlFile - the name of an XML file. This method will attempt to locate the file by using Class.getResource(String).

Returns:

a new execution block from the XML data in the given file.

Throws:

FileNotFoundException - if the XML file cannot be found.

JAXBException - if the schema file used (if any) is malformed, if the XML file cannot be read, or if the XML file is not schema-valid.

XMLStreamException - if there is a problem opening the XML file, if the XML is not well-formed, or for some other "unexpected processing conditions".

fromXml

public static ExecutionBlock fromXml(Reader reader)
                              throws JAXBException,
                                     XMLStreamException

Creates a new execution block based on the XML data read from reader.

Parameters:

reader - the source of the XML data. If this value is null, null is returned.

Returns:

a new execution block based on the XML data read from reader.

Throws:

XMLStreamException - if the XML is not well-formed, or for some other "unexpected processing conditions".

JAXBException - if anything else goes wrong during the transformation.

clone

public ExecutionBlock clone()

Returns a copy of this execution block.

For the most part this block is deeply cloned. There are, however, a few exceptions to the deep copy philosophy:

1. The ID will be set to Identifiable.UNIDENTIFIED.
2. The xmlId will be unique.
3. This execution block will belong to no scheduling block.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this execution block.

In order to be equal to this block, o must be non-null and of the same class as this block. Equality is determined by examining the equality of corresponding attributes, with the following exceptions, which are ignored when assessing equality:

1. id
2. xmlId

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object