edu.nrao.sss.model.project
Class SchedulingBlock

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

All Implemented Interfaces:

Schedulable, UserAccountable, Identifiable, Cloneable

public class SchedulingBlock
extends Object
implements Schedulable, Cloneable, Identifiable, UserAccountable

The shortest allowable contiguous block of observing time on a telescope. This is the atomic unit of observing.

A SchedulingBlock is contained in a ProgramBlock. The program block defines the configuration of the telescope. A program block may need to be broken into several scheduling blocks if, for example, 20 hours of observing time was needed for the program block, but the target source was not available for 20 consecutive hours of observing.

Version Info:

$Revision: 2277 $

$Date: 2009-04-29 11:19:38 -0600 (Wed, 29 Apr 2009) $

$Author: dharland $

Since:

2006-02-24

Author:

David M. Harland

Field Summary

static String

DEFAULT_NAME

Fields inherited from interface edu.nrao.sss.model.project.scheduling.Schedulable

NAME_SEPARATOR, OBSERVE_SCRIPT_NOT_FOUND

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

UNIDENTIFIED

Fields inherited from interface edu.nrao.sss.model.UserAccountable

NULL_USER_ID

Constructor Summary

SchedulingBlock()
Creates a new instance.

Method Summary

boolean	addPrerequisite(SchedulingBlock newPrereq) Adds newPrereq to this scheduling block's set of direct prerequisites.
void	appendComments(String additionalComments) Adds additional comments to those already associated with this scheduling block.
void	appendCommentsToOperator(String additionalComments) Adds additional comments to those already associated with this scheduling block.
TimeDuration	calculateTimePerExecution() Returns the amount of time allocated for one execution of this scheduling block.
boolean	canBeScheduled() Returns true if this scheduling block can be scheduled for observation in the face of the given conditions.
void	clearId() Resets this sb's id to UNIDENTIFIED and calls it's scan sequence's and execution block's clearId() methods.
SchedulingBlock	clone() Returns a scheduling block that is almost a copy of this one.
SchedulingBlock	cloneWithoutPrerequisites() Returns a scheduling block that is almost a copy of this one.
boolean	contains(ScanLoopElement scanOrScanLoop, EqualityMethod equalityMethod) Returns true if this scheduling block contains scanOrScanLoop.
Scan	createScan(ScanMode scanMode) Creates and returns a new scan that is suitable for use with this scheduling block.
boolean	equals(Object o) Returns true if o is equal to this scheduling block.
SchedulingConstraint	evaluateSchedulability() Returns SchedulingConstraint.NONE if this scheduling block may be scheduled for observation in the face of the given conditions.
static SchedulingBlock	fromXml(Reader reader) Creates a new scheduling block based on the XML data read from reader.
static SchedulingBlock	fromXml(String xmlFile) Creates a new scheduling block from the XML data in the given file.
int	getAbortedCount() Returns the number of times an execution of this scheduling block has been aborted.
Set<SchedulingBlock>	getAllPrerequisites() Returns a set containing all direct and indirect prerequisites of this scheduling block.
AlterationStatus	getAlterationStatus() Returns information about the manner in which this scheduling block was created and altered.
EvlaPointingPosition	getAssumedTelescopePointing() Returns the position at which the telescope is assumed to be pointing just prior to the start of this scheduling block.
int	getAuthorizedCount() Returns the number of executions authorized for this block.
String	getComments() Returns comments about this scheduling block.
String	getCommentsToOperator() Returns comments intended for use by an operator.
int	getCompletedCount() Returns the number of successful executions of this block.
String	getCompleteName()
List<Constraint>	getConstraints() Deprecated. Returns an empty list.
Long	getCreatedBy() Returns the ID of the user who created this object.
Date	getCreatedOn() Returns the date on which this object was created.
Set<SchedulingBlock>	getDirectPrerequisites() Returns this scheduling block's set of direct prerequisites.
EnvironmentalConstraints	getEnvironmentalConstraints() Returns the environmental scheduling constraints of this block.
List<ExecutionBlock>	getExecutionBlocks() Returns a complete collection of this scheduling block's execution blocks.
EventSetStatus	getExecutionStatus() Returns this scheduling block's execution status.
Date	getFixedStartTime() Returns either the time this block must be executed or null, if this block may be dynamically scheduled.
Long	getId()
Long	getLastUpdatedBy() Returns the ID of the user who most recently updated this object.
Date	getLastUpdatedOn() Returns the most recent date on which this object was updated.
String	getLongName() Deprecated.
TimeOfDayInterval	getLstStartRange() Returns the range of allowable execution start times for this scheduling block, expressed in local sidereal time.
TimeDuration	getMonitoringInterval() Returns the amount of time between successive executions of this block.
String	getName() Returns the name of this scheduling block.
SchedulingBlock	getParentBlock() Returns this block's parent, or null if it has no parent.
TimeInterval	getPreferredDateRange() Returns the preferred date range for execution of this scheduling block.
static Comparator<SchedulingBlock>	getPrequisiteComparator() Returns a comparator that places all prerequisites before the blocks that depend upon them.
List<Priority>	getPriorities() Returns the set of priorities for this scheduling block.
ProgramBlock	getProgramBlock() Returns the program block to which this scheduling block belongs, if any.
String	getProgramName()
Project	getProject() Returns the project to which this scheduling block belongs.
String	getProjectName()
String	getProposalName()
Collection<ScheduleEntry>	getReadyToScheduleEntries(Collection<ScheduleEntry> destination) Returns the schedule entries of this block that are ready for scheduling.
Set<Scan>	getScans() Returns the scans that belong to this scheduling block.
ScanLoop	getScanSequence() Returns this scheduling block's sequence of scans.
Collection<ScheduleEntry>	getScheduleEntries(EventStatus execStatus, Collection<ScheduleEntry> destination) Returns the schedule entries of this block that have an execution status of execStatus.
List<ServiceCalibration>	getServiceCalibrations() Returns a list of the service calibrations required by this scheduling block.
String	getShortName() Deprecated.
Set<Source>	getSources() Returns the sources to be observed by this scheduling block at the current time.
Set<Source>	getSources(Date dateTime) Returns the sources to be observed by this scheduling block at dateTime.
TimeDuration	getTotalTime() Returns the total time allocated to this scheduling block.
SchedulingType	getType() Returns the scheduling type to use for this scheduling block.
boolean	hasFixedStartTime() Returns true if this block must be executed at an exact point in time.
int	hashCode()
boolean	hasParentBlock() Returns true if this block has a parent block.
boolean	hasPrerequisites() Returns true if this block has one or more prequisite blocks.
boolean	hasProgramBlock() Returns true if this scheduling block has a non-null program block.
boolean	isDirectPrerequisiteOf(SchedulingBlock schedBlock) Returns true if this scheduling block is a direct prerequisite of schedBlock.
boolean	isPrerequisiteOf(SchedulingBlock schedBlock) Returns true if this scheduling block is either a direct or indirect prerequisite of schedBlock.
boolean	isTest() Returns true if this block is part of a test program.
boolean	mayBeScheduledDynamically() Returns true if this block may be scheduled dynamically.
void	removeAllPrerequisites() Clears this scheduling block's set of prerequisites.
boolean	removePrerequisite(SchedulingBlock oldPrereq) Removes oldPrereq from this scheduling block's set of direct prerequisites.
void	removeScan(Scan scan, EqualityMethod equalityMethod) Removes all occurrences of the given scan from this scheduling block.
void	reset() Resets this scheduling block to its initial state.
void	setAssumedTelescopePointing(EvlaPointingPosition newPosition) Sets the position at which the telescope is assumed to be pointing just prior to the start of this scheduling block.
void	setAuthorizedCount(int newCount) Sets the number of executions authorized for this block.
void	setComments(String replacementComments) Sets comments about this scheduling block.
void	setCommentsToOperator(String replacementComments) Stores comments intended for use by an operator.
void	setConstraints(List<Constraint> replacementList) Deprecated. Does nothing.
void	setCreatedBy(Long userId) Sets the ID of the user who created this object.
void	setCreatedOn(Date d) Sets the date on which this object was created.
void	setFixedStartTime(Date startTime) Changes the type of this block to SchedulingType.FIXED_DATE and sets the start time.
void	setLastUpdatedBy(Long userId) Sets the ID of the user who most recently updated this object.
void	setLastUpdatedOn(Date d) Sets the date on which this object was most recently updated.
void	setLongName(String newName) Deprecated.
void	setLstStartRange(TimeOfDayInterval range) Sets the range of allowable execution start times for this scheduling block, expressed in local sidereal time.
void	setMonitoringInterval(TimeDuration interval) Sets the amount of time between successive executions of this block.
void	setName(String newName) Sets the name of this scheduling block.
void	setPreferredDateRange(TimeInterval range) Sets the preferred date range for execution of this scheduling block.
void	setPriorities(List<Priority> replacementList) Sets the set of priorities of this scheduling block.
void	setProgramBlock(ProgramBlock newProgBlock) Sets the program block to which this scheduling block belongs.
void	setServiceCalibrations(List<ServiceCalibration> replacementList) Replaces this block's list of service calibrations with replacementList.
void	setShortName(String newName) Deprecated.
void	setType(SchedulingType newType) Sets the scheduling type to use for this scheduling block.
void	submit() Prepares this scheduling block for scheduling.
String	toObserveScript() Returns an observation script that is used to control a telescope.
String	toObserveScript(Date startingDate) Returns an observation script that is used to control a telescope.
String	toString() Returns a text representation of this scheduling block.
String	toSummaryString() Returns a short textual description of this scheduling block.
String	toXml() Returns an XML representation of this scheduling block.
SchedulingBlock	unsubmit() Puts an end to the life cycle of this block and potentially creates a replacement block.
boolean	useDefaultAssumedTelescopePointing() Returns true if the position provided by getAssumedTelescopePointing() is a default position.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this scheduling block to writer.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_NAME

public static final String DEFAULT_NAME

See Also:

Constant Field Values

Constructor Detail

SchedulingBlock

public SchedulingBlock()

Creates a new instance.

Method Detail

reset

public void reset()

Resets this scheduling block to its initial state. A reset block has the same state as a new block.

getId

public Long getId()

Specified by:

getId in interface Identifiable

clearId

public void clearId()

Resets this sb's id to UNIDENTIFIED and calls it's scan sequence's and execution block's clearId() methods.

setName

public void setName(String newName)

Sets the name of this scheduling block.

If newName is null or the empty string (""), the request to change the name will be denied and the current name will remain in place.

Specified by:

setName in interface Schedulable

Parameters:

newName - the new name of this scheduling block.

getName

public String getName()

Returns the name of this scheduling block.

Specified by:

getName in interface Schedulable

Returns:

the name of this scheduling block.

getLongName

@Deprecated
public String getLongName()

Deprecated.

setLongName

@Deprecated
public void setLongName(String newName)

Deprecated.

getShortName

@Deprecated
public String getShortName()

Deprecated.

setShortName

@Deprecated
public void setShortName(String newName)

Deprecated.

getProgramName

public String getProgramName()

Specified by:

getProgramName in interface Schedulable

getProjectName

public String getProjectName()

Specified by:

getProjectName in interface Schedulable

getProposalName

public String getProposalName()

Specified by:

getProposalName in interface Schedulable

getCompleteName

public String getCompleteName()

Specified by:

getCompleteName in interface Schedulable

getProject

public Project getProject()

Returns the project to which this scheduling block belongs. If this scheduling block is not currently contained by a project, the returned value will be null.

Returns:

the project that contains this scheduling block or null.

setProgramBlock

public void setProgramBlock(ProgramBlock newProgBlock)

Sets the program block to which this scheduling block belongs.

If this scheduling block is currently contained in a program block that is not the same as the newProgBlock parameter, the current program block will be told to remove this scheduling block from its collection of scheduling blocks. If newProgBlock is not null, it will be told to add this scheduling block to its collection. Finally, this scheduling block's program block will be set to newProgBlock, even if it is null.

Passing this method a newProgBlock of null has the effect of disconnecting this scheduling block from any program block.

Parameters:

newProgBlock - the program block to which this scheduling block belongs.

getProgramBlock

public ProgramBlock getProgramBlock()

Returns the program block to which this scheduling block belongs, if any.

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

Specified by:

getProgramBlock in interface Schedulable

Returns:

the program block that contains this scheduling block, if any.

See Also:

hasProgramBlock()

hasProgramBlock

public boolean hasProgramBlock()

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

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

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

Returns:

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

createScan

public Scan createScan(ScanMode scanMode)

Creates and returns a new scan that is suitable for use with this scheduling block. It will also be of a variety that is appropriate for the given observation mode. The returned scan has not been added to this scheduling block.

Returns:

a new scan that can later be added to this scheduling block.

removeScan

public void removeScan(Scan scan,
                       EqualityMethod equalityMethod)

Removes all occurrences of the given scan from this scheduling block.

In order for element to be removed from this block, it must be contained by this block. Containment is determined by the equalityMethod provided. If this parameter is null, EqualityMethod.VALUE will be used.

Parameters:

scan - the scan to be removed.

equalityMethod - determines whether containment is based on reference or value equality. A value of null will be interpreted as a signal to use value equality.

getScans

public Set<Scan> getScans()

Returns the scans that belong to this scheduling block.

The returned Set is not held directly by this scheduling block, so changes made to it will not be reflected in this object. The scans in the returned set, though, are those held by this scheduling block, so changes to those will be reflected in this object.

This is a convenience method that is equivalent to calling getScanSequence().toScanSet().

Returns:

the scans that belong to this scheduling block.

getScanSequence

public ScanLoop getScanSequence()

Returns this scheduling block's sequence of scans.

Returns:

this scheduling block's sequence of scans.

contains

public boolean contains(ScanLoopElement scanOrScanLoop,
                        EqualityMethod equalityMethod)

Returns true if this scheduling block contains scanOrScanLoop.

Containment is determined by the equalityMethod provided. If this parameter is null, EqualityMethod.VALUE will be used.

Parameters:

scanOrScanLoop - the scan or scan loop to be tested for containment.

equalityMethod - determines whether containment is based on reference or value equality. A value of null will be interpreted as a signal to use value equality.

Returns:

true if this scheduling block contains scanOrScanLoop.

addPrerequisite

public boolean addPrerequisite(SchedulingBlock newPrereq)

Adds newPrereq to this scheduling block's set of direct prerequisites. If this scheduling block belongs to a program block, and if newPrereq becomes a prerequisite of this one, then newPrereq is added to this program block, because a scheduling block that is part of a program block may have as prerequisites only those scheduling blocks that belong to the same program block.

In order to prevent a circular chain of dependencies, newPrereq will not be added to this scheduling block's set if this block is a prerequisite of newPrereq.

Direct vs. Indirect Prerequisites
The prerequisite methods of this class often refer to direct or indirect prerequisites. This section explains the meanings of those terms. Consider this set of dependencies:

   A)--+---------------+
       |-->E)--+       |
   B)--+       |       |-->G)-->H
   C           |-->F)--+
   D)----------+
 

where the notation X)-->Y means that Y is dependent on the completion of X or, alternatively, X is a prerequisite of Y.

Scheduling block E has two prerequisites, A and B, each of which is direct.
Scheduling block F has two direct prerequisites, D and E, and two indirect prerequisites, A and B.
Scheduling block G is interesting because A serves as both a direct and an indirect (via F and E) prerequisite.

Methods that refer only to prerequisite without the direct or indirect adjective mean a prerequisite of any type.

Parameters:

newPrereq - a new direct prerequisite for this scheduling block.

Returns:

true if newPrereq was added to this scheduling block's set of direct prerequisites.
The conditions that lead to a return value of false are:

1. newPrereq is null
2. newPrereq is already an direct prerequisite of this scheduling block
3. This scheduling block is currently a prequisite, direct or otherwise, of newPrereq.

removePrerequisite

public boolean removePrerequisite(SchedulingBlock oldPrereq)

Removes oldPrereq from this scheduling block's set of direct prerequisites. (For an explanation of direct versus indirect prequisites, see the note in the addPrerequisite(SchedulingBlock) method.)

Parameters:

oldPrereq - the prerequisite to be removed from this scheduling block's set of direct prerequisites.

Returns:

true if oldPrereq was successfully removed. Note that a return value of false might mean that oldPrereq was not an direct prerequisite of this scheduling block.

removeAllPrerequisites

public void removeAllPrerequisites()

Clears this scheduling block's set of prerequisites.

isPrerequisiteOf

public boolean isPrerequisiteOf(SchedulingBlock schedBlock)

Returns true if this scheduling block is either a direct or indirect prerequisite of schedBlock. (For an explanation of direct versus indirect prerequisites, see the note in the addPrerequisite(SchedulingBlock) method.)

Parameters:

schedBlock - the scheduling block to test.

Returns:

true if this scheduling block is a prerequisite of schedBlock.

See Also:

isDirectPrerequisiteOf(SchedulingBlock)

isDirectPrerequisiteOf

public boolean isDirectPrerequisiteOf(SchedulingBlock schedBlock)

Returns true if this scheduling block is a direct prerequisite of schedBlock. (For an explanation of direct versus indirect prequisites, see the note in the addPrerequisite(SchedulingBlock) method.)

Parameters:

schedBlock - the scheduling block to test.

Returns:

true if this scheduling block is an direct prerequisite of schedBlock.

See Also:

isPrerequisiteOf(SchedulingBlock)

hasPrerequisites

public boolean hasPrerequisites()

Returns true if this block has one or more prequisite blocks.

Returns:

true if this block has one or more prequisite blocks.

getDirectPrerequisites

public Set<SchedulingBlock> getDirectPrerequisites()

Returns this scheduling block's set of direct prerequisites.

The returned Set is an unmodifiable set that will not permit additions of new elements or deletions of existing elements. Attempts to modify the set will result in UnsupportedOperationExceptions.

Returns:

this scheduling block's set of direct prerequisites.

getAllPrerequisites

public Set<SchedulingBlock> getAllPrerequisites()

Returns a set containing all direct and indirect prerequisites of this scheduling block. (For an explanation of direct versus indirect prequisites, see the note in the addPrerequisite(SchedulingBlock) method.)

Returns:

a set containing all prerequisites of this scheduling block.

hasParentBlock

public boolean hasParentBlock()

Returns true if this block has a parent block. Most blocks do not have parent blocks. One known situation where a block does have a parent is when it was created as the result of an unsubmit operation on the parent.

Returns:

true if this block has a parent block.

See Also:

getParentBlock()

getParentBlock

public SchedulingBlock getParentBlock()

Returns this block's parent, or null if it has no parent. Most blocks do not have parent blocks.

Returns:

true if this block has a parent block.

See Also:

hasParentBlock()

setType

public void setType(SchedulingType newType)

Sets the scheduling type to use for this scheduling block. If newType is null, it will be interpreted as the default type.

Specified by:

setType in interface Schedulable

Parameters:

newType - the new scheduling type for this block.

getType

public SchedulingType getType()

Returns the scheduling type to use for this scheduling block.

Specified by:

getType in interface Schedulable

Returns:

the scheduling type to use for this scheduling block.

mayBeScheduledDynamically

public boolean mayBeScheduledDynamically()

Returns true if this block may be scheduled dynamically. The only time this method returns false is when this block's type is SchedulingType.FIXED_DATE.

Returns:

true if this block may be scheduled dynamically.

Since:

2008-07-25

getAlterationStatus

public AlterationStatus getAlterationStatus()

Returns information about the manner in which this scheduling block was created and altered.

Returns:

this scheduling block's alteration status.

isTest

public boolean isTest()

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

Returns:

true if this block is part of a test program.

getExecutionStatus

public EventSetStatus getExecutionStatus()

Returns this scheduling block's execution status.

Specified by:

getExecutionStatus in interface Schedulable

Returns:

this scheduling block's execution status.

submit

public void submit()

Prepares this scheduling block for scheduling.

This method is intended to be used no more than once on this scheduling block. It will not have any effect unless this scheduling block is in its initial status of not-ready-to-be-scheduled. Note that this method no longer checks this block for warnings and errors. It is now the responsibility of clients to decide if this block is fit for scheduling.

When called on a block in its initial status, this method will result in the creation of a number of execution blocks equal to the authorized count of this block and will result in a new status of not-yet-scheduled.

Throws:

RuntimeException - if this block has not yet been scheduled but already has execution blocks. Only an internal programmer error should lead to this situation (or perhaps bad data coming from a persistent store, such as XML or a database).

unsubmit

public SchedulingBlock unsubmit()

Puts an end to the life cycle of this block and potentially creates a replacement block.

Modifications of This Block
The authorization count of this block is set to the number of successful iterations. This means that after the call this block is no longer authorized for more iterations, and that it has a status of complete or canceled.

Creation of a Replacement Block
If at the time this block was unsubmitted it had more authorized iterations, those iterations will be transfered to a replacement block. It is this replacement block that is returned. The replacement block will have an authorized count equal to the unrun iterations of this block. The replacement block will have this block as a parent. The replacement block will be in a not-ready-to-be-scheduled state with no execution blocks, meaning that it may be later submitted. Finally, if this block was a prerequisite of any other blocks, those blocks will now depend on the replacement and not on this one.

If this block had no more authorized iterations at the time of the unsubmit, there will be no replacement and the return value will be null.

Returns:

a new scheduling block to replace this one, or null.

getAuthorizedCount

public int getAuthorizedCount()

Returns the number of executions authorized for this block.

Specified by:

getAuthorizedCount in interface Schedulable

Returns:

the number of executions authorized for this block.

setAuthorizedCount

public void setAuthorizedCount(int newCount)

Sets the number of executions authorized for this block.

The authorized count may never be set to a value less than that of the number of successful executions already completed. An attempt to set the value below this minimum will be silently reinterpreted as a request to set it to this minimum. This means that a convenient way to prevent future runs of this block is to use a value less than one.

If the request to increase or decrease the number of authorized iterations is made prior to submitting this block for scheduling, then the authorized count is simply updated to the requested value (subject to the paragraph above). If, though, the request is made after this block has already been submitted, this method will attempt to add or remove execution blocks.

Specified by:

setAuthorizedCount in interface Schedulable

Parameters:

newCount - the new number of executions authorized for this block.

getCompletedCount

public int getCompletedCount()

Returns the number of successful executions of this block.

Specified by:

getCompletedCount in interface Schedulable

Returns:

the number of successful executions of this block.

getAbortedCount

public int getAbortedCount()

Returns the number of times an execution of this scheduling block has been aborted.

Returns:

the number of aborted executions for this block.

getScheduleEntries

public Collection<ScheduleEntry> getScheduleEntries(EventStatus execStatus,
                                                    Collection<ScheduleEntry> destination)

Returns the schedule entries of this block that have an execution status of execStatus. Only the status of the entries is considered. This method does not look, for example, at the isTest() property.

Parameters:

execStatus - the execution status of the schedule entries to be added to destination.

destination - the collection to which the schedule entries should be added. If this collection is null, a new one will be created. This collection is returned.

Returns:

the collection holding the schedule entries. This will be either destination or a new collection, if destination is null.

See Also:

getReadyToScheduleEntries(Collection)

getReadyToScheduleEntries

public Collection<ScheduleEntry> getReadyToScheduleEntries(Collection<ScheduleEntry> destination)

Returns the schedule entries of this block that are ready for scheduling. If this is a test scheduling block, or if this block has no NOT_YET_SCHEDULED entries, the returned collection will be empty.

Parameters:

destination - the collection to which the ready-to-be-scheduled entries should be added. If this collection is null, a new one will be created. This collection is returned.

Returns:

a collection of ready-to-be-scheduled entries, or an empty collection. The returned collection will be either destination or a new collection, if destination is null.

See Also:

getScheduleEntries(EventStatus, Collection)

getExecutionBlocks

public List<ExecutionBlock> getExecutionBlocks()

Returns a complete collection of this scheduling block's execution blocks. The returned collection is not held internally by this scheduling block, so changes made to it will not be reflected herein.

Returns:

this SB's execution blocks.

hasFixedStartTime

public boolean hasFixedStartTime()

Returns true if this block must be executed at an exact point in time.

Returns:

true if this block must be executed at an exact point in time.

Since:

2008-07-25

getFixedStartTime

public Date getFixedStartTime()

Returns either the time this block must be executed or null, if this block may be dynamically scheduled.

Returns:

if this block must be executed at a particular point in time, that point in time. Otherwise null is returned, indicating that this block may be scheduled dynamically.

Since:

2008-07-25

setFixedStartTime

public void setFixedStartTime(Date startTime)

Changes the type of this block to SchedulingType.FIXED_DATE and sets the start time.

Parameters:

startTime - the time at which this block must be executed. If this value is null this method does nothing.

Since:

2008-07-25

calculateTimePerExecution

public TimeDuration calculateTimePerExecution()

Returns the amount of time allocated for one execution of this scheduling block.

Specified by:

calculateTimePerExecution in interface Schedulable

Returns:

the amount of time allocated for one execution of this scheduling block.

Throws:

ValidationException - if this method is unable to calculate the SB's length due to a lack of information in the SB.

getTotalTime

public TimeDuration getTotalTime()

Returns the total time allocated to this scheduling block. The total time is defined as: calculateTimePerExecution() * getAuthorizedCount().

Returns:

the total time allocated to this scheduling block.

setPreferredDateRange

public void setPreferredDateRange(TimeInterval range)

Sets the preferred date range for execution of this scheduling block.

Note that this scheduling block will not hold a reference to range, but will instead keep a copy of it.

Specified by:

setPreferredDateRange in interface Schedulable

Parameters:

range - the preferred date range for execution of this scheduling block.

getPreferredDateRange

public TimeInterval getPreferredDateRange()

Returns the preferred date range for execution of this scheduling block. The returned interval is a copy of the one held internally by this block.

Specified by:

getPreferredDateRange in interface Schedulable

Returns:

the preferred date range for execution of this scheduling block.

setLstStartRange

public void setLstStartRange(TimeOfDayInterval range)

Sets the range of allowable execution start times for this scheduling block, expressed in local sidereal time.

Note that this scheduling block will hold a reference to range (unless it is null); it will not store a copy. This means that any changes a client makes to range after calling this method will be reflected in this object.

Specified by:

setLstStartRange in interface Schedulable

Parameters:

range -

getLstStartRange

public TimeOfDayInterval getLstStartRange()

Returns the range of allowable execution start times for this scheduling block, expressed in local sidereal time.

The returned range, which is guaranteed to be non-null, is the actual range held by this block, so changes made to it will be reflected in this object.

Specified by:

getLstStartRange in interface Schedulable

Returns:

the allowable LST range for beginning execution of this scheduling block.

setMonitoringInterval

public void setMonitoringInterval(TimeDuration interval)

Sets the amount of time between successive executions of this block.

Note that this scheduling block will hold a reference to interval (unless it is null); it will not store a copy. This means that any changes a client makes to interval after calling this method will be reflected in this object.

Parameters:

interval - the amount of time between successive executions of this block.

getMonitoringInterval

public TimeDuration getMonitoringInterval()

Returns the amount of time between successive executions of this block.

The returned amount, which is guaranteed to be non-null, is the actual amount held by this block, so changes made to it will be reflected in this object.

Returns:

the amount of time between successive executions of this block.

setConstraints

@Deprecated
public void setConstraints(List<Constraint> replacementList)

Deprecated. Does nothing.

Description copied from interface: Schedulable

Sets the requirements that can be used to determine the success of a scheduling block under current conditions.

Specified by:

setConstraints in interface Schedulable

Parameters:

replacementList - a set of environmental and telescopes constraints such as recent calibration accuracies that can be used to determine the success of this scheduling block under current conditions.

getConstraints

@Deprecated
public List<Constraint> getConstraints()

Deprecated. Returns an empty list.

Description copied from interface: Schedulable

Returns a set of requirements that can be used to determine the success of a scheduling block under current conditions.

Specified by:

getConstraints in interface Schedulable

Returns:

a set of requirements that can be used to determine the success of this scheduling block under current conditions.

getEnvironmentalConstraints

public EnvironmentalConstraints getEnvironmentalConstraints()

Returns the environmental scheduling constraints of this block.

The returned object, which is guaranteed to be non-null, is the actual instance held by this block, so changes made to it will be reflected in this scheduling block.

Returns:

the environmental scheduling constraints of this block.

setAssumedTelescopePointing

public void setAssumedTelescopePointing(EvlaPointingPosition newPosition)

Sets the position at which the telescope is assumed to be pointing just prior to the start of this scheduling block.

A value of null is permitted and will result in the corresponding getter returning a default position. Note that when newPosition is not null this method does not hold a reference to it, but holds a copy.

Parameters:

newPosition - the new assumed telescope pointing position.

Since:

2009-02-18

getAssumedTelescopePointing

public EvlaPointingPosition getAssumedTelescopePointing()

Returns the position at which the telescope is assumed to be pointing just prior to the start of this scheduling block. The returned value is never null. It is either equal to the value most recently send to the corresponding setter or, if that value was null, is a default position.

The returned object is not held internally by this scheduling block, so changes made to it will not be reflected herein.

Returns:

the position at which the telescope is assumed to be pointing just prior to the start of this scheduling block.

Since:

2009-02-18

useDefaultAssumedTelescopePointing

public boolean useDefaultAssumedTelescopePointing()

Returns true if the position provided by getAssumedTelescopePointing() is a default position.

Returns:

Returns true if the position provided by getAssumedTelescopePointing() is a default position.

setPriorities

public void setPriorities(List<Priority> replacementList)

Sets the set of priorities of this scheduling block.

Specified by:

setPriorities in interface Schedulable

Parameters:

replacementList - a set of priorities representing the importance of this scheduling block with regard to a variety of criteria such as scientific rating, etc. If replacementList is null, it will be interpreted as an empty list.

getPriorities

public List<Priority> getPriorities()

Returns the set of priorities for this scheduling block.

Specified by:

getPriorities in interface Schedulable

Returns:

the set of priorities for this scheduling block.

getSources

public Set<Source> getSources()

Returns the sources to be observed by this scheduling block at the current time. The current time is used to evaluate any SourceLookupTables held by this scheduling block.

Returns:

the sources to be observed at the current time.

getSources

public Set<Source> getSources(Date dateTime)

Returns the sources to be observed by this scheduling block at dateTime. The dateTime parameter is used to evaluate any SourceLookupTables held by this scheduling block.

Parameters:

dateTime - the time for which sources are requested.

Returns:

the sources to be observed at the given time.

setServiceCalibrations

public void setServiceCalibrations(List<ServiceCalibration> replacementList)

Replaces this block's list of service calibrations with replacementList.

Parameters:

replacementList - a replacement list of service calibrations for this scheduling block. If replacementList is null, it will be interpreted as an empty list.

getServiceCalibrations

public List<ServiceCalibration> getServiceCalibrations()

Returns a list of the service calibrations required by this scheduling block.

The return value is guaranteed to be non-null. It is also the list that is held internally by this scheduling block, so any changes made to the returned list will be reflected in this object.

Returns:

a list of the service calibrations required by this scheduling block.

canBeScheduled

public boolean canBeScheduled()

Returns true if this scheduling block can be scheduled for observation in the face of the given conditions.

This scheduling block compares the given conditions to its constraints and decides whether or not it may be submitted for scheduling. This method is biased toward returning a value of true so that the scheduler can be presented with as many scheduling blocks as possible. This method returns false only when the conditions are so negative (for example, if the source is not in the sky at the time of condition XXX) that scheduling makes no sense at all.

Specified by:

canBeScheduled in interface Schedulable

Returns:

true if this scheduling block can be scheduled for observation.

See Also:

evaluateSchedulability()

evaluateSchedulability

public SchedulingConstraint evaluateSchedulability()

Returns SchedulingConstraint.NONE if this scheduling block may be scheduled for observation in the face of the given conditions.

If the given conditions are outside the contraints of this scheduling block, this method will return a value that indicates which constraint thwarted the scheduling. If multiple conditions are outside this block's constraints...TODO.

Returns:

SchedulingConstraint.NONE if this scheduling block may be scheduled for observation.

setCreatedBy

public void setCreatedBy(Long userId)

Description copied from interface: UserAccountable

Sets the ID of the user who created this object.

If userId is null, this object will be updated not with null but with UserAccountable.NULL_USER_ID instead.

Specified by:

setCreatedBy in interface UserAccountable

Parameters:

userId - the ID of the user who most recently updated this object.

setCreatedOn

public void setCreatedOn(Date d)

Description copied from interface: UserAccountable

Sets the date on which this object was created.

If d is null it will be ignored and this method will do nothing.

Specified by:

setCreatedOn in interface UserAccountable

Parameters:

d - the date on which this object was created.

setLastUpdatedBy

public void setLastUpdatedBy(Long userId)

Description copied from interface: UserAccountable

Sets the ID of the user who most recently updated this object.

If userId is null, this object will be updated not with null but with UserAccountable.NULL_USER_ID instead.

Specified by:

setLastUpdatedBy in interface UserAccountable

Parameters:

userId - the ID of the user who most recently updated this object.

setLastUpdatedOn

public void setLastUpdatedOn(Date d)

Description copied from interface: UserAccountable

Sets the date on which this object was most recently updated.

If d is null it will be ignored and this method will do nothing.

Specified by:

setLastUpdatedOn in interface UserAccountable

Parameters:

d - the date on which this object was most recently updated.

getCreatedBy

public Long getCreatedBy()

Description copied from interface: UserAccountable

Returns the ID of the user who created this object.

If this object does not know the identity of the user who created it, the returned ID will be UserAccountable.NULL_USER_ID.

Specified by:

getCreatedBy in interface UserAccountable

Returns:

the ID of the user who created this object.

getCreatedOn

public Date getCreatedOn()

Description copied from interface: UserAccountable

Returns the date on which this object was created.

Specified by:

getCreatedOn in interface UserAccountable

Returns:

the date on which this object was created.

getLastUpdatedBy

public Long getLastUpdatedBy()

Description copied from interface: UserAccountable

Returns the ID of the user who most recently updated this object.

If this object does not know the identity of the user who lasted updated it, the returned ID will be UserAccountable.NULL_USER_ID.

Specified by:

getLastUpdatedBy in interface UserAccountable

Returns:

the ID of the user who most recently updated this object.

getLastUpdatedOn

public Date getLastUpdatedOn()

Description copied from interface: UserAccountable

Returns the most recent date on which this object was updated.

Specified by:

getLastUpdatedOn in interface UserAccountable

Returns:

the most recent date on which this object was updated.

toObserveScript

public String toObserveScript()
                       throws ValidationException

Returns an observation script that is used to control a telescope.

Returns:

an observation script that can be used by the executor that runs a telescope.

Throws:

ValidationException

toObserveScript

public String toObserveScript(Date startingDate)
                       throws ValidationException

Returns an observation script that is used to control a telescope.

Specified by:

toObserveScript in interface Schedulable

Parameters:

startingDate - the start date and time of the script, overrides SB properties. Can be null (values in this SB will not be overridden in this case).

Returns:

an observation script that can be used by the executor that runs a telescope.

Throws:

ValidationException - if this SB fails validation checks.

setComments

public void setComments(String replacementComments)

Sets comments about this scheduling block.

Parameters:

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

See Also:

setCommentsToOperator(String), appendComments(String)

appendComments

public void appendComments(String additionalComments)

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

Parameters:

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

See Also:

appendCommentsToOperator(String), setComments(String)

getComments

public String getComments()

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

Returns:

free-form text about this scheduling block.

See Also:

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

setCommentsToOperator

public void setCommentsToOperator(String replacementComments)

Stores comments intended for use by an operator.

Parameters:

replacementComments - comments intended for use by an operator. These comments replace all previously set comments. A null value will be replaced by the empty string (""}).

See Also:

setComments(String), appendCommentsToOperator(String)

appendCommentsToOperator

public void appendCommentsToOperator(String additionalComments)

Adds additional comments to those already associated with this scheduling block. These comments are intended for use by an operator.

Parameters:

additionalComments - new, additional, comments to an operator for this scheduling block.

See Also:

appendComments(String), setCommentsToOperator(String)

getCommentsToOperator

public String getCommentsToOperator()

Returns comments intended for use by an operator. The value returned is guaranteed to be non-null.

Returns:

comments intended for use by an operator.

See Also:

getComments(), appendCommentsToOperator(String), setCommentsToOperator(String)

toString

public String toString()

Returns a text representation of this scheduling block. The default form of the text is XML. However, if anything goes wrong during the conversion to XML, an alternate, and much abbreviated, form will be returned.

Overrides:

toString in class Object

Returns:

a text representation of this scheduling block.

See Also:

toSummaryString()

toSummaryString

public String toSummaryString()

Returns a short textual description of this scheduling block.

Returns:

a short textual description of this scheduling block.

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this scheduling block.

Returns:

an XML representation of this scheduling 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 scheduling block to writer.

Parameters:

writer - the device to which XML is written.

Throws:

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

fromXml

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

Creates a new scheduling 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 scheduling 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 SchedulingBlock fromXml(Reader reader)
                               throws JAXBException,
                                      XMLStreamException

Creates a new scheduling 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 scheduling 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 SchedulingBlock clone()

Returns a scheduling block that is almost a copy of this one.

The returned element is, for the most part, a deep copy of this one. However, there are a few exceptions:

1. The ID will be set to Identifiable.UNIDENTIFIED.
2. The programBlock will be null.
3. The parentBlock will be null.
4. The createdOn and lastUpdatedOn attributes will be set to the current system time.

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

Overrides:

clone in class Object

Returns:

a near copy of this scheduling block.

cloneWithoutPrerequisites

public SchedulingBlock cloneWithoutPrerequisites()

Returns a scheduling block that is almost a copy of this one.

The returned element is, for the most part, a deep copy of this one. However, there are a few exceptions:

1. The ID will be set to Identifiable.UNIDENTIFIED.
2. The XML ID will be given a new UUID.
3. The programBlock will be null.
4. The parentBlock will be null.
5. The createdOn and lastUpdatedOn attributes will be set to the current system time.
6. The list of prerequisites will be empty.

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

Returns:

a near copy of this scheduling block, without prerequisites.

equals

public boolean equals(Object o)

Returns true if o is equal to this scheduling block.

In order to be equal to this scheduling 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. programBlock
3. parentBlock
4. createdOn
5. createdBy
6. lastUpdatedOn
7. lastUpdatedBy
8. alteration status (Under the theory that two things may be equal regardless of how they got that way.)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

getPrequisiteComparator

public static Comparator<SchedulingBlock> getPrequisiteComparator()

Returns a comparator that places all prerequisites before the blocks that depend upon them. Blocks that have no prereqs, and are prereqs of nothing, could be placed anywhere in the sorting process.

Returns:

a comparator that places all prerequisites before the blocks that depend upon them.