1 /*
2 * Copyright (c) 2005, London e-Science Centre, Imperial College London, UK
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
6 *
7 * - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
8 * - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
9 * - Neither the name of the London e-Science Centre nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
10 *
11 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
12 */
13 package org.icenigrid.gridsam.core.plugin;
14
15 import java.io.IOException;
16 import java.text.ParseException;
17
18 import org.apache.commons.logging.Log;
19 import org.apache.commons.vfs.FileObject;
20 import org.icenigrid.gridsam.core.JobManagerException;
21 import org.icenigrid.gridsam.core.MutableJobInstance;
22
23 /**
24 * Interface defining a context object being passed through the launching
25 * pipeline providing useful information about the job and the environment to be
26 * launched.
27 *
28 * @author wwhl
29 */
30 public interface JobContext extends JobManagerContext {
31
32 /**
33 * A runnable-like interface that allows exception to be caught
34 */
35 public interface ThrowableRunnable {
36
37 /**
38 * When an object implementing interface <code>ThrowableRunnable</code>
39 * is used to create a thread, starting the thread causes the object's
40 * <code>run</code> method to be called in that separately executing
41 * thread. <p/> The general contract of the method <code>run</code> is
42 * that it may take any action whatsoever.
43 *
44 * @throws Exception
45 * exception to be thrown back to the caller when calling
46 * runInterruptable
47 * @see java.lang.Thread#run()
48 */
49 public void run() throws Exception;
50
51 }
52
53 /**
54 * test whether this context has been interrupted
55 *
56 * @return boolean true if interrupted, false otherwise
57 */
58 public boolean isInterrupted();
59
60 /**
61 * test whether this context is recovering from a crash
62 *
63 * @return boolean true to indicate this context is recovering from a crash,
64 * false to indicate normal execution
65 */
66 public boolean isRecovering();
67
68 /**
69 * the job instance associated with this job context
70 *
71 * @return MutableJobInstance the job instance associated with this context
72 */
73 public MutableJobInstance getJobInstance();
74
75 /**
76 * run a block of code (i.e. in the Runnable) that can be interrupted (i.e.
77 * receive java.lang.InterruptedException) when the Job context is
78 * interrutped (i.e. isInterrupted is set to true)
79 *
80 * @param pRunnable
81 * the interruptable code
82 * @return true if the code block has been interrupted
83 */
84 public boolean runInterruptable(Runnable pRunnable);
85
86 /**
87 * run a block of code (i.e. in the Runnable) that can be interrupted (i.e.
88 * receive java.lang.InterruptedException) when the Job context is
89 * interrutped (i.e. isInterrupted is set to true)
90 *
91 * @param pRunnable
92 * the interruptable code
93 * @return true if the code block has been interrupted
94 * @throws Exception
95 * the exception thrown by the ThrowableRunnable
96 */
97 public boolean runInterruptable(ThrowableRunnable pRunnable)
98 throws Exception;
99
100 /**
101 * get the file system associated with the job context
102 *
103 * @return FileObject the root file system for the job context.
104 *
105 * @throws IOException
106 * if the file system cannot be retrieved
107 */
108 public FileObject getFileSystem() throws IOException;
109
110 /**
111 * schedule the given DRMConnector for immediate execution in this job
112 * context for the current job
113 *
114 * @param pConnector
115 * the DRMConnector
116 * @throws org.icenigrid.gridsam.core.JobManagerException
117 * if the DRMConnector cannot be scheduled
118 */
119 public void schedule(DRMConnector pConnector) throws JobManagerException;
120
121 /**
122 * schedule the given named DRMConnector for immediate execution in this job
123 * context for the current job
124 *
125 * @param pConnectorName
126 * the name of the DRMConnector resolvable by the context *
127 * @throws JobManagerException
128 * if the DRMConnector cannot be scheduled
129 */
130 public void schedule(String pConnectorName) throws JobManagerException;
131
132 /**
133 * schedule the given DRMConnector for repeated execution in this job
134 * context for the current job
135 *
136 * @param pConnector
137 * the DRMConnector
138 * @param pRepeatInterval
139 * the period between repeated execution
140 * @throws JobManagerException
141 * if the DRMConnector cannot be scheduled
142 */
143 public void schedule(DRMConnector pConnector, long pRepeatInterval)
144 throws JobManagerException;
145
146 /**
147 * schedule the given named DRMConnector for immediate execution in this job
148 * context for the current job
149 *
150 * @param pConnectorName
151 * the name of the DRMConnector resolvable by the context
152 * @param pRepeatInterval
153 * the period between repeated execution
154 * @throws JobManagerException
155 * if the DRMConnector cannot be scheduled
156 */
157 public void schedule(String pConnectorName, long pRepeatInterval)
158 throws JobManagerException;
159
160 /**
161 * schedule the given DRMConnector for repeated execution in this job
162 * context for the current job
163 *
164 * @param pConnector
165 * the DRMConnector
166 * @param pCronExpression
167 * the CRON job expression to specify the schedule
168 * @throws java.text.ParseException
169 * if the cron expression is invalid
170 * @throws JobManagerException
171 * if the DRMConnector cannot be scheduled
172 */
173 public void schedule(DRMConnector pConnector, String pCronExpression)
174 throws ParseException, JobManagerException;
175
176 /**
177 * schedule the given named DRMConnector for immediate execution in this job
178 * context for the current job
179 *
180 * @param pConnectorName
181 * the name of the DRMConnector resolvable by the context
182 * @param pCronExpression
183 * the CRON job expression to specify the schedule
184 * @throws ParseException
185 * if the cron expression is invalid
186 * @throws JobManagerException
187 * if the DRMConnector cannot be scheduled
188 */
189 public void schedule(String pConnectorName, String pCronExpression)
190 throws ParseException, JobManagerException;
191
192 /**
193 * get a Log associated with this job. DRMConnector should use this log to
194 * convey meaningful logging information associated with this job.
195 *
196 * @return Log the logger instance
197 */
198 public Log getLog();
199
200 }