com.novell.zos.jdl
Class Job

java.lang.Object
  extended by com.novell.zos.jdl.GridObjectInfo
      extended by 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.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.
 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.
 void schedule(org.python.core.PyClass jobletClass)
          Schedule a single joblet.
 void schedule(org.python.core.PyClass jobletClass, int jobletCount)
          Schedule one or more joblets.
 void schedule(org.python.core.PyClass 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.PyClass 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.PyClass 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.PyClass jobletClass, org.python.core.PyDictionary params)
          Schedule a single joblet with additional joblet facts.
 void schedule(org.python.core.PyClass 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 scheduleSweep(org.python.core.PyClass jobletClass)
          Schedule as many joblets as there are matching resources using the job's resource constraints.
 void scheduleSweep(org.python.core.PyClass 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 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, 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

scheduleSweep

public void scheduleSweep(org.python.core.PyClass 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.PyClass 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.PyClass jobletClass)
Schedule a single joblet.

Parameters:
jobletClass - Reference to Joblet class to execute on node

schedule

public void schedule(org.python.core.PyClass 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.PyClass 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.PyClass 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.PyClass 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.PyClass 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.PyClass 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

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.


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"
 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.


Copyright (c) 2009 Novell, Inc. All rights reserved.