edu.nrao.sss.model.project
Class Project

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

All Implemented Interfaces:

UserAccountable, Identifiable, Cloneable

public class Project
extends Object
implements Identifiable, UserAccountable, Cloneable

A scientifically independent subset of the observations set forth in a Proposal.

An approved Proposal may lead to one or more Projects. These projects are created by the Observing Program Committee. Different projects from the same proposal may have different scientific ratings. A proposal is typically split into projects when time is requested on different telescopes. There is usually a one-to-one corespondence between project and telescope within a given proposal.

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

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

UNIDENTIFIED

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

NULL_USER_ID

Constructor Summary

Project()
Creates a new instance.

Method Summary

void	addProgramBlock(int idx, ProgramBlock progBlock) Adds the given program block to this project at index idx.
void	addProgramBlock(ProgramBlock progBlock) Adds the given program block to this project.
void	appendComments(String additionalComments) Adds additional comments to those already associated with this project.
void	clearId() Resets this project's id to UNIDENTIFIED and calls all of it's ProgramBlock's clearId() methods.
Project	clone() Returns a project that is a copy of this one.
ProgramBlock	createProgramBlock() Creates and returns a new program block that is suitable for use with this project.
static Project	createProject(TelescopeType telescope) Creates an instance of a project that is appropriate for the given telescope.
boolean	equals(Object o) Returns true if o is equal to this project.
static Project	fromXml(Reader reader) Creates a new project based on the XML data read from reader.
static Project	fromXml(String xmlFile) Creates a new project from the XML data in the given file.
double	getAllocatedTime() Returns the amount of time allocated to this project by the Time Allocation Committee.
String	getComments() Returns comments about this project.
Long	getCreatedBy() Returns the ID of the user who created this object.
Date	getCreatedOn() Returns the date on which this object was created.
Long	getEditor() Returns the ID of the user who is authorized to edit this project.
EventSetStatus	getExecutionStatus() Returns this project's execution status.
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.
List<ProgramBlock>	getProgramBlocks() Returns the program blocks that belong to this project.
List<ProgramBlock>	getProgramBlocksSortedByPrereqs() Returns a list of this project's program blocks sorted such that any prerequisites of the block at index i are at in indices greater than i.
String	getProjectCode() Returns this project's NRAO code.
ProjectType	getProjectType() Returns the type of this project.
Proposal	getProposal() Returns the proposal that spawned this project.
String	getProposalCode() Returns the NRAO code of the proposal that spawned this project.
Collection<ScheduleEntry>	getReadyToScheduleEntries(Collection<ScheduleEntry> destination) Returns the schedule entries of this project that are ready for scheduling.
Collection<ScheduleEntry>	getScheduleEntries(EventStatus execStatus, Collection<ScheduleEntry> destination) Returns the schedule entries of this project that have an execution status of execStatus.
ScientificPriority	getScientificPriority() Returns the scientific priority of this project.
TelescopeType	getTelescope() Returns the telescope used by this project.
double	getTimeUsedSoFar() Returns the telescope time used so far for this project.
String	getTitle() Returns the title of this project.
int	hashCode()
boolean	hasProposal() Returns true if this project has a non-null proposal.
boolean	isTest() Returns true if this project is a test, as opposed to official, project.
void	removeAllProgramBlocks() Removes all program blocks from this project.
void	removeProgramBlock(ProgramBlock progBlock) Removes the given program block from this project.
void	reset() Resets this project to its initial state.
void	setAllocatedTime(double allocatedTime) Sets the amount of time allocated to this project by the Time Allocation Committee.
void	setComments(String replacementComments) Sets comments about this project.
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	setEditor(Long userId) Sets the ID of the user who is authorized to edit this project.
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	setProjectCode(String newCode) Sets this project's NRAO code.
void	setProjectType(ProjectType type) Sets the type of this project.
void	setProposal(Proposal proposal) Sets the proposal that spawned this project.
void	setProposalCode(String newCode)
void	setProposalProvider(ProposalProvider newProvider) Tells this project where to look for proposals if it does not already have one.
void	setScientificPriority(ScientificPriority newPriority) Sets the scientific priority for this project.
void	setTelescope(TelescopeType telescope) Sets the telescope on which this project will be performed.
void	setTest(boolean projectIsTest) Declares this project as either a test or official project.
void	setTitle(String newTitle) Sets the title of this project.
String	toString() Returns a text representation of this project.
String	toSummaryString() Returns a short textual description of this project.
String	toXml() Returns an XML representation of this project.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this project to writer.

Methods inherited from class java.lang.Object

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

Constructor Detail

Project

public Project()

Creates a new instance.

Method Detail

createProject

public static Project createProject(TelescopeType telescope)

Creates an instance of a project that is appropriate for the given telescope. The new project's telescope will have been communicated to the project via its setTelescope method before it is returned.

Parameters:

telescope - the telescope for which a new project is desired. If telescope is null, it will be treated as if it had been TelescopeType.getDefault().

Returns:

a new project for telescope.

reset

public void reset()

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

getId

public Long getId()

Specified by:

getId in interface Identifiable

clearId

public void clearId()

Resets this project's id to UNIDENTIFIED and calls all of it's ProgramBlock's clearId() methods.

setProjectCode

public void setProjectCode(String newCode)

Sets this project's NRAO code.

Note that this is not necessarily the identifier that the persistence layer will use to uniquely identify projects in the data store. (See getId() for that concept.) Instead, this is NRAO's identifier for this project.

Parameters:

newCode - this project's NRAO identifier.

getProjectCode

public String getProjectCode()

Returns this project's NRAO code.

Returns:

this project's NRAO code.

See Also:

setProjectCode(String)

setTitle

public void setTitle(String newTitle)

Sets the title of this project. Note that this project's title may be different than the title of the Proposal that led to this project.

Parameters:

newTitle - the title of this project.

getTitle

public String getTitle()

Returns the title of this project.

Returns:

the title of this project.

setProposal

public void setProposal(Proposal proposal)

Sets the proposal that spawned this project.

If proposal is the same as this.getProposal(), this method will do nothing. Otherwise a reference to proposal is saved in this project.

Consequences of Changing a Project's Proposal:

• All existing sources in the project are removed and replaced with the sources from the proposal.
• All program blocks are removed.

Parameters:

proposal - the proposal that spawned this project.

getProposal

public Proposal getProposal()

Returns the proposal that spawned this project. Note that the returned proposal may have spawned additional projects.

Note to Developers: This method may be expensive. If all you need is the proposal's ID code, the getProposalCode() method is more efficient. Of course, if you need extensive information from the proposal, you should use this method.

Note that it is possible for this project to not yet have a proposal. In this situation, the return value will be null. Also, if there are any problems encountered while using the proposal repository, null will be returned.

Returns:

the proposal that spawned this project.

See Also:

getProposalCode(), hasProposal()

hasProposal

public boolean hasProposal()

Returns true if this project has a non-null proposal.

The only times this method should return false are:

1. This project has just been created and its proposal has not yet been set.
2. A client set this project's proposal to null

Returns:

true if this project has a non-null proposal.

setProposalProvider

public void setProposalProvider(ProposalProvider newProvider)

Tells this project where to look for proposals if it does not already have one.

Parameters:

newProvider - a provider of proposals.

getProposalCode

public String getProposalCode()

Returns the NRAO code of the proposal that spawned this project.

Calling this method instead of getProposal().getPropId() may be more efficient.

Returns:

the NRAO code of the proposal that spawned this project.

See Also:

getProposal()

setProposalCode

public void setProposalCode(String newCode)

createProgramBlock

public ProgramBlock createProgramBlock()

Creates and returns a new program block that is suitable for use with this project. The returned program block has not been added to this project.

Returns:

a new program block that can later be added to this project.

addProgramBlock

public void addProgramBlock(ProgramBlock progBlock)

Adds the given program block to this project.

If progBlock is already part of this project, or if it is null, no action is taken. Otherwise it is added to this project, removed from the project to which it had been attached (if any), and updated so that it knows it belongs to this project.

Parameters:

progBlock - the program block to be added to this project.

addProgramBlock

public void addProgramBlock(int idx,
                            ProgramBlock progBlock)

Adds the given program block to this project at index idx.

If progBlock is already part of this project, or if it is null, no action is taken. Otherwise it is added to this project, removed from the project to which it had been attached (if any), and updated so that it knows it belongs to this project.

Parameters:

idx - the index in our list of program blocks at which to add progBlock.

progBlock - the program block to be added to this project.

removeProgramBlock

public void removeProgramBlock(ProgramBlock progBlock)

Removes the given program block from this project.

If progBlock is null, or if it does not belong to this project, nothing happens. If it is a prerequisite of one or more of the program blocks held by this project, an exception is thrown and it is not removed from this project. Otherwise, progBlock is removed from this project and has its project attribute set to null.

Parameters:

progBlock - the program block to be removed.

removeAllProgramBlocks

public void removeAllProgramBlocks()

Removes all program blocks from this project. Each program block is notified that it no longer has a containing project.

getProgramBlocks

public List<ProgramBlock> getProgramBlocks()

Returns the program blocks that belong to this project.

The returned List is a copy of the one held internally by this project, so changes made to it will not be reflected herein.

Returns:

the program blocks that belong to this project.

getProgramBlocksSortedByPrereqs

public List<ProgramBlock> getProgramBlocksSortedByPrereqs()

Returns a list of this project's program blocks sorted such that any prerequisites of the block at index i are at in indices greater than i.

Note that the sort determines only how prerequisites and things dependent on them are place relative to one another. For example, imagine four blocks A, B, C, and D. C has A and B as prerequisites and no other block has prerequisites. The returned list will place C in a lower index than A and B. However, we know nothing about how A and B will be placed relative to each other, nor do we know ahead of time where D will be placed.

Returns:

program blocks sorted by prerequisite relationships.

getScheduleEntries

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

Returns the schedule entries of this project 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 project that are ready for scheduling. If this is a test project, or if this project 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)

getExecutionStatus

public EventSetStatus getExecutionStatus()

Returns this project's execution status.

Returns:

this project's execution status.

setTelescope

public void setTelescope(TelescopeType telescope)

Sets the telescope on which this project will be performed.

Parameters:

telescope - the telescope used by this project.

getTelescope

public TelescopeType getTelescope()

Returns the telescope used by this project.

Returns:

telescope used by this project.

setScientificPriority

public void setScientificPriority(ScientificPriority newPriority)

Sets the scientific priority for this project.

Parameters:

newPriority - the scientific priority for this project.

getScientificPriority

public ScientificPriority getScientificPriority()

Returns the scientific priority of this project.

Returns:

the scientific priority of this project.

setAllocatedTime

public void setAllocatedTime(double allocatedTime)

Sets the amount of time allocated to this project by the Time Allocation Committee.

Parameters:

allocatedTime - the amount of time allocated to this project in whole and fractional hours.

getAllocatedTime

public double getAllocatedTime()

Returns the amount of time allocated to this project by the Time Allocation Committee.

Returns:

the amount of time allocated to this project in whole and fractional hours.

setTest

public void setTest(boolean projectIsTest)

Declares this project as either a test or official project. The default state of a newly created project is as a test project.

Parameters:

projectIsTest - true if this project is a test project.

isTest

public boolean isTest()

Returns true if this project is a test, as opposed to official, project.

Returns:

true if this project is unofficial.

setProjectType

public void setProjectType(ProjectType type)

Sets the type of this project.

Parameters:

type - the type of this project.

getProjectType

public ProjectType getProjectType()

Returns the type of this project.

Returns:

the type of this project.

getTimeUsedSoFar

public double getTimeUsedSoFar()

Returns the telescope time used so far for this project.

Returns:

the telescope time used so far for this project.

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.

setEditor

public void setEditor(Long userId)

Sets the ID of the user who is authorized to edit this project.

Parameters:

userId - the ID of the user who is authorized to edit this project.

getEditor

public Long getEditor()

Returns the ID of the user who is authorized to edit this project.

Returns:

the ID of the user who is authorized to edit this project.

setComments

public void setComments(String replacementComments)

Sets comments about this project.

Parameters:

replacementComments - free-form comments about this project. 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 project.

Parameters:

additionalComments - new, additional, comments about this project.

See Also:

setComments(String)

getComments

public String getComments()

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

Returns:

free-form comments about this project.

See Also:

appendComments(String), setComments(String)

toString

public String toString()

Returns a text representation of this project. 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 project.

toSummaryString

public String toSummaryString()

Returns a short textual description of this project.

Returns:

a short textual description of this project.

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this project.

Returns:

an XML representation of this project.

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 project 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 Project fromXml(String xmlFile)
                       throws JAXBException,
                              XMLStreamException,
                              FileNotFoundException

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

Creates a new project 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 project 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 Project clone()

Returns a project that is a copy of this one.

For the most part this project is deeply cloned. For example, the clone and this project will have their own lists of program blocks, and the program blocks in the clone will be clones of those in this project. There are, however, a few exceptions to the deep copy philosophy:

1. The ID will be set to Identifiable.UNIDENTIFIED.
2. The proposal will refer to the same proposal that this project points to.
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 project.

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

1. id
2. proposal (but not proposal code, which is not ignored)
3. createdOn
4. createdBy
5. lastUpdatedOn
6. lastUpdatedBy

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object