com.novell.zos.jdl
Class Job

java.lang.Object
  com.novell.zos.jdl.GridObjectInfo
      com.novell.zos.jdl.Job

public class Job
extends GridObjectInfo

The Job class is a representation of a running job instance. This class defines functions for interacting with the server including handling notification of job state transitions, child job submission, managing Joblets and for receiving and sending events from resources and from clients. A Job writer defines a subclass of the Job class and uses the methods available on the Job class for scheduling Joblets and event processing. When a job is started, the Job subclass is instantiated.
There can only be one Job subclass per JDL file. The Job subclass name is not required to match the JDL filename. The filename is the defined job name. However, the JDL filename must match the .job file containing a JDL file. Packaging a JDL file inside of a .job file is necessary for also including the matching .policy and .sched files.

Example of a job that schedules a single Joblet to run on one resource:

 class Simple(Job):
      def job_started_event(self):
          self.schedule(SimpleJoblet)

 class SimpleJoblet(Joblet):
      def joblet_started_event(self):
          print "Hello from Joblet"
 

For the above example, the class Simple is instantiated on the server when a job is started either by client tools or by the Job Scheduler. When a job transitions to the started state, the method job_started_event is invoked. Here the job_started_event invokes the base class method schedule() to create a single instance of SimpleJoblet and schedule the SimpleJoblet to be run on a resource. When an appropriate resource is allocated, the SimpleJoblet class is instantiated and run on the resource.

Each Job has a set of events that are invoked at the state transitions of a Job. On the starting state of a Job, the job_started_event is always invoked.

Following is a list of Job events that are invoked upon Job state transitions:

      job_started_event
      job_completed_event
      job_cancelled_event
      job_failed_event
      job_paused_event
      job_resumed_event

List of Job events invoked upon child Job state transitions:

      child_job_started_event
      child_job_completed_event
      child_job_cancelled_event
      child_job_failed_event

List of provisioner events invoked upon provisioner state transitions:

      provisioner_completed_event
      provisioner_cancelled_event
      provisioner_failed_event

List of Joblet events invoked upon joblet state transitions:

      joblet_started_event
      joblet_completed_event
      joblet_failed_event
      joblet_cancelled_event
      joblet_retry_event

* Of the above list, only the job_started_event is required. The rest are optional.

A Job writer can also handle and invoke custom events within a Job. Events can come from clients, other Jobs and from Joblets.

Example of defining an event handler named mycustom_event in a Job:

 class Simple(Job):
      def job_started_event(self):
          ...

      def mycustom_event(self,params):
          dir = params["directory_to_list"]
          self.schedule(MyJoblet,{ "dir" : dir } )
 

For the above example, the event mycustom_event retrieves an element from the params dictionary that is supplied to every custom event. The dictionary is optionally filled by the caller of the event.

Example of invoking the custom event named 'mycustom_event' from the zos client command line tool:

      zos event mycustom_event directory_to_list="/tmp" 

In the above, a message is sent from the client tool to the job running on the server.

Example of invoking the same custom event from a Joblet:

 class SimpleJoblet(Joblet):
      def joblet_started_event(self):
          ...
          self.sendEvent("mycustom_event", { ... } )

In the above, a message is sent from the Joblet running on a resource to the job running on the server.
The running job has access to a factset which is the aggregation of the Job instance factset (jobinstance.*), the deployed Job factset (job.*, jobargs.*), the User factset (user.*), the Matrix factset (matrix.*) and any jobargs or policy facts supplied at the time the Job is started.

Fact values are retrieved using the GridObjectInfo functions that the Job class inherits.

Example of retrieving the value of the job instance fact state.string from the jobinstance namespace:

 class Simple(Job):
      def job_started_event(self):
          jobstate = self.getFact("jobinstance.state.string")
          print "job state=%s" % (jobstate)
 

Defined Job Instance Facts:

      jobinstance.id                  The job instance unique identifier
      jobinstance.priority            The numeric represenation of the current priority of this job instance (1=lowest, 9=higest).  Default value is the user's default priority
      jobinstance.priority.string     The string representation of the current priority of this job instance
      jobinstance.instancename        The optional human readable name for this job instance
      jobinstance.memo                A brief memo set by this job instance that can be seen in user/administrator portals
      jobinstance.starttime           The formated start date and time for this job instance
      jobinstance.joblet.pspace       The number of 'rows' in a fully expanded p-space definition. Will be equals to the number of joblets only if 'jobinstance.joblet.size' is 1
      jobinstance.joblet.size         The number of p-space rows encapsulated in each joblet. May be explicitly set of derived as a result of specifing joblet count
      jobinstance.joblets.count       The number of joblets under management of this job instance
      jobinstance.joblets.waiting     Number of joblets that are waiting for available resources
      jobinstance.joblets.running     Number of joblets that are actively running on resources
      jobinstance.joblets.failed      Number of joblets that ended in a failed state
      jobinstance.joblets.cancelled   Number of joblets that ended in a cancelled state
      jobinstance.joblets.complete    Number of joblets that completed successfully
      jobinstance.restarted           Whether this job instance was been restarted due to server restart
      jobinstance.resources           The resources currently in use by this job
      jobinstance.resources.count     Number of resources currently in use by this job
      jobinstance.cost                The cost of this job ($)
      jobinstance.cost.burnrate       The computed moving average burn rate of the job ($/hr)
      jobinstance.startat             The date/time that this job was requested to start at
      jobinstance.time.submitted      The time this job instance was submitted
      jobinstance.time.started        The time this job instance was actually started or an estimating if queued
      jobinstance.time.elapsed        The elapsed wall time this job instance has been running or ran (in seconds)
      jobinstance.time.queued         The elapsed wall time this job instance has been a queued (in second)s
      jobinstance.time.elapsed.string The elapsed wall time this job instance has been in a running
      jobinstance.time.completed      The time this job instance completed or an estimation if still active
      jobinstance.matchingresources   The number of currently active resources that match the 'resource' contraints
      jobinstance.privileged          Whether joblets started by this instance can run in extra system joblet slots
      jobinstance.state               The numeric state of this job instance
      jobinstance.state.string        String representation of the current state of this job instance
      jobinstance.problemresources    The names of resources that are excluded from this job instance due to reaching the 'job.maxnodefailures' limit
      jobinstance.problemresources.count      The number of resources that are excluded from this job instance due to reaching the 'job.maxnodefailures' limit
      jobinstance.errors              The error messages recorded for a failed job
      jobinstance.terminationtype     The cause of the termination for a cancelled or failed job.
      jobinstance.originid            The job identifier of the root job of this hierarchy or this job if a top level job
      jobinstance.parentid            The job identifier of the parent job of this hierarchy or empty if this is a top level job with no parent
      jobinstance.childids            String array of child job ids. Empty array if no child jobs were launched
      jobinstance.provision.count     The total number of resources that have been automaticaly provisioned (or are in progress) for this job
      jobinstance.provision.pending   The total number of automatically provisioned resources that are pending online status
      jobinstance.provision.problemresources  The names of automatically provisioned resources that encountered provisioning errors and have been excluded
      jobinstance.provision.avoidresources    The names of automatically provisioned resources that are currently being avoided (not yet excluded) because of prior provisioning errors
      jobinstance.provision.problemresources.count    The number of automatically provisioned resources that encountered provisioning errors and have been excluded
  

Field Summary

static int	CANCELLED_STATE Cancelled end state.
static int	CANCELLING_STATE Cancelling.
static int	COMPLETED_STATE Completed end state.
static int	COMPLETING_STATE Completing.
static int	FAILED_STATE Failed end state.
static int	FAILING_STATE Failing.
static int	PAUSED_STATE Paused.
static int	QUEUED_STATE Queued.
static int	RUNNING_STATE Running.
static int	STARTING_STATE Starting.
static int	SUBMITTED_STATE Submitted.
static java.lang.String	TERMINATION_TYPE_ADMIN Indicate Job was cancelled by admin.
static java.lang.String	TERMINATION_TYPE_JOB Indicate Job was cancelled by a Job function.
static java.lang.String	TERMINATION_TYPE_TIMEOUT Indicate Job was cancelled due to exceeding the job timeout value.
static java.lang.String	TERMINATION_TYPE_USER Indicate Job was cancelled by client user.

Method Summary

void	cancel() Cancel this job instance.
void	cancel(java.lang.String reason) Cancel this job instance with a reason.
void	cancelAllJoblets() Cancel all joblets for this job instance.
void	cancelAllTimers() Cancel all timers for this job instance.
void	changePriority(java.lang.String priority) Change priority of this job.
void	child_job_cancelled_event(Job job) child_job_cancelled_event is fired when a child job has transitioned to the cancelled state.
void	child_job_completed_event(Job job) child_job_completed_event is fired when a child job has transitioned to the completed state.
void	child_job_failed_event(Job job) child_job_failed_event is fired when a child job has transitioned to the failed state.
void	child_job_started_event(Job job) child_job_started_event is fired when a child job has transitioned to the running state.
void	fail() Fail this job instance.
void	fail(java.lang.String reason) Fail this job instance with a reason.
org.python.core.PyList	getChildJobs() Retrieve a list of child jobs submitted by this job.
Joblet	getJoblet(int jobletNumber) Retrieve a scheduled Joblet.
java.lang.Object	getMatchingResources() Retrieve a List of matching resources for this Job instance.
java.lang.Object	getMatchingResources(ScheduleSpec scheduleSpec) Retrieve a List of matching resources for this Job instance using the supplied ScheduleSpec.
boolean	isProvisionJob()
void	job_cancelled_event() job_cancelled_event is fired when a job is transitioning to the cancelled state.
void	job_completed_event() job_completed_event is fired when the job is transitioning to the completed state.
void	job_failed_event() job_failed_event is fired when the job is transitioning to the failed state.
void	job_paused_event() Fired when a job is paused by user or administrator.
void	job_resumed_event() Fired when a previously paused job is resumed.
void	job_started_event() job_started_event is the first event to be called when a job is started.
void	joblet_cancelled_event(int jobletNumber, java.lang.String resourceId, java.lang.String reason) joblet_cancelled_event is fired when the Joblet has had execution cancelled.
void	joblet_completed_event(int jobletNumber, java.lang.String resourceId) joblet_completed_event is fired when the Joblet has completed execution on a resource.
void	joblet_failed_event(int jobletNumber, java.lang.String resourceId, java.lang.String errorMsg) joblet_failed_event is fired when the Joblet has failed execution on a resource.
void	joblet_retry_event(int jobletNumber, java.lang.String resourceId, java.lang.String errorMsg) joblet_retry_event is fired when the Joblet is transitioning back to a waiting state after a failed execution on a resource.
void	joblet_started_event(int jobletNumber, java.lang.String resourceId) joblet_started_event is fired when the Joblet has started execution on a resource.
void	pause() Pause this job instance.
void	provisioner_cancelled_event(org.python.core.PyDictionary params) provisioner_cancelled_event is fired when the provision operation submitted by this job has been cancelled.
void	provisioner_completed_event(org.python.core.PyDictionary params) provisioner_completed_event is fired when the provision operation submitted by this job has completed.
void	provisioner_failed_event(org.python.core.PyDictionary params) provisioner_failed_event is fired when the provision operation submitted by this job has failed.
void	resume() Resume this job instance if it is currently paused.
org.python.core.PyObject	runJob(RunJobSpec runJobSpec) Run a new child or stand-alone job using attributes defined in the supplied RunJobSpec.
org.python.core.PyObject	runJob(java.lang.String job) Run a new child job.
org.python.core.PyObject	runJob(java.lang.String job, org.python.core.PyDictionary params) Run a new child job with supplied job arguments.
org.python.core.PyObject	runJob(java.lang.String job, org.python.core.PyDictionary params, Constraint constraint) Run a new child job using supplied resource Constraint.
org.python.core.PyObject	runJob(java.lang.String job, org.python.core.PyDictionary params, java.lang.String policy) Run a new child job using supplied policy text.
org.python.core.PyDictionary	saveStateValue(org.python.core.PyString name, org.python.core.PyObject value, org.python.core.PyList targetEvents, org.python.core.PyDictionary matchDict) Save a job value for use by a future invocation of a Provisioning Adapter pre or post hook job and/or joblet
org.python.core.PyDictionary	saveStateValue(org.python.core.PyString name, org.python.core.PyObject value, org.python.core.PyList targetEvents, org.python.core.PyList matchNames, org.python.core.PyDictionary matchDict) Save a job value for use by a future invocation of a Provisioning Adapter pre or post hook job and/or joblet
void	schedule(org.python.core.PyType jobletClass) Schedule a single joblet.
void	schedule(org.python.core.PyType jobletClass, int jobletCount) Schedule one or more joblets.
void	schedule(org.python.core.PyType jobletClass, ParameterSpace parameterSpace, org.python.core.PyDictionary params) Schedule a set of joblets using the passed ParameterSpace as the basis for joblet assignment.
void	schedule(org.python.core.PyType jobletClass, ParameterSpace parameterSpace, org.python.core.PyDictionary params, int jobletCount) Schedule a set of joblets using the passed ParameterSpace as the basis for joblet assignment.
void	schedule(org.python.core.PyType jobletClass, ParameterSpace parameterSpace, org.python.core.PyDictionary params, int jobletCount, org.python.core.PyMethod allocate) Schedule a set of joblets using the passed ParameterSpace as the basis for joblet assignment.
void	schedule(org.python.core.PyType jobletClass, org.python.core.PyDictionary params) Schedule a single joblet with additional joblet facts.
void	schedule(org.python.core.PyType jobletClass, org.python.core.PyDictionary params, int jobletCount) Schedule one or more joblets with additional joblet facts.
void	schedule(ScheduleSpec spec) Schedule a set of joblets using the passed ScheduleSpec.
void	scheduleJobletForResource(org.python.core.PyString resourceId, org.python.core.PyType jobletClass, org.python.core.PyDictionary params) Utility to schedule joblet to run on a specified resource.
void	scheduleJobletForVmHost(org.python.core.PyString vmHostId, org.python.core.PyType jobletClass, org.python.core.PyDictionary params) Utility to schedule joblet to run on a VmHost's physical resource.
void	scheduleSweep(org.python.core.PyType jobletClass) Schedule as many joblets as there are matching resources using the job's resource constraints.
void	scheduleSweep(org.python.core.PyType jobletClass, org.python.core.PyDictionary params) Schedule as many joblets as there are matching resources using the job's resource constraints.
void	scheduleSweep(ScheduleSpec spec) Schedule as many joblets as there are matching resources after applying any constraint from the ScheduleSpec to constrain the available joblets.
void	sendClientEvent(java.lang.String name, org.python.core.PyDictionary params) Send an event to the client.
void	sendEvent(java.lang.String name, org.python.core.PyDictionary params) Send an event to the parent job.
void	sendEvent(java.lang.String destJobID, java.lang.String name, org.python.core.PyDictionary params) Send an event to another job.
void	sendJobletEvent(int jobletNumber, java.lang.String name, org.python.core.PyDictionary params) Send an event from server to Joblet execution on a resource.
void	stopJavaTimerThread()
void	subscribeToEvent(java.lang.String event, org.python.core.PyMethod method) Subscribe to be notified of a Platespin Orchestrate Event
void	terminate() Terminate this job instance.
void	unsubscribeFromEvent(java.lang.String event, org.python.core.PyMethod method) Unsubscribe from Platespin Orchestrate Event notifications

Methods inherited from class com.novell.zos.jdl.GridObjectInfo

deleteFact, factExists, getFact, getFact, getFactLastModified, getFactNames, refresh, setArrayFact, setBooleanArrayFact, setDateArrayFact, setDateFact, setFact, setIntegerArrayFact, setRealArrayFact, setStringArrayFact, setTimeArrayFact, setTimeFact

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SUBMITTED_STATE

public static final int SUBMITTED_STATE

Submitted. This is the intial state. Transitions to: Queued/Failing

See Also:

Constant Field Values

QUEUED_STATE

public static final int QUEUED_STATE

Queued. Transitions to: Starting/Failing/Cancelling

See Also:

Constant Field Values

STARTING_STATE

public static final int STARTING_STATE

Starting. Transistions to: Running/Failing/Cancelling

See Also:

Constant Field Values

RUNNING_STATE

public static final int RUNNING_STATE

Running. Transistions to: Paused/Completing/Failing/Cancelling

See Also:

Constant Field Values

PAUSED_STATE

public static final int PAUSED_STATE

Paused. Transitions to: Running/Completing/Failing/Cancelling

See Also:

Constant Field Values

COMPLETING_STATE

public static final int COMPLETING_STATE

Completing. Transitions to: Completing

See Also:

Constant Field Values

CANCELLING_STATE

public static final int CANCELLING_STATE

Cancelling. Transistions to: Cancelled

See Also:

Constant Field Values

FAILING_STATE

public static final int FAILING_STATE

Failing. Transitions to: Failed

See Also:

Constant Field Values

COMPLETED_STATE

public static final int COMPLETED_STATE

Completed end state.

See Also:

Constant Field Values

CANCELLED_STATE

public static final int CANCELLED_STATE

Cancelled end state.

See Also:

Constant Field Values

FAILED_STATE

public static final int FAILED_STATE

Failed end state.

See Also:

Constant Field Values

TERMINATION_TYPE_USER

public static final java.lang.String TERMINATION_TYPE_USER

Indicate Job was cancelled by client user. (Only applies if Job is in CANCELLED_STATE) Value is obtained from jobinstance.terminationtype fact

See Also:

Constant Field Values

TERMINATION_TYPE_ADMIN

public static final java.lang.String TERMINATION_TYPE_ADMIN

Indicate Job was cancelled by admin. (Only applies if Job is in CANCELLED_STATE) Value is obtained from jobinstance.terminationtype fact

See Also:

Constant Field Values

TERMINATION_TYPE_JOB

public static final java.lang.String TERMINATION_TYPE_JOB

Indicate Job was cancelled by a Job function. (Only applies if Job is in CANCELLED_STATE) Value is obtained from jobinstance.terminationtype fact

See Also:

Constant Field Values

TERMINATION_TYPE_TIMEOUT

public static final java.lang.String TERMINATION_TYPE_TIMEOUT

Indicate Job was cancelled due to exceeding the job timeout value. (Only applies if Job is in CANCELLED_STATE) Value is obtained from jobinstance.terminationtype fact

See Also:

Constant Field Values

Method Detail

stopJavaTimerThread

public void stopJavaTimerThread()

isProvisionJob

public boolean isProvisionJob()

scheduleSweep

public void scheduleSweep(org.python.core.PyType jobletClass)

Schedule as many joblets as there are matching resources using the job's resource constraints. Each created joblet will be preassigned to run on only the specified resource.

Note that joblets created with scheduleSweep() will take precedence over regularly scheduled joblets and will prevent regular joblets from running until all preassigned ones are complete. For this reason it is not normally recommended to mix schedule() and scheduleSweep in the same job.

Parameters:

jobletClass - Reference to Joblet class to execute on node

scheduleSweep

public void scheduleSweep(org.python.core.PyType jobletClass,
                          org.python.core.PyDictionary params)

Schedule as many joblets as there are matching resources using the job's resource constraints. Each created joblet will be preassigned to run on only the specified resource.

Note that joblets created with scheduleSweep() will take precedence over regularly scheduled joblets and will prevent regular joblets from running until all preassigned ones are complete. For this reason it is not normally recommended to mix schedule() and scheduleSweep in the same job.

Parameters:

jobletClass - Reference to Joblet class to execute on node

params - dictionary of facts to store in joblet

scheduleSweep

public void scheduleSweep(ScheduleSpec spec)

Schedule as many joblets as there are matching resources after applying any constraint from the ScheduleSpec to constrain the available joblets. Each created joblet will be preassigned to run only on the specified resource.

Note that joblets created with scheduleSweep() will take precedence over regularly scheduled joblets and will prevent regular joblets from running until all preassigned ones are complete. For this reason it is not normally recommended to mix schedule() and scheduleSweep in the same job.

Parameters:

spec - ScheduleSpec to use for scheduling joblets

schedule

public void schedule(org.python.core.PyType jobletClass)

Schedule a single joblet.

Parameters:

jobletClass - Reference to Joblet class to execute on node

schedule

public void schedule(org.python.core.PyType jobletClass,
                     int jobletCount)

Schedule one or more joblets.

Parameters:

jobletClass - Reference to Joblet class to execute on node

jobletCount - Number of joblets to create

schedule

public void schedule(org.python.core.PyType jobletClass,
                     org.python.core.PyDictionary params)

Schedule a single joblet with additional joblet facts.

Parameters:

jobletClass - Reference to Joblet class to execute on node

params - dictionary of facts to store in joblet

schedule

public void schedule(org.python.core.PyType jobletClass,
                     org.python.core.PyDictionary params,
                     int jobletCount)

Schedule one or more joblets with additional joblet facts.

Parameters:

jobletClass - Reference to Joblet class to execute on node

params - dictionary of facts to store in joblet

jobletCount - Number of joblets to create

schedule

public void schedule(org.python.core.PyType jobletClass,
                     ParameterSpace parameterSpace,
                     org.python.core.PyDictionary params)

Schedule a set of joblets using the passed ParameterSpace as the basis for joblet assignment.

Parameters:

jobletClass - Reference to Joblet class to execute on node

parameterSpace - ParameterSpace object instance

params - dictionary of facts to store in joblet

schedule

public void schedule(org.python.core.PyType jobletClass,
                     ParameterSpace parameterSpace,
                     org.python.core.PyDictionary params,
                     int jobletCount)

Schedule a set of joblets using the passed ParameterSpace as the basis for joblet assignment.

Parameters:

jobletClass - Reference to Joblet class to execute on node

parameterSpace - ParameterSpace object instance

params - dictionary of facts to store in joblet

jobletCount - Maximum number of joblets to break up ParameterSpace A count of 1 means to only create 1 joblet. This may override ParameterSpace defined joblet breakup.

schedule

public void schedule(org.python.core.PyType jobletClass,
                     ParameterSpace parameterSpace,
                     org.python.core.PyDictionary params,
                     int jobletCount,
                     org.python.core.PyMethod allocate)

Schedule a set of joblets using the passed ParameterSpace as the basis for joblet assignment.

Parameters:

jobletClass - Reference to Joblet class to execute on node

parameterSpace - ParameterSpace object instance

params - dictionary of facts to store in joblet

jobletCount - Maximum number of joblets to break up ParameterSpace

allocate - Reference to function to execute for choosing nodes (optional)

schedule

public void schedule(ScheduleSpec spec)

Schedule a set of joblets using the passed ScheduleSpec.

Parameters:

spec - ScheduleSpec instance defining Joblets to schedule

scheduleJobletForVmHost

public void scheduleJobletForVmHost(org.python.core.PyString vmHostId,
                                    org.python.core.PyType jobletClass,
                                    org.python.core.PyDictionary params)

Utility to schedule joblet to run on a VmHost's physical resource. Job fails if host does not exist or physical resource is not online (enabled)

Parameters:

vmHostId - the string vmhost id

jobletClass - the jdl class for the joblet

params - the params PyDictionary to pass to the joblet

scheduleJobletForResource

public void scheduleJobletForResource(org.python.core.PyString resourceId,
                                      org.python.core.PyType jobletClass,
                                      org.python.core.PyDictionary params)

Utility to schedule joblet to run on a specified resource. Job fails if host does not exist or physical resource is not online (enabled)

Parameters:

resourceId - the string resource id

jobletClass - the jdl class for the joblet

params - the params PyDictionary to pass to the joblet

runJob

public org.python.core.PyObject runJob(java.lang.String job)

Run a new child job.

Parameters:

job - Name of job to run

Returns:

Job instance of new child job

Throws:

JdlException - if child job is not deployed

runJob

public org.python.core.PyObject runJob(java.lang.String job,
                                       org.python.core.PyDictionary params)

Run a new child job with supplied job arguments.

Example to run the sample job with two arguments:

      self.runJob('quickie',{"numJoblets":2,"sleeptime":5})
 

Parameters:

job - Name of job to run

params - Dictionary of job arguments

Returns:

Job instance of new child job

Throws:

JdlException - if child job is not deployed or job arguments are not of the correct type

runJob

public org.python.core.PyObject runJob(java.lang.String job,
                                       org.python.core.PyDictionary params,
                                       java.lang.String policy)

Run a new child job using supplied policy text. The supplied policy text is aggregated with the child Job's policies.

Parameters:

job - Name of job to run

params - Dictionary of job arguments

policy - Policy text

Returns:

Job instance of new child job

Throws:

JdlException - if child job is not deployed or job arguments are not of the correct type

runJob

public org.python.core.PyObject runJob(java.lang.String job,
                                       org.python.core.PyDictionary params,
                                       Constraint constraint)

Run a new child job using supplied resource Constraint. The supplied constraint is aggregated with the child Job's resource constraints.

Example to run the "osInfo" job as a child job with a supplied constraint that matches on a specific OS family:

          eq = EqConstraint()
          eq.setFact("resource.os.family")
          eq.setValue("windows")
          self.runJob("osInfo",{},eq) 

The supplied constraint is AND'd to the job's existing constraints.

Parameters:

job - Name of job to run

params - Dictionary of job arguments

constraint - Constraint object

Returns:

Job instance of new child job

Throws:

JdlException - if child job is not deployed or job arguments are not of the correct type

runJob

public org.python.core.PyObject runJob(RunJobSpec runJobSpec)

Run a new child or stand-alone job using attributes defined in the supplied RunJobSpec.

Parameters:

runJobSpec - RunJobSpec instance with attributes for starting child job

Returns:

Job instance of new child job

Throws:

JdlException - if child job is not deployed or job arguments are not of the correct type

sendEvent

public void sendEvent(java.lang.String name,
                      org.python.core.PyDictionary params)

Send an event to the parent job.

Parameters:

name - Name of event

params - Dictionary of parameters to send to destination

sendEvent

public void sendEvent(java.lang.String destJobID,
                      java.lang.String name,
                      org.python.core.PyDictionary params)

Send an event to another job.

This is typically used to communicate to a child job.

Parameters:

destJobID - Job Instance ID of job to send event to

name - Name of event

params - Dictionary of parameters to send to destination

sendClientEvent

public void sendClientEvent(java.lang.String name,
                            org.python.core.PyDictionary params)

Send an event to the client.

This allows communication from the Job running on the server to a client that is listening to Job events using the Client Toolkit.

Example to send an event to a client with a payload consisting of integer and a string:

      self.sendClientEvent("client_event",{ "param1": 1024, "param2":"hello world" })
 

Parameters:

name - Name of event

params - Dictionary of parameters to send to destination.

sendJobletEvent

public void sendJobletEvent(int jobletNumber,
                            java.lang.String name,
                            org.python.core.PyDictionary params)

Send an event from server to Joblet execution on a resource.

Joblet must be running on a resource or this event is ignored. Typically used to communicate state changes to a long running Joblet.

Parameters:

jobletNumber - Number of joblet to send event to. Joblet must be contracted on node.

name - name of event

params - dictionary of parameters to send to destination

Throws:

org.python.core.PyException - if joblet does not exist or is not contracted

cancel

public void cancel()

Cancel this job instance.

cancel

public void cancel(java.lang.String reason)

Cancel this job instance with a reason.

Parameters:

reason - message to put in job log

fail

public void fail()

Fail this job instance.

fail

public void fail(java.lang.String reason)

Fail this job instance with a reason.

Parameters:

reason - Reason message to put in job log

pause

public void pause()

Pause this job instance.

resume

public void resume()

Resume this job instance if it is currently paused.

terminate

public void terminate()

Terminate this job instance.

Typically used when the fact job.autoterminate has been set to False.

Note: This does not immediately terminate the calling JDL thread; instead, it sends a message to the server requesting termination of the job. This can take a while to happen (since subjobs need to be recursively terminated, and joblets cancelled). Therefore, if it is required for the calling JDL thread to terminate immediately, the invocation of this method should be immediately followed by a return.

getChildJobs

public org.python.core.PyList getChildJobs()

Retrieve a list of child jobs submitted by this job. The elements are instance of Job.

Returns:

Python list of child jobs

cancelAllJoblets

public void cancelAllJoblets()

Cancel all joblets for this job instance.

Any joblets that are running or waiting are cancelled. If the job is set to autoterminate, then the job will terminate normally.

cancelAllTimers

public void cancelAllTimers()

Cancel all timers for this job instance.

Any running Timer instances are cancelled. A running Timer will keep the job instance in a Running state.

changePriority

public void changePriority(java.lang.String priority)

Change priority of this job.

Parameters:

priority - String priority name

job_started_event

public void job_started_event()

job_started_event is the first event to be called when a job is started. A Job writer is required to implement this event. This event is not fired until a job instance has transitioned out of the queued state. After this event has completed, the job instance is in the running state. Job setup or scheduling of Joblets is typically implemented in this event.

job_cancelled_event

public void job_cancelled_event()

job_cancelled_event is fired when a job is transitioning to the cancelled state. A Job writer can optionally implement this event to handle job cleanup.

job_paused_event

public void job_paused_event()

Fired when a job is paused by user or administrator. A Job writer can optionally implement this event to handle state changes.

job_completed_event

public void job_completed_event()

job_completed_event is fired when the job is transitioning to the completed state. A Job writer can optionally implement this event to handle any job cleanup.

job_failed_event

public void job_failed_event()

job_failed_event is fired when the job is transitioning to the failed state. A Job writer can optionally implement this event to handle any job cleanup.

job_resumed_event

public void job_resumed_event()

Fired when a previously paused job is resumed. A Job writer can optionally implement this event to handle state changes.

child_job_started_event

public void child_job_started_event(Job job)

child_job_started_event is fired when a child job has transitioned to the running state. A Job writer can optionally implement this event to handle job state transitions.

Parameters:

job - Child Job instance that is running

child_job_completed_event

public void child_job_completed_event(Job job)

child_job_completed_event is fired when a child job has transitioned to the completed state. A Job writer can optionally implement this event to handle any job cleanup.

Parameters:

job - Child Job instance that has completed

child_job_failed_event

public void child_job_failed_event(Job job)

child_job_failed_event is fired when a child job has transitioned to the failed state. A Job writer can optionally implement this event to handle any job cleanup.

Parameters:

job - Child Job instance that has failed

child_job_cancelled_event

public void child_job_cancelled_event(Job job)

child_job_cancelled_event is fired when a child job has transitioned to the cancelled state. A Job writer can optionally implement this event to handle job cleanup.

Parameters:

job - Child Job instance that has cancelled

joblet_started_event

public void joblet_started_event(int jobletNumber,
                                 java.lang.String resourceId)

joblet_started_event is fired when the Joblet has started execution on a resource. A Job writer can optionally implement this event to handle a joblet state change.

Parameters:

jobletNumber - Joblet number that has started (0 based)

resourceId - Id of resource where joblet was started on.

joblet_cancelled_event

public void joblet_cancelled_event(int jobletNumber,
                                   java.lang.String resourceId,
                                   java.lang.String reason)

joblet_cancelled_event is fired when the Joblet has had execution cancelled. The Joblet may or may not have been running. A Job writer can optionally implement this event to handle a joblet state change. Note that if the job has ended, this event will not be called.

Parameters:

jobletNumber - Joblet number that has been cancelled (0 based)

resourceId - ID of resource where joblet was cancelled. Can be None if was not running

reason - Reason message for the joblet error. Maybe empty

joblet_completed_event

public void joblet_completed_event(int jobletNumber,
                                   java.lang.String resourceId)

joblet_completed_event is fired when the Joblet has completed execution on a resource. A Job writer can optionally implement this event to handle a joblet state change. Note that if the job has ended, this event will not be called.

Parameters:

jobletNumber - Joblet number that has completed (0 based)

resourceId - ID of resource where joblet ran to completion

joblet_failed_event

public void joblet_failed_event(int jobletNumber,
                                java.lang.String resourceId,
                                java.lang.String errorMsg)

joblet_failed_event is fired when the Joblet has failed execution on a resource. A Job writer can optionally implement this event to handle a joblet state change. Note that if the job has ended, this event will not be called.

Parameters:

jobletNumber - Joblet number that has failed

resourceId - ID of resource where joblet ran

errorMsg - Error message for the joblet error

joblet_retry_event

public void joblet_retry_event(int jobletNumber,
                               java.lang.String resourceId,
                               java.lang.String errorMsg)

joblet_retry_event is fired when the Joblet is transitioning back to a waiting state after a failed execution on a resource. This event will not fire if the maximum retry settings have been met and Joblet transitions to the failed state. A Job writer can optionally implement this event to handle a joblet state change.

Parameters:

jobletNumber - Joblet number that is to be retried

resourceId - ID of resource where joblet ran

errorMsg - Error message for the joblet error

getJoblet

public Joblet getJoblet(int jobletNumber)

Retrieve a scheduled Joblet. Joblet may not be running on a resource. The Joblet factset is available using the base GridObjectInfo methods. Retrieve the state facts to determine the state of the Joblet.

Parameters:

jobletNumber - Number of joblet

Returns:

Joblet instance

Throws:

java.lang.Exception - if Joblet number refers to a Joblet that has not yet been created

provisioner_completed_event

public void provisioner_completed_event(org.python.core.PyDictionary params)

provisioner_completed_event is fired when the provision operation submitted by this job has completed.

A Job writer can optionally implement this event to handle any job response to provision completion.

Example of a handler for the completion of suspending a resource

       def provisioner_completed_event(params):
           if params["action"] == "Suspend":
              print "Successfully suspended resource '%s'" % (params["resource"])
 

params argument is a Dictionary containing various attributes including "action" and "provisionjob" keys.

Valid "action" strings include:

   "Provision"
   "Clone"
   "Move"
   "Shutdown"
   "Restart"
   "Destroy"
   "Suspend"
   "Pause"
   "Resume"
   "Personalize"
   "Save Config"
   "Apply Config"
   "Create Template"
   "Migrate"
   "Checkpoint"
   "Restore"
   "Install Agent"
   "Make Standalone"
   "Check Status"
   "Delete"
   "Cancel Action"
   "Build"
   "Rediscover"
 Additional Params include "resource" key.

   "Discover All"
 No additional Params keys.

   "Discover VmHost"
 Additional Params include "host" key.

   "Discover Repository"
 Additional Params include "repository" key.
 

The "provisionjob" key contains the Job Id of the provisioning adapter job that was run.
The "resource" key contains the Resource Id of the resource the action was acted on.
The "host" key contains the VmHost Id of the host on which VM discovery took place.
The "repository" key contains the Repository Id of the repository on which VM discovery took place.

Parameters:

params - Dictionary containing "action", "provisionjob" and other action specific keys

provisioner_failed_event

public void provisioner_failed_event(org.python.core.PyDictionary params)

provisioner_failed_event is fired when the provision operation submitted by this job has failed.

A Job writer can optionally implement this event to handle any job response to provision failure.
An optional "error" key may be passed as a param indicating the failure. More information may also be available by looking up the provisioning job.

Parameters:

params - Dictionary containing "action", "resource", "provisionjob" and other action specific keys.

provisioner_cancelled_event

public void provisioner_cancelled_event(org.python.core.PyDictionary params)

provisioner_cancelled_event is fired when the provision operation submitted by this job has been cancelled.

A Job writer can optionally implement this event to handle any job response to provision cancellation.

Parameters:

params - Dictionary containing "action", "resource", "provisionjob" and other action specific keys

subscribeToEvent

public void subscribeToEvent(java.lang.String event,
                             org.python.core.PyMethod method)

Subscribe to be notified of a Platespin Orchestrate Event

Example of a job subscribing to an event:

  class EventDaemon(Job):
    def job_started_event(self):
       self.setFact("job.autoterminate",False)
       self.subscribeToEvent("vmhost",self.eventHandler)
       
    def eventHandler(self,context):
       print "Context:"
       keys = context.keys()
       keys.sort()
       for k in keys:
          v = context[k] 
          print "  key(%s) type(%s) value(%s)" % (k,type(v),str(v))
  

In the above example, the job subscribes to an event named "vmhost". The Job method eventHandler() will be invoked upon the event notification. This job will continue running until the job is canceled or an error occurs.

Parameters:

event - Event Name to subscribe to

method - Method in this Job subclass

unsubscribeFromEvent

public void unsubscribeFromEvent(java.lang.String event,
                                 org.python.core.PyMethod method)

Unsubscribe from Platespin Orchestrate Event notifications

Example of unsubscribing from same event example used in subscribeToEvent():

     self.unsubscribeFromEvent("vmhost",self.eventHandler)
 

Parameters:

event - Event Name to unsubscribe from

method - Method in this Job subclass that was used in subscribing.

getMatchingResources

public java.lang.Object getMatchingResources()

Retrieve a List of matching resources for this Job instance.
This will return the same matching result set used by schedule(). So only online resources that match this job instance's constraints will be returned.
If you want to run a custom Constraint search for Grid Objects, use the getMatrix().getGridObjects() methods.

Returns:

List of resource names that match the constraint. List can be empty if no matching resources are available.

getMatchingResources

public java.lang.Object getMatchingResources(ScheduleSpec scheduleSpec)

Retrieve a List of matching resources for this Job instance using the supplied ScheduleSpec.
This will return the same matching result set used by schedule() if it were called with the same ScheduleSpec instance. So only resources that match this job instance's constraints and any specified in the supplied ScheduleSpec will be returned.
If you want to run a custom Constraint search for Grid Objects, use the getMatrix().getGridObjects() methods.

Parameters:

scheduleSpec - ScheduleSpec instance defining optional additional constraint

Returns:

List of resource names that match the constraint. List can be empty if no matching resources are available.

saveStateValue

public org.python.core.PyDictionary saveStateValue(org.python.core.PyString name,
                                                   org.python.core.PyObject value,
                                                   org.python.core.PyList targetEvents,
                                                   org.python.core.PyDictionary matchDict)

Save a job value for use by a future invocation of a Provisioning Adapter pre or post hook job and/or joblet

Parameters:

name - Relative name of the saved value.

value - The value to save (can be any Py type including PyDictionary)

targetEvents - A PyList containing names of events which should receive the saved value

matchDict - A PyDictionary containing key/value pairs which must match the values found in the params dictionary passed to the specified event. Non-matching event calls will not receive the saved value.

saveStateValue

public org.python.core.PyDictionary saveStateValue(org.python.core.PyString name,
                                                   org.python.core.PyObject value,
                                                   org.python.core.PyList targetEvents,
                                                   org.python.core.PyList matchNames,
                                                   org.python.core.PyDictionary matchDict)

Save a job value for use by a future invocation of a Provisioning Adapter pre or post hook job and/or joblet

Parameters:

name - Relative name of the saved value.

value - The value to save (can be any Py type including PyDictionary)

targetEvents - A PyList containing names of events which should receive the saved value

matchNames - A PyList containing only those keys from matchDict that should be considered in matching params values. This allows matchDict to contain additional non-state-related key/value pairs.

matchDict - A PyDictionary containing key/value pairs which must match the values found in the params dictionary passed to the specified event. Non-matching event calls do not receive the saved value.