001 package edu.nrao.sss.model.project;
002
003 import java.io.Writer;
004 import java.util.Date;
005
006 import javax.xml.bind.JAXBException;
007
008 import edu.nrao.sss.util.EventStatus;
009 import edu.nrao.sss.util.IllegalTransitionException;
010
011 /**
012 * A single schedulable entry of a {@link SchedulingBlock scheduling block}.
013 * Each iteration is considered to be a separately schedulable event and is
014 * represented by an instance of this class.
015 * <p>
016 * <b>Version Info:</b>
017 * <table style="margin-left:2em">
018 * <tr><td>$Revision$</td></tr>
019 * <tr><td>$Date$</td></tr>
020 * <tr><td>$Author$ (last person to modify)</td></tr>
021 * </table></p>
022 *
023 * @author David M. Harland
024 * @since 2007-08-17
025 */
026 public interface ScheduleEntry
027 {
028 /**
029 * The scheduling block from which this entry was created.
030 * @return this entry's containing scheduling block.
031 */
032 public SchedulingBlock getSchedulingBlock();
033
034 //============================================================================
035 // STATUS
036 //============================================================================
037
038 /**
039 * Returns information about where this entry is in its life cycle.
040 * @return the execution status of this entry.
041 */
042 public EventStatus getExecutionStatus();
043
044 /**
045 * Returns the point in time when this entry's status changed to its current value.
046 * @return the point in time when this entry's status changed to its current value.
047 */
048 public Date getExecutionStatusChangeDate();
049
050 /**
051 * Submits this entry for scheduling.
052 * <p>
053 * This method is called on an entry that has just been made ready for
054 * scheduling. Typically such an entry has a status of
055 * not-ready-for-scheduling. This method will change the entry's status
056 * to not-yet-scheduled.</p>
057 * <p>
058 * (The reason for the new <i>updateStatus</i> prefix is two fold. First,
059 * it is meant to indicate that we're not truly performing the action that
060 * the final verb indicates; only a controller of this model can really
061 * do that. The model does, though, ensure the transition is legal and
062 * may update more things than just a status property. The second
063 * reason is that using a common prefix puts all status-altering methods
064 * next to each other in an alphabetical listing. We could have collapsed
065 * these into one method with a parameter, but the <tt>EventStatus</tt>
066 * and <tt>EventSetStatus</tt> enumeration elements do not map one-to-one
067 * with these methods.)</p>
068 *
069 * @throws IllegalTransitionException
070 * if this entry is not in a state where it may be submitted for scheduling.
071 * For example, it would be illegal to schedule an entry
072 * that has already been canceled.
073 */
074 public void updateStatusSubmit() throws IllegalTransitionException;
075
076 /**
077 * Schedules this entry to be executed at the given time.
078 * <p>
079 * This method may be called on an entry that has already been scheduled
080 * if the client wishes to change the time at which it should be executed.</p>
081 * <p>
082 * See {@link #updateStatusSubmit()} for an explanation of the new
083 * <i>updateStatus</i> prefix.</p>
084 *
085 * @param futureTime
086 * the time at which the entry should be executed.
087 *
088 * @throws IllegalTransitionException
089 * if this entry is not in a state where it may be scheduled.
090 * For example, it would be illegal to schedule an entry
091 * that has already been executed.
092 *
093 * @see #reschedule()
094 */
095 public void updateStatusSchedule() throws IllegalTransitionException;
096
097 /**
098 * Executes this entry.
099 * <p>
100 * This method is called on an entry that has been scheduled but has
101 * not yet been executed.</p>
102 * <p>
103 * See {@link #updateStatusSubmit()} for an explanation of the new
104 * <i>updateStatus</i> prefix.</p>
105 *
106 * @throws IllegalTransitionException
107 * if this entry is not in the scheduled-but-not-started state.
108 */
109 public void updateStatusExecute() throws IllegalTransitionException;
110
111 /**
112 * Brings this entry to a successful completion.
113 * <p>
114 * This method is called on an entry that has was most recently in the
115 * in-progress state.</p>
116 * <p>
117 * See {@link #updateStatusSubmit()} for an explanation of the new
118 * <i>updateStatus</i> prefix.</p>
119 *
120 * @throws IllegalTransitionException
121 * if this entry is not currently in-progress.
122 */
123 public void updateStatusComplete() throws IllegalTransitionException;
124
125 /**
126 * Indicates that an execution in progress failed to complete.
127 * <p>
128 * This method is called on an entry that has was most recently in the
129 * in-progress state. If a human wishes to stop an in-progress entry,
130 * the {@link #updateStatusCancel() cancel} method should be used.
131 * This method should be called by the execution process, or its proxy,
132 * to indicate that execution failed.</p>
133 *
134 * @throws IllegalTransitionException
135 * if this entry is not in-progress.
136 */
137 public void updateStatusFail() throws IllegalTransitionException;
138
139 /**
140 * Cancels this entry so that it will never be executed or rescheduled.
141 * <p>
142 * See {@link #updateStatusSubmit()} for an explanation of the new
143 * <i>updateStatus</i> prefix.</p>
144 *
145 * @throws IllegalTransitionException
146 * if this entry is not in a state where it may be canceled.
147 * For example, it would be illegal to cancel an entry
148 * that has already been completed successfully.
149 */
150 public void updateStatusCancel() throws IllegalTransitionException;
151
152 /**
153 * Puts this entry back in the not-yet-scheduled state, thereby making
154 * it available for rescheduling.
155 * <p>
156 * See {@link #updateStatusSubmit()} for an explanation of the new
157 * <i>updateStatus</i> prefix.</p>
158 *
159 * @throws IllegalTransitionException
160 * if this entry is not in a state where it may be rescheduled.
161 * Only entries that have been scheduled but not yet started
162 * may be rescheduled.
163 */
164 public void updateStatusReschedule() throws IllegalTransitionException;
165
166 /**
167 * Removes this entry from the schedule, with the intention of
168 * doing so temporarily.
169 * Once on hold, only the {@link #release()} and {@link #cancel()}
170 * methods can take it out of the on-hold state.
171 * <p>
172 * See {@link #updateStatusSubmit()} for an explanation of the new
173 * <i>updateStatus</i> prefix.</p>
174 *
175 * @throws IllegalTransitionException
176 * if this entry is not in a state where it may be held.
177 * An entry may be placed on hold only if it has not yet been
178 * scheduled, or if it has been scheduled but not yet started.
179 */
180 public void updateStatusHold() throws IllegalTransitionException;
181
182 /**
183 * Releases this entry from the on-hold state so that it may be rescheduled.
184 * Once released, this entry's status will be not-yet-scheduled
185 * and it will be ready for reconsideration.
186 * <p>
187 * See {@link #updateStatusSubmit()} for an explanation of the new
188 * <i>updateStatus</i> prefix.</p>
189 *
190 * @throws IllegalTransitionException
191 * if this entry is not in a state where it may be released.
192 * Only entries that are on hold may be released.
193 */
194 public void updateStatusRelease() throws IllegalTransitionException;
195
196 //============================================================================
197 // XML
198 //============================================================================
199
200 /**
201 * Returns an XML representation of this entry.
202 * @return an XML representation of this entry.
203 * @throws JAXBException if anything goes wrong during the conversion to XML.
204 * @see #writeAsXmlTo(Writer)
205 */
206 public String toXml() throws JAXBException;
207
208 /**
209 * Writes an XML representation of this entry to {@code writer}.
210 * @param writer the device to which XML is written.
211 * @throws JAXBException if anything goes wrong during the conversion to XML.
212 */
213 public void writeAsXmlTo(Writer writer) throws JAXBException;
214 }