1
/*___INFO__MARK_BEGIN__*/
2
/*************************************************************************
4
* The Contents of this file are made available subject to the terms of
5
* the Sun Industry Standards Source License Version 1.2
7
* Sun Microsystems Inc., March, 2001
10
* Sun Industry Standards Source License Version 1.2
11
* =================================================
12
* The contents of this file are subject to the Sun Industry Standards
13
* Source License Version 1.2 (the "License"); You may not use this file
14
* except in compliance with the License. You may obtain a copy of the
15
* License at http://gridengine.sunsource.net/Gridengine_SISSL_license.html
17
* Software provided under this License is provided on an "AS IS" basis,
18
* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
19
* WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
20
* MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
21
* See the License for the specific provisions governing your rights and
22
* obligations concerning the Software.
24
* The Initial Developer of the Original Code is: Sun Microsystems, Inc.
26
* Copyright: 2001 by Sun Microsystems, Inc.
28
* All Rights Reserved.
30
************************************************************************/
31
/*___INFO__MARK_END__*/
32
package org.ggf.drmaa;
34
import java.util.List;
39
* This interface represents a template to be used for the creation of a job.
40
* The properties set on a JobTemplate instance are used to create a new job and
41
* set up the new job's environment.
43
* <p>There is a 1:n relationship between JobTemplate instances and jobs. A
44
* single JobTemplate instance can be used to submit any number of jobs. Once a
45
* job has been submitted, e.g. via Session.runJob(), the JobTemplate instance
46
* no longer has any affect on that job. Changes made to the JobTemplate
47
* instance will have no affect on already running jobs. Deleting the
48
* JobTemplate instance (via Session.deleteJobTemplate()) also has no effect on
51
* <p>Once a JobTemplate instance has been created
52
* (via Session.createJobTemplate()), it is the responsibility of the developer
53
* to delete it when no longer needed (via Session.deleteJobTemplate ()).
54
* Failure to do so may result in a memory leak.</p>
58
* <pre>public static void main(String[] args) {
59
* SessionFactory factory = SessionFactory.getFactory();
60
* Session session = factory.getSession();
63
* session.init("");
64
* JobTemplate jt = session.createJobTemplate();
65
* jt.setRemoteCommand("sleeper.sh");
66
* jt.setWorkingDirectory(":" + HOME_DIRECTORY + "/jobs");
67
* jt.setArgs(Collections.singletonList("5"));
69
* String id = session.runJob(jt);
71
* session.deleteJobTemplate(jt);
74
* catch (DrmaaException e) {
75
* System.out.println("Error: " + e.getMessage ());
79
* @author dan.templeton@sun.com
84
public abstract interface JobTemplate {
86
* Means the job has been queued but it is not
87
* eligible to run. Used with the jobSubmissionState property.
89
public static final int HOLD_STATE = 0;
91
* Means the job has been queued and is eligible
92
* to run. Used with the jobSubmissionState property.
94
public static final int ACTIVE_STATE = 1;
96
* Placeholder which represents the home directory in the workingDirectory,
97
* inputPath, outputPath, and errorPath properties
99
public static final String HOME_DIRECTORY = "$drmaa_hd_ph$";
101
* Placeholder which represents the working directory in the
102
* workingDirectory, inputPath, outputPath, and errorPath properties
104
public static final String WORKING_DIRECTORY = "$drmaa_wd_ph$";
106
* Placeholder which represents the job id for a job in a parametric job set
107
* in the inputPath, outputPath, and errorPath properties
109
public static final String PARAMETRIC_INDEX = "$drmaa_incr_ph$";
112
* Set the command string to execute as the job. The command
113
* is relative to the execution host and is evaluated on the
115
* @param remoteCommand the command to execute as the job
116
* @throws DrmaaException May be one of the following:
118
* <LI>InvalidAttributeFormatException -- the format of the argument is
120
* <LI>InvalidAttributeValueException -- the value of the argument is
122
* <LI>ConflictingAttributeValuesException -- the value of the argument
123
* conflicts with the value of another job template property</LI>
124
* <LI>NoActiveSessionException -- the session has not yet been initialized
125
* or has already been exited</LI>
126
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
127
* contact the DRM</LI>
128
* <LI>AuthorizationException -- the executing user does not have
129
* sufficient permissions to execute the desired action</LI>
130
* <LI>IllegalArgumentException -- an argument is invalid</LI>
131
* <LI>InternalException -- an error has occured in the DRMAA
132
* implementation</LI>
135
public void setRemoteCommand(String remoteCommand) throws DrmaaException;
138
* Get the command string to execute as the job.
139
* @return the command to execute as the job or null if it has not been set
140
* @throws DrmaaException May be one of the following:
142
* <LI>NoActiveSessionException -- the session has not yet been initialized
143
* or has already been exited</LI>
144
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
145
* contact the DRM</LI>
146
* <LI>AuthorizationException -- the executing user does not have
147
* sufficient permissions to execute the desired action</LI>
148
* <LI>InternalException -- an error has occured in the DRMAA
149
* implementation</LI>
151
* @see #setRemoteCommand(String)
153
public String getRemoteCommand() throws DrmaaException;
156
* Sets the arguments to the job.
157
* @param args the parameters passed as arguments to the job
158
* @throws DrmaaException May be one of the following:
160
* <LI>InvalidAttributeFormatException -- the format of the argument is
162
* <LI>InvalidAttributeValueException -- the value of the argument is
164
* <LI>ConflictingAttributeValuesException -- the value of the argument
165
* conflicts with the value of another job template property</LI>
166
* <LI>NoActiveSessionException -- the session has not yet been initialized
167
* or has already been exited</LI>
168
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
169
* contact the DRM</LI>
170
* <LI>AuthorizationException -- the executing user does not have
171
* sufficient permissions to execute the desired action</LI>
172
* <LI>IllegalArgumentException -- an argument is invalid</LI>
173
* <LI>InternalException -- an error has occured in the DRMAA
174
* implementation</LI>
178
public void setArgs(List args) throws DrmaaException;
181
* Get the arguments to the job.
182
* @return the parameters passed as arguments to the job or null if they have
184
* @throws DrmaaException May be one of the following:
186
* <LI>NoActiveSessionException -- the session has not yet been initialized
187
* or has already been exited</LI>
188
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
189
* contact the DRM</LI>
190
* <LI>AuthorizationException -- the executing user does not have
191
* sufficient permissions to execute the desired action</LI>
192
* <LI>InternalException -- an error has occured in the DRMAA
193
* implementation</LI>
195
* @see #setArgs(List)
197
public List getArgs() throws DrmaaException;
200
* Set the job state at submission. The states are
201
* HOLD_STATE and ACTIVE_STATE:
204
* <LI>ACTIVE_STATE means job is eligible to run</LI>
205
* <LI>HOLD_STATE means job may be queued but is ineligible to run</LI>
208
* <p>A job submitted in the HOLD_STATE state can be made eligible to run
209
* through the Session.control() method using the Session.RELEASE
211
* @param state the job state at submission
212
* @throws DrmaaException May be one of the following:
214
* <LI>InvalidAttributeFormatException -- the format of the argument is
216
* <LI>InvalidAttributeValueException -- the value of the argument is
218
* <LI>ConflictingAttributeValuesException -- the value of the argument
219
* conflicts with the value of another job template property</LI>
220
* <LI>NoActiveSessionException -- the session has not yet been initialized
221
* or has already been exited</LI>
222
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
223
* contact the DRM</LI>
224
* <LI>AuthorizationException -- the executing user does not have
225
* sufficient permissions to execute the desired action</LI>
226
* <LI>IllegalArgumentException -- an argument is invalid</LI>
227
* <LI>InternalException -- an error has occured in the DRMAA
228
* implementation</LI>
231
public void setJobSubmissionState(int state) throws DrmaaException;
234
* Get the job state at submission.
235
* @return the job state at submission
236
* @throws DrmaaException May be one of the following:
238
* <LI>NoActiveSessionException -- the session has not yet been initialized
239
* or has already been exited</LI>
240
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
241
* contact the DRM</LI>
242
* <LI>AuthorizationException -- the executing user does not have
243
* sufficient permissions to execute the desired action</LI>
244
* <LI>InternalException -- an error has occured in the DRMAA
245
* implementation</LI>
247
* @see #setJobSubmissionState(int)
249
public int getJobSubmissionState() throws DrmaaException;
252
* Set the environment values that define the remote environment.
253
* The values override any remote environment values if there is a
255
* @param env the environment values that define the remote environment
256
* @throws DrmaaException May be one of the following:
258
* <LI>InvalidAttributeFormatException -- the format of the argument is
260
* <LI>InvalidAttributeValueException -- the value of the argument is
262
* <LI>ConflictingAttributeValuesException -- the value of the argument
263
* conflicts with the value of another job template property</LI>
264
* <LI>NoActiveSessionException -- the session has not yet been initialized
265
* or has already been exited</LI>
266
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
267
* contact the DRM</LI>
268
* <LI>AuthorizationException -- the executing user does not have
269
* sufficient permissions to execute the desired action</LI>
270
* <LI>IllegalArgumentException -- an argument is invalid</LI>
271
* <LI>InternalException -- an error has occured in the DRMAA
272
* implementation</LI>
275
public void setJobEnvironment(Map env) throws DrmaaException;
278
* Get the environment values that define the remote environment.
279
* @return the environment values that define the remote environment or null
280
* if it has not been set
281
* @throws DrmaaException May be one of the following:
283
* <LI>NoActiveSessionException -- the session has not yet been initialized
284
* or has already been exited</LI>
285
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
286
* contact the DRM</LI>
287
* <LI>AuthorizationException -- the executing user does not have
288
* sufficient permissions to execute the desired action</LI>
289
* <LI>InternalException -- an error has occured in the DRMAA
290
* implementation</LI>
292
* @see #setJobEnvironment(Map)
294
public Map getJobEnvironment() throws DrmaaException;
297
* Set the directory where the job is executed. If the working directory is
298
* not set, behavior is implementation dependent. The working directory is
299
* evaluated relative to the execution host.
301
* <p>A <CODE>HOME_DIRECTORY</CODE> placeholder at the beginning denotes that
302
* the remaining portion of the directory name is resolved
303
* relative to the job submiter's home directory on the execution host.</p>
305
* <p>The <CODE>PARAMETRIC_INDEX</CODE> placeholder can be used at any position
306
* within the directory name of a parametric job and will be replaced
307
* by the underlying DRM system with the parametric job's index.</p>
309
* <p>The directory name must be specified in a syntax that is common at the
310
* host where the job will be executed.</p>
312
* <p>If no placeholder is used, an absolute directory specification
315
* <p>If the directory does not exist when the job is run, the job enters the
316
* state Session.FAILED.</p>
318
* @param wd the directory where the job is executed
319
* @throws DrmaaException May be one of the following:
321
* <LI>InvalidAttributeFormatException -- the format of the argument is
323
* <LI>InvalidAttributeValueException -- the value of the argument is
325
* <LI>ConflictingAttributeValuesException -- the value of the argument
326
* conflicts with the value of another job template property</LI>
327
* <LI>NoActiveSessionException -- the session has not yet been initialized
328
* or has already been exited</LI>
329
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
330
* contact the DRM</LI>
331
* <LI>AuthorizationException -- the executing user does not have
332
* sufficient permissions to execute the desired action</LI>
333
* <LI>IllegalArgumentException -- an argument is invalid</LI>
334
* <LI>InternalException -- an error has occured in the DRMAA
335
* implementation</LI>
338
public void setWorkingDirectory(String wd) throws DrmaaException;
341
* Get the directory where the job is executed.
342
* @return the directory where the job is executed or null if it has not been
344
* @throws DrmaaException May be one of the following:
346
* <LI>NoActiveSessionException -- the session has not yet been initialized
347
* or has already been exited</LI>
348
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
349
* contact the DRM</LI>
350
* <LI>AuthorizationException -- the executing user does not have
351
* sufficient permissions to execute the desired action</LI>
352
* <LI>InternalException -- an error has occured in the DRMAA
353
* implementation</LI>
355
* @see #setWorkingDirectory(String)
357
public String getWorkingDirectory() throws DrmaaException;
360
* Set an opaque string specifying how to resolve site-specific resources
361
* and/or policies. The job category can be used, for example, to submit
362
* jobs that are "low priority" jobs. It is then up to the local
363
* DRM administrator to map "low priority" to a set of appropriate
364
* job submission characteristics, such as reduced memory allowance or
365
* lower priority value.
366
* @param category an opaque string specifying how to resolve site-specific
367
* resources and/or policies.
368
* @throws DrmaaException May be one of the following:
370
* <LI>InvalidAttributeFormatException -- the format of the argument is
372
* <LI>InvalidAttributeValueException -- the value of the argument is
374
* <LI>ConflictingAttributeValuesException -- the value of the argument
375
* conflicts with the value of another job template property</LI>
376
* <LI>NoActiveSessionException -- the session has not yet been initialized
377
* or has already been exited</LI>
378
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
379
* contact the DRM</LI>
380
* <LI>AuthorizationException -- the executing user does not have
381
* sufficient permissions to execute the desired action</LI>
382
* <LI>IllegalArgumentException -- an argument is invalid</LI>
383
* <LI>InternalException -- an error has occured in the DRMAA
384
* implementation</LI>
387
public void setJobCategory(String category) throws DrmaaException;
390
* Get the opaque string specifying how to resolve site-specific resources
392
* @return the opaque string specifying how to resolve site-specific
393
* resources and/or policies or null if it has not been set
394
* @throws DrmaaException May be one of the following:
396
* <LI>NoActiveSessionException -- the session has not yet been initialized
397
* or has already been exited</LI>
398
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
399
* contact the DRM</LI>
400
* <LI>AuthorizationException -- the executing user does not have
401
* sufficient permissions to execute the desired action</LI>
402
* <LI>InternalException -- an error has occured in the DRMAA
403
* implementation</LI>
405
* @see #setJobCategory(String)
407
public String getJobCategory() throws DrmaaException;
410
* Set an opaque string that is passed by the end user to DRMAA to specify
411
* site-specific resources and/or policies.
412
* @param spec an opaque string that is passed by the end user to DRMAA to
413
* specify site-specific resources and/or policies
414
* @throws DrmaaException May be one of the following:
416
* <LI>InvalidAttributeFormatException -- the format of the argument is
418
* <LI>InvalidAttributeValueException -- the value of the argument is
420
* <LI>ConflictingAttributeValuesException -- the value of the argument
421
* conflicts with the value of another job template property</LI>
422
* <LI>NoActiveSessionException -- the session has not yet been initialized
423
* or has already been exited</LI>
424
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
425
* contact the DRM</LI>
426
* <LI>AuthorizationException -- the executing user does not have
427
* sufficient permissions to execute the desired action</LI>
428
* <LI>IllegalArgumentException -- an argument is invalid</LI>
429
* <LI>InternalException -- an error has occured in the DRMAA
430
* implementation</LI>
433
public void setNativeSpecification(String spec) throws DrmaaException;
436
* Get the opaque string that is passed by the end user to DRMAA to specify
437
* site-specific resources and/or policies.
438
* @return the opaque string that is passed by the end user to DRMAA to
439
* specify site-specific resources and/or policies or null if it has not
441
* @throws DrmaaException May be one of the following:
443
* <LI>NoActiveSessionException -- the session has not yet been initialized
444
* or has already been exited</LI>
445
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
446
* contact the DRM</LI>
447
* <LI>AuthorizationException -- the executing user does not have
448
* sufficient permissions to execute the desired action</LI>
449
* <LI>InternalException -- an error has occured in the DRMAA
450
* implementation</LI>
452
* @see #setNativeSpecification(String)
454
public String getNativeSpecification() throws DrmaaException;
457
* Set the list of email addresses used to report the job completion and
459
* @param email the list of email addresses used to report the job
460
* completion and status.
461
* @throws DrmaaException May be one of the following:
463
* <LI>InvalidAttributeFormatException -- the format of the argument is
465
* <LI>InvalidAttributeValueException -- the value of the argument is
467
* <LI>ConflictingAttributeValuesException -- the value of the argument
468
* conflicts with the value of another job template property</LI>
469
* <LI>NoActiveSessionException -- the session has not yet been initialized
470
* or has already been exited</LI>
471
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
472
* contact the DRM</LI>
473
* <LI>AuthorizationException -- the executing user does not have
474
* sufficient permissions to execute the desired action</LI>
475
* <LI>IllegalArgumentException -- an argument is invalid</LI>
476
* <LI>InternalException -- an error has occured in the DRMAA
477
* implementation</LI>
480
public void setEmail(Set email) throws DrmaaException;
483
* Get the list of email addresses used to report the job completion and
485
* @return the list of email addresses used to report the job completion
486
* and status or null if they have not been set
487
* @throws DrmaaException May be one of the following:
489
* <LI>NoActiveSessionException -- the session has not yet been initialized
490
* or has already been exited</LI>
491
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
492
* contact the DRM</LI>
493
* <LI>AuthorizationException -- the executing user does not have
494
* sufficient permissions to execute the desired action</LI>
495
* <LI>InternalException -- an error has occured in the DRMAA
496
* implementation</LI>
498
* @see #setEmail(Set)
500
public Set getEmail() throws DrmaaException;
503
* Set whether to block sending e-mail by default, regardless of the DRMS
504
* settings. This property can only be used to prevent email from being
505
* sent. It cannot force the DRM to send email.
506
* @param blockEmail whether to block sending e-mail by default
507
* @throws DrmaaException May be one of the following:
509
* <LI>InvalidAttributeFormatException -- the format of the argument is
511
* <LI>InvalidAttributeValueException -- the value of the argument is
513
* <LI>ConflictingAttributeValuesException -- the value of the argument
514
* conflicts with the value of another job template property</LI>
515
* <LI>NoActiveSessionException -- the session has not yet been initialized
516
* or has already been exited</LI>
517
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
518
* contact the DRM</LI>
519
* <LI>AuthorizationException -- the executing user does not have
520
* sufficient permissions to execute the desired action</LI>
521
* <LI>IllegalArgumentException -- an argument is invalid</LI>
522
* <LI>InternalException -- an error has occured in the DRMAA
523
* implementation</LI>
526
public void setBlockEmail(boolean blockEmail) throws DrmaaException;
529
* Get whether to block sending e-mail by default, regardless of the DRMS
531
* @return whether to block sending e-mail by default
532
* @throws DrmaaException May be one of the following:
534
* <LI>NoActiveSessionException -- the session has not yet been initialized
535
* or has already been exited</LI>
536
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
537
* contact the DRM</LI>
538
* <LI>AuthorizationException -- the executing user does not have
539
* sufficient permissions to execute the desired action</LI>
540
* <LI>InternalException -- an error has occured in the DRMAA
541
* implementation</LI>
543
* @see #setBlockEmail(boolean)
545
public boolean getBlockEmail() throws DrmaaException;
548
* Set the earliest time when the job may be eligible to be run.
549
* @param startTime the earliest time when the job may be eligible to be run
550
* @throws DrmaaException May be one of the following:
552
* <LI>InvalidAttributeFormatException -- the format of the argument is
554
* <LI>InvalidAttributeValueException -- the value of the argument is
556
* <LI>ConflictingAttributeValuesException -- the value of the argument
557
* conflicts with the value of another job template property</LI>
558
* <LI>NoActiveSessionException -- the session has not yet been initialized
559
* or has already been exited</LI>
560
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
561
* contact the DRM</LI>
562
* <LI>AuthorizationException -- the executing user does not have
563
* sufficient permissions to execute the desired action</LI>
564
* <LI>IllegalArgumentException -- an argument is invalid</LI>
565
* <LI>InternalException -- an error has occured in the DRMAA
566
* implementation</LI>
569
public void setStartTime(PartialTimestamp startTime) throws DrmaaException;
572
* Get the earliest time when the job may be eligible to be run.
573
* @return the earliest time when the job may be eligible to be run or null
574
* if it has not been set
575
* @throws DrmaaException May be one of the following:
577
* <LI>NoActiveSessionException -- the session has not yet been initialized
578
* or has already been exited</LI>
579
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
580
* contact the DRM</LI>
581
* <LI>AuthorizationException -- the executing user does not have
582
* sufficient permissions to execute the desired action</LI>
583
* <LI>InternalException -- an error has occured in the DRMAA
584
* implementation</LI>
586
* @see #setStartTime(PartialTimestamp)
588
public PartialTimestamp getStartTime() throws DrmaaException;
591
* Set the name of the job. A job name will be comprised of alpha-numeric
592
* and _ characters. The DRMAA implementation may truncate client
593
* provided job names to an implementation defined length that is at least
595
* @param name the name of the job
596
* @throws DrmaaException May be one of the following:
598
* <LI>InvalidAttributeFormatException -- the format of the argument is
600
* <LI>InvalidAttributeValueException -- the value of the argument is
602
* <LI>ConflictingAttributeValuesException -- the value of the argument
603
* conflicts with the value of another job template property</LI>
604
* <LI>NoActiveSessionException -- the session has not yet been initialized
605
* or has already been exited</LI>
606
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
607
* contact the DRM</LI>
608
* <LI>AuthorizationException -- the executing user does not have
609
* sufficient permissions to execute the desired action</LI>
610
* <LI>IllegalArgumentException -- an argument is invalid</LI>
611
* <LI>InternalException -- an error has occured in the DRMAA
612
* implementation</LI>
615
public void setJobName(String name) throws DrmaaException;
618
* Get the name of the job.
619
* @return the name of the job or null if it has not been set
620
* @throws DrmaaException May be one of the following:
622
* <LI>NoActiveSessionException -- the session has not yet been initialized
623
* or has already been exited</LI>
624
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
625
* contact the DRM</LI>
626
* <LI>AuthorizationException -- the executing user does not have
627
* sufficient permissions to execute the desired action</LI>
628
* <LI>InternalException -- an error has occured in the DRMAA
629
* implementation</LI>
631
* @see #setJobName(String)
633
public String getJobName() throws DrmaaException;
636
* Set the job's standard input path.
637
* Unless set elsewhere, if not explicitly set in the job template, the job
638
* is started with an empty input stream.
640
* <p>If set, specifies the network path of the job's input stream in
641
* the form of [hostname]:file_path</p>
643
* <p>When the transferFiles property is supported and has it's inputStream
644
* property set, the input file will be fetched by the underlying DRM
645
* system from the specified host or from the submit host if no hostname
648
* <p>When the transferFiles property is not supported or does not have its
649
* inputStream property set, the input file is always expected to be
650
* at the host where the job is executed irrespective of a whether a
651
* hostname is specified in the path.</p>
653
* <p>The <CODE>PARAMETRIC_INDEX</CODE> placeholder can be used at any position
654
* within the file path of parametric job templates and will be replaced
655
* by the underlying DRM system with the parametric job's index.</p>
657
* <p>A <CODE>HOME_DIRECTORY</CODE> placeholder at the beginning of the file
658
* path denotes that the remaining portion of the file path is relative to
659
* the job submiter's home directory on the host where the file is
662
* <p>A <CODE>WORKING_DIRECTORY</CODE> placeholder at the beginning of the file
663
* path denotes that the remaining portion of the file path is relative to
664
* the job's working directory on the host where the file is located.</p>
666
* <p>The file path must be specified in a syntax that is common at the host
667
* where the file is located.</p>
669
* <p>When the job is run, if this property is set, and the file can't be read,
670
* the job will enter the state Session.FAILED.</p>
671
* @param inputPath the job's standard input path
672
* @throws DrmaaException May be one of the following:
674
* <LI>InvalidAttributeFormatException -- the format of the argument is
676
* <LI>InvalidAttributeValueException -- the value of the argument is
678
* <LI>ConflictingAttributeValuesException -- the value of the argument
679
* conflicts with the value of another job template property</LI>
680
* <LI>NoActiveSessionException -- the session has not yet been initialized
681
* or has already been exited</LI>
682
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
683
* contact the DRM</LI>
684
* <LI>AuthorizationException -- the executing user does not have
685
* sufficient permissions to execute the desired action</LI>
686
* <LI>IllegalArgumentException -- an argument is invalid</LI>
687
* <LI>InternalException -- an error has occured in the DRMAA
688
* implementation</LI>
691
public void setInputPath(String inputPath) throws DrmaaException;
694
* Get the job's standard input path.
695
* @return the job's standard input path or null if it has not been set
696
* @throws DrmaaException May be one of the following:
698
* <LI>NoActiveSessionException -- the session has not yet been initialized
699
* or has already been exited</LI>
700
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
701
* contact the DRM</LI>
702
* <LI>AuthorizationException -- the executing user does not have
703
* sufficient permissions to execute the desired action</LI>
704
* <LI>InternalException -- an error has occured in the DRMAA
705
* implementation</LI>
707
* @see #setInputPath(String)
709
public String getInputPath() throws DrmaaException;
712
* Sets how to direct the job's standard output.
713
* If not explicitly set in the job template, the whereabouts of the jobs
714
* output stream is not defined.
715
* If set, specifies the network path of the job's output stream file in the
716
* form of [hostname]:file_path
718
* <p>When the transferFiles property is supported and has its outputStream
719
* property set, the output file will be transferred by the underlying
720
* DRM system to the specified host or to the submit host if no hostname is
723
* <p>When the transferFiles property is not supported or does
724
* not have it's outputStream property set, the output file is always kept
725
* at the host where the job is executed irrespective of a whether a
726
* hostname is specified in the path.</p>
728
* <p>The <CODE>PARAMETRIC_INDEX</CODE> placeholder can be used at any position
729
* within the file path of parametric job templates and will be replaced
730
* by the underlying DRM system with the parametric job's index.</p>
732
* <p>A <CODE>HOME_DIRECTORY</CODE> placeholder at the beginning of the file
733
* path denotes that the remaining portion of the file path is relative to
734
* the job submiter's home directory on the host where the file is
737
* <p>A <CODE>WORKING_DIRECTORY</CODE> placeholder at the beginning of the file
738
* path denotes that the remaining portion of the file path is relative to
739
* the job's working directory on the host where the file is located.</p>
741
* <p>The file path must be specified in a syntax that is common at the host
742
* where the file is located.</p>
744
* <p>When the job is run, if this property is set, and the file can't be
745
* written before execution the job will enter the state Session.FAILED.</p>
746
* @param outputPath how to direct the job's standard output
747
* @throws DrmaaException May be one of the following:
749
* <LI>InvalidAttributeFormatException -- the format of the argument is
751
* <LI>InvalidAttributeValueException -- the value of the argument is
753
* <LI>ConflictingAttributeValuesException -- the value of the argument
754
* conflicts with the value of another job template property</LI>
755
* <LI>NoActiveSessionException -- the session has not yet been initialized
756
* or has already been exited</LI>
757
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
758
* contact the DRM</LI>
759
* <LI>AuthorizationException -- the executing user does not have
760
* sufficient permissions to execute the desired action</LI>
761
* <LI>IllegalArgumentException -- an argument is invalid</LI>
762
* <LI>InternalException -- an error has occured in the DRMAA
763
* implementation</LI>
766
public void setOutputPath(String outputPath) throws DrmaaException;
769
* Gets how to direct the job's standard output.
770
* @return how to direct the job's standard output or null if it has not been
772
* @throws DrmaaException May be one of the following:
774
* <LI>NoActiveSessionException -- the session has not yet been initialized
775
* or has already been exited</LI>
776
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
777
* contact the DRM</LI>
778
* <LI>AuthorizationException -- the executing user does not have
779
* sufficient permissions to execute the desired action</LI>
780
* <LI>InternalException -- an error has occured in the DRMAA
781
* implementation</LI>
783
* @see #setOutputPath(String)
785
public String getOutputPath() throws DrmaaException;
788
* Sets how to direct the job's standard error.
789
* If not explicitly set in the job template, the whereabouts of the job's
790
* error stream is not defined. If set, specifies the network path of the
791
* job's error stream file in the form [hostname]:file_path
793
* <p>When the transferFiles property is supported and has its errorStream
794
* property set, the error file will be transferred by the underlying
795
* DRM system to the specified host or to the submit host if no hostname is
798
* <p>When the transferFiles property is not supported or does
799
* not have it's errorStream property set, the error file is always kept
800
* at the host where the job is executed irrespective of a whether a
801
* hostname is specified in the path.</p>
803
* <p>The <CODE>PARAMETRIC_INDEX</CODE> placeholder can be used at any position
804
* within the file path of parametric job templates and will be replaced
805
* by the underlying DRM system with the parametric job's index.</p>
807
* <p>A <CODE>HOME_DIRECTORY</CODE> placeholder at the beginning of the file
808
* path denotes that the remaining portion of the file path is relative to
809
* the job submiter's home directory on the host where the file is
812
* <p>A <CODE>WORKING_DIRECTORY</CODE> placeholder at the beginning of the file
813
* path denotes that the remaining portion of the file path is relative to
814
* the job's working directory on the host where the file is located.</p>
816
* <p>The file path must be specified in a syntax that is common at the host
817
* where the file is located.</p>
819
* <p>When the job is run, if this property is set, and the file can't be
820
* written before execution the job will enter the state Session.FAILED.</p>
821
* @param errorPath how to direct the job's standard error
822
* @throws DrmaaException May be one of the following:
824
* <LI>InvalidAttributeFormatException -- the format of the argument is
826
* <LI>InvalidAttributeValueException -- the value of the argument is
828
* <LI>ConflictingAttributeValuesException -- the value of the argument
829
* conflicts with the value of another job template property</LI>
830
* <LI>NoActiveSessionException -- the session has not yet been initialized
831
* or has already been exited</LI>
832
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
833
* contact the DRM</LI>
834
* <LI>AuthorizationException -- the executing user does not have
835
* sufficient permissions to execute the desired action</LI>
836
* <LI>IllegalArgumentException -- an argument is invalid</LI>
837
* <LI>InternalException -- an error has occured in the DRMAA
838
* implementation</LI>
841
public void setErrorPath(String errorPath) throws DrmaaException;
844
* Gets how to direct the job's standard error.
845
* @return how to direct the job's standard error
846
* @throws DrmaaException May be one of the following:
848
* <LI>NoActiveSessionException -- the session has not yet been initialized
849
* or has already been exited</LI>
850
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
851
* contact the DRM</LI>
852
* <LI>AuthorizationException -- the executing user does not have
853
* sufficient permissions to execute the desired action</LI>
854
* <LI>InternalException -- an error has occured in the DRMAA
855
* implementation</LI>
857
* @see #setErrorPath(String)
859
public String getErrorPath() throws DrmaaException;
862
* Sets whether the error stream should be intermixed with the output
863
* stream. If not explicitly set in the job template this property defaults
864
* to <CODE>false</CODE>.
866
* <p>If <CODE>true</CODE> is specified the underlying DRM system will ignore
867
* the value of the errorPath property and intermix the standard error
868
* stream with the standard output stream as specified by the outputPath
870
* @param join whether the error stream should be intermixed with the output
872
* @throws DrmaaException May be one of the following:
874
* <LI>InvalidAttributeFormatException -- the format of the argument is
876
* <LI>InvalidAttributeValueException -- the value of the argument is
878
* <LI>ConflictingAttributeValuesException -- the value of the argument
879
* conflicts with the value of another job template property</LI>
880
* <LI>NoActiveSessionException -- the session has not yet been initialized
881
* or has already been exited</LI>
882
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
883
* contact the DRM</LI>
884
* <LI>AuthorizationException -- the executing user does not have
885
* sufficient permissions to execute the desired action</LI>
886
* <LI>IllegalArgumentException -- an argument is invalid</LI>
887
* <LI>InternalException -- an error has occured in the DRMAA
888
* implementation</LI>
891
public void setJoinFiles(boolean join) throws DrmaaException;
894
* Gets whether the error stream should be intermixed with the output
896
* @return Whether the error stream should be intermixed with the output
898
* @throws DrmaaException May be one of the following:
900
* <LI>NoActiveSessionException -- the session has not yet been initialized
901
* or has already been exited</LI>
902
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
903
* contact the DRM</LI>
904
* <LI>AuthorizationException -- the executing user does not have
905
* sufficient permissions to execute the desired action</LI>
906
* <LI>InternalException -- an error has occured in the DRMAA
907
* implementation</LI>
909
* @see #setJoinFiles(boolean)
911
public boolean getJoinFiles() throws DrmaaException;
914
* Specifies, which of the standard I/O files (stdin, stdout and stderr) are
915
* to be transferred to/from the execution host. If not set, defaults to
916
* the equivalent of a FileTransferMode instance with all properties set to
917
* false. See inputPath, outputPath and errorPath setters for information
918
* about how to specify the standard input file, standard output file, and
919
* standard error file.
921
* <p>If the FileTransferMode instance's errorStream property is set to
922
* <CODE>true</CODE>, the errorPath property is taken to specify the
923
* location to which error files should be transfered after the job
926
* <p>If the FileTransferMode instance's inputStream property is set to
927
* <CODE>true</CODE>, the inputPath property is taken to specify the
928
* location from which input files should be transfered before the job
931
* <p>If the FileTransferMode instance's outputStream property is set to
932
* <CODE>true</CODE>, the outputPath property is taken to specify the
933
* location to which output files should be transfered after the job
936
* @param mode how to transfer files between hosts.
937
* @throws DrmaaException May be one of the following:
939
* <LI>InvalidAttributeFormatException -- the format of the argument is
941
* <LI>InvalidAttributeValueException -- the value of the argument is
943
* <LI>ConflictingAttributeValuesException -- the value of the argument
944
* conflicts with the value of another job template property</LI>
945
* <LI>NoActiveSessionException -- the session has not yet been initialized
946
* or has already been exited</LI>
947
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
948
* contact the DRM</LI>
949
* <LI>AuthorizationException -- the executing user does not have
950
* sufficient permissions to execute the desired action</LI>
951
* <LI>IllegalArgumentException -- an argument is invalid</LI>
952
* <LI>InternalException -- an error has occured in the DRMAA
953
* implementation</LI>
955
* @see #setInputPath(String)
956
* @see #setOutputPath(String)
957
* @see #setErrorPath(String)
959
public void setTransferFiles(FileTransferMode mode) throws DrmaaException;
962
* Gets how to transfer files between hosts.
963
* @return how to transfer files between hosts.
964
* @throws DrmaaException May be one of the following:
966
* <LI>NoActiveSessionException -- the session has not yet been initialized
967
* or has already been exited</LI>
968
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
969
* contact the DRM</LI>
970
* <LI>AuthorizationException -- the executing user does not have
971
* sufficient permissions to execute the desired action</LI>
972
* <LI>InternalException -- an error has occured in the DRMAA
973
* implementation</LI>
975
* @see #setTransferFiles(FileTransferMode)
977
public FileTransferMode getTransferFiles() throws DrmaaException;
980
* Sets a deadline after which the DRMS will terminate the job.
981
* @param deadline the deadline after which the DRMS will terminate the job
982
* @throws DrmaaException May be one of the following:
984
* <LI>InvalidAttributeFormatException -- the format of the argument is
986
* <LI>InvalidAttributeValueException -- the value of the argument is
988
* <LI>ConflictingAttributeValuesException -- the value of the argument
989
* conflicts with the value of another job template property</LI>
990
* <LI>NoActiveSessionException -- the session has not yet been initialized
991
* or has already been exited</LI>
992
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
993
* contact the DRM</LI>
994
* <LI>AuthorizationException -- the executing user does not have
995
* sufficient permissions to execute the desired action</LI>
996
* <LI>IllegalArgumentException -- an argument is invalid</LI>
997
* <LI>InternalException -- an error has occured in the DRMAA
998
* implementation</LI>
1001
public void setDeadlineTime(PartialTimestamp deadline)
1002
throws DrmaaException;
1005
* Sets a deadline after which the DRMS will terminate the job.
1006
* @return the deadline after which the DRMS will terminate the job
1007
* @throws DrmaaException May be one of the following:
1009
* <LI>NoActiveSessionException -- the session has not yet been initialized
1010
* or has already been exited</LI>
1011
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1012
* contact the DRM</LI>
1013
* <LI>AuthorizationException -- the executing user does not have
1014
* sufficient permissions to execute the desired action</LI>
1015
* <LI>InternalException -- an error has occured in the DRMAA
1016
* implementation</LI>
1018
* @see #setDeadlineTime(PartialTimestamp)
1020
public PartialTimestamp getDeadlineTime() throws DrmaaException;
1023
* Sets when the job's wall clock time limit has
1024
* been exceeded. The DRMS will terminate a job that has exceeded its wall
1025
* clock time limit. Note that time spent suspended is also accounted for
1027
* @param hardWallclockLimit when the job's wall clock time limit has been
1028
* exceeded. Specified in seconds
1029
* @throws DrmaaException May be one of the following:
1031
* <LI>InvalidAttributeFormatException -- the format of the argument is
1033
* <LI>InvalidAttributeValueException -- the value of the argument is
1035
* <LI>ConflictingAttributeValuesException -- the value of the argument
1036
* conflicts with the value of another job template property</LI>
1037
* <LI>NoActiveSessionException -- the session has not yet been initialized
1038
* or has already been exited</LI>
1039
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1040
* contact the DRM</LI>
1041
* <LI>AuthorizationException -- the executing user does not have
1042
* sufficient permissions to execute the desired action</LI>
1043
* <LI>IllegalArgumentException -- an argument is invalid</LI>
1044
* <LI>InternalException -- an error has occured in the DRMAA
1045
* implementation</LI>
1048
public void setHardWallclockTimeLimit(long hardWallclockLimit)
1049
throws DrmaaException;
1052
* Gets the duration of the job's wall clock time limit.
1053
* @return when the job's wall clock time limit has been exceeded.
1054
* Specified in seconds
1055
* @throws DrmaaException May be one of the following:
1057
* <LI>NoActiveSessionException -- the session has not yet been initialized
1058
* or has already been exited</LI>
1059
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1060
* contact the DRM</LI>
1061
* <LI>AuthorizationException -- the executing user does not have
1062
* sufficient permissions to execute the desired action</LI>
1063
* <LI>InternalException -- an error has occured in the DRMAA
1064
* implementation</LI>
1066
* @see #setHardWallclockTimeLimit(long)
1068
public long getHardWallclockTimeLimit() throws DrmaaException;
1071
* Sets an estimate as to how much wall clock time job will need to
1072
* complete. Note that time spent suspended is also accounted for here.<P>
1074
* This attribute is intended to assist the scheduler.
1075
* If the time specified in insufficient, the
1076
* drmaa-implementation may impose a scheduling penalty.
1077
* @param softWallclockLimit an estimate as to how much wall clock time job
1078
* will need to complete. Specified in seconds
1079
* @throws DrmaaException May be one of the following:
1081
* <LI>InvalidAttributeFormatException -- the format of the argument is
1083
* <LI>InvalidAttributeValueException -- the value of the argument is
1085
* <LI>ConflictingAttributeValuesException -- the value of the argument
1086
* conflicts with the value of another job template property</LI>
1087
* <LI>NoActiveSessionException -- the session has not yet been initialized
1088
* or has already been exited</LI>
1089
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1090
* contact the DRM</LI>
1091
* <LI>AuthorizationException -- the executing user does not have
1092
* sufficient permissions to execute the desired action</LI>
1093
* <LI>IllegalArgumentException -- an argument is invalid</LI>
1094
* <LI>InternalException -- an error has occured in the DRMAA
1095
* implementation</LI>
1098
public void setSoftWallclockTimeLimit(long softWallclockLimit)
1099
throws DrmaaException;
1102
* Gets an estimate as to how much wall clock time job will need to
1104
* @return an estimate as to how much wall clock time job will need
1105
* to complete. Specified in seconds
1106
* @throws DrmaaException May be one of the following:
1108
* <LI>NoActiveSessionException -- the session has not yet been initialized
1109
* or has already been exited</LI>
1110
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1111
* contact the DRM</LI>
1112
* <LI>AuthorizationException -- the executing user does not have
1113
* sufficient permissions to execute the desired action</LI>
1114
* <LI>InternalException -- an error has occured in the DRMAA
1115
* implementation</LI>
1117
* @see #setSoftWallclockTimeLimit(long)
1119
public long getSoftWallclockTimeLimit() throws DrmaaException;
1122
* Sets how long the job may be in a running state before its limit has been
1123
* exceeded, and therefore is terminated by the DRMS.
1124
* @param hardRunLimit how long the job may be in a running state before its
1125
* limit has been exceeded. Specified in seconds
1126
* @throws DrmaaException May be one of the following:
1128
* <LI>InvalidAttributeFormatException -- the format of the argument is
1130
* <LI>InvalidAttributeValueException -- the value of the argument is
1132
* <LI>ConflictingAttributeValuesException -- the value of the argument
1133
* conflicts with the value of another job template property</LI>
1134
* <LI>NoActiveSessionException -- the session has not yet been initialized
1135
* or has already been exited</LI>
1136
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1137
* contact the DRM</LI>
1138
* <LI>AuthorizationException -- the executing user does not have
1139
* sufficient permissions to execute the desired action</LI>
1140
* <LI>IllegalArgumentException -- an argument is invalid</LI>
1141
* <LI>InternalException -- an error has occured in the DRMAA
1142
* implementation</LI>
1145
public void setHardRunDurationLimit(long hardRunLimit)
1146
throws DrmaaException;
1149
* Gets how long the job may be in a running state before its limit has been
1151
* @return how long the job may be in a running state before its limit has
1152
* been exceeded. Specified in seconds
1153
* @throws DrmaaException May be one of the following:
1155
* <LI>NoActiveSessionException -- the session has not yet been initialized
1156
* or has already been exited</LI>
1157
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1158
* contact the DRM</LI>
1159
* <LI>AuthorizationException -- the executing user does not have
1160
* sufficient permissions to execute the desired action</LI>
1161
* <LI>InternalException -- an error has occured in the DRMAA
1162
* implementation</LI>
1164
* @see #setHardRunDurationLimit(long)
1166
public long getHardRunDurationLimit() throws DrmaaException;
1169
* Sets an estimate as to how long the job will need to remain in a running
1170
* state to complete. This attribute is intended to assist the scheduler.
1171
* If the time specified in insufficient, the DRMAA implementation may
1172
* impose a scheduling penalty.
1173
* @param softRunLimit an estimate as to how long the job will need to
1174
* remain in a running state to complete. Specified in seconds
1175
* @throws DrmaaException May be one of the following:
1177
* <LI>InvalidAttributeFormatException -- the format of the argument is
1179
* <LI>InvalidAttributeValueException -- the value of the argument is
1181
* <LI>ConflictingAttributeValuesException -- the value of the argument
1182
* conflicts with the value of another job template property</LI>
1183
* <LI>NoActiveSessionException -- the session has not yet been initialized
1184
* or has already been exited</LI>
1185
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1186
* contact the DRM</LI>
1187
* <LI>AuthorizationException -- the executing user does not have
1188
* sufficient permissions to execute the desired action</LI>
1189
* <LI>IllegalArgumentException -- an argument is invalid</LI>
1190
* <LI>InternalException -- an error has occured in the DRMAA
1191
* implementation</LI>
1194
public void setSoftRunDurationLimit(long softRunLimit)
1195
throws DrmaaException;
1198
* Gets an estimate as to how long the job will need to remain in a running
1199
* state to complete.
1200
* @return an estimate as to how long the job will need to remain
1201
* in a running state to complete. Specified in seconds
1202
* @throws DrmaaException May be one of the following:
1204
* <LI>NoActiveSessionException -- the session has not yet been initialized
1205
* or has already been exited</LI>
1206
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1207
* contact the DRM</LI>
1208
* <LI>AuthorizationException -- the executing user does not have
1209
* sufficient permissions to execute the desired action</LI>
1210
* <LI>InternalException -- an error has occured in the DRMAA
1211
* implementation</LI>
1213
* @see #setSoftRunDurationLimit(long)
1215
public long getSoftRunDurationLimit() throws DrmaaException;
1218
* Returns the list of supported property names. This list
1219
* includes supported DRMAA reserved property names (both required and
1220
* optional) and DRM-specific property names.
1221
* @return the list of supported property names
1222
* @throws DrmaaException May be one of the following:
1224
* <LI>NoActiveSessionException -- the session has not yet been initialized
1225
* or has already been exited</LI>
1226
* <LI>DrmCommunicationException -- the DRMAA implementation was unable to
1227
* contact the DRM</LI>
1228
* <LI>AuthorizationException -- the executing user does not have
1229
* sufficient permissions to execute the desired action</LI>
1230
* <LI>InternalException -- an error has occured in the DRMAA
1231
* implementation</LI>
1234
public Set getAttributeNames() throws DrmaaException;
added
removed
source/libs/jdrmaa/src/org/ggf/drmaa/JobTemplate.java
