edu.nrao.sss.model.project.scan
Class ScanLoopElement

java.lang.Object
  edu.nrao.sss.model.project.scan.ScanLoopElement

All Implemented Interfaces:

UserAccountable, Identifiable, Cloneable

Direct Known Subclasses:

Scan, ScanLoop

public abstract class ScanLoopElement
extends Object
implements Cloneable, Identifiable, UserAccountable

The abstract parent of both Scan and ScanLoop.

Note: This class was originally an interface but became an abstract class due to some JAXB restrictions on marshalling and unmarshalling to/from XML for interface classes. I was successful with this class as an interface while going to XML, but not coming from XML.

Version Info:

$Revision: 1911 $

$Date: 2009-01-21 10:27:48 -0700 (Wed, 21 Jan 2009) $

$Author: dharland $

Since:

2006-07-31

Author:

David M. Harland

Field Summary

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

UNIDENTIFIED

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

NULL_USER_ID

Method Summary

void	appendComments(String additionalComments) Adds additional comments to those already associated with this element.
void	clearId() Resets this scan loop element's id to UNIDENTIFIED.
ScanLoopElement	clone() Returns a scan loop element that is a copy of this one.
boolean	equals(Object o) Returns true if o is equal to this scan loop element.
String	getComments() Returns comments about this element.
Long	getCreatedBy() Returns the ID of the user who created this object.
Date	getCreatedOn() Returns the date on which this object was created.
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	getName() Returns the name of this element.
ProgramBlock	getProgramBlock() Returns the program block to which this scan belongs.
Project	getProject() Returns the project to which this scan belongs.
SchedulingBlock	getSchedulingBlock() Returns the scheduling block to which this scan loop element belongs, if any.
int	hashCode() Returns a hash code value for this scan loop element.
boolean	hasSchedulingBlock() Returns true if this scan loop element is connected, either directly or indirectly, to a non-null scheduling block.
void	reset() Resets this element to its initial state.
void	setComments(String replacementComments) Sets comments about this element.
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	setId(Long id) Do not use.
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	setName(String newName) Sets the name of this element.
void	setSchedulingBlock(SchedulingBlock newSchedBlock) Sets the scheduling block to which this scan loop element belongs.
String	toString() Returns a text representation of this scan loop element.
abstract String	toSummaryString() Returns a short textual description of this scan loop element.
String	toXml() Returns an XML representation of this scan loop element.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this scan loop element to writer.

Methods inherited from class java.lang.Object

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

Method Detail

reset

public void reset()

Resets this element to its initial state. A reset scan loop element has the same state as a new element.

setId

public void setId(Long id)

Do not use. This method is here for the persistence mechanism. Other clients should not set object identifiers.

getId

public Long getId()

Specified by:

getId in interface Identifiable

clearId

public void clearId()

Resets this scan loop element's id to UNIDENTIFIED.

setName

public void setName(String newName)

Sets the name of this element.

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.

Parameters:

newName - the new name of this element.

getName

public String getName()

Returns the name of this element.

Returns:

the name of this element.

setSchedulingBlock

public void setSchedulingBlock(SchedulingBlock newSchedBlock)

Sets the scheduling block to which this scan loop element belongs.

This method does not communicate back to newSchedBlock about its new scan loop element. This is because the scheduling block does not hold these elements directly, except for its single scanSequence, which is of type ScanLoop. This means that the model is not enforcing integrity in the container / contained relationship that exists between SchedulingBlock and ScanLoopElement.

Passing this method a schedulingBlock of null has the effect of disconnecting this element from any scheduling block.

Parameters:

newSchedBlock - the scheduling block to which this element belongs.

getSchedulingBlock

public SchedulingBlock getSchedulingBlock()

Returns the scheduling block to which this scan loop element belongs, if any. If this element belongs to no scheduling block, the value returned is null.

Returns:

the scheduling block that contains this scan loop element.

hasSchedulingBlock

public boolean hasSchedulingBlock()

Returns true if this scan loop element is connected, either directly or indirectly, to a non-null scheduling block.

Scans should normally be contained directly within either a scheduling block or an execution block. The execution block, in turn, is normally contained within a scheduling block. Therefore, a scan loop element normally has a link to a scheduling block. However, there are some situations where this method will return false:

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

Returns:

true if this scan 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.

getProgramBlock

public ProgramBlock getProgramBlock()

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

Returns:

the program block that contains this scan or null.

getProject

public Project getProject()

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

Returns:

the project that contains this scan or null.

setComments

public void setComments(String replacementComments)

Sets comments about this element.

Parameters:

replacementComments - free-form text about this element. 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 element.

Parameters:

additionalComments - new, additional, comments about this element.

See Also:

setComments(String)

getComments

public String getComments()

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

Returns:

free-form text about this element.

See Also:

appendComments(String), setComments(String)

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.

toString

public String toString()

Returns a text representation of this scan loop element. 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 scan.

See Also:

toSummaryString()

toSummaryString

public abstract String toSummaryString()

Returns a short textual description of this scan loop element.

Returns:

a short textual description of this scan loop element.

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this scan loop element.

Returns:

an XML representation of this scan loop element.

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 scan loop element to writer.

Parameters:

writer - the device to which XML is written.

Throws:

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

clone

public ScanLoopElement clone()

Returns a scan loop element that is 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 schedulingBlock will be null.
3. 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

equals

public boolean equals(Object o)

Returns true if o is equal to this scan loop element.

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

1. id
2. schedulingBlock
3. createdOn
4. createdBy
5. lastUpdatedOn
6. lastUpdatedBy

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this scan loop element.

Overrides:

hashCode in class Object