com.novell.zos.jdl
Class Joblet

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

Direct Known Subclasses:

ProvisionJoblet

public class Joblet
extends GridObjectInfo

The Joblet class defines execution on the resource. A Job writer constructs a subclass of Joblet to define code to run on a resource. The method joblet_started_event is required to be implemented. joblet_started_event is invoked on the resource.

The Job writer invokes the schedule() function in the Job subclass to define when and which resource the Joblet is executed.

Each Joblet instance has the Job instance (jobinstance.*,job.*,jobargs.*,user.*), Resource (resource.*) and Joblet (joblet.*,jobletargs.*) fact sets available using the base GridObjectInfo fact functions. For example, you can use self.getFact() to retrieve a Joblet fact. Use the getMatrix() built-in function to retrieve facts for other Grid Objects that are not in the context of this Joblet instance's fact set.

Defined Joblet Facts:

      joblet.id               Unique identifier for this joblet
      joblet.instancename     A human readable name for this joblet instance.
      joblet.memo             An (optional) memo field for this joblet that can be displayed in the management console.
      joblet.number           The joblet number (0 is the first Joblet).
      joblet.retrynumber      The number of retries for this joblet (0 on first attempt).
      joblet.timeout          The time after which this joblet will be cancelled/retried (seconds, defaults to job.joblet.timeout).
      joblet.preemptible      Indicates whether this joblet is willing or able to be preempted.
      joblet.autoterminate    Whether the joblet ends when all events for the joblet ends.
      joblet.state            The numeric state of this joblet instance.
      joblet.state.string     String representation of the current state of this joblet instance.
      joblet.errors           The List of Error Dictionaries encapsulating the error history for this joblet. Dictionary keys: 'ts' timestamp in milliseconds, 'node' the node name where execution failed, 'error' the error message. *
      joblet.history          The List of resource IDs where Joblet ran on. 
 

Interaction with the Job and a SDK client is accomplished using event methods on the Joblet class such as self.sendEvent() and self.sendClientEvent().
If a ParameterSpace has been defined for this Joblet, the self.getParamterSpace() method retrieves the Joblet's JobletParameterSpace.

Example of a Joblet that runs a command line and forces a Joblet failure if the command line returns an exit code greater than zero:

      class MyJoblet(Joblet):
          def joblet_started_event(self):
              e = Exec()
              e.setCommand("ls -la")
              rslt = e.execute()
              if rslt > 0:
                 self.fail("ls command failed")
 

In the above example, the Joblet may be retried on another resource depending on the value of the fact job.joblet.maxfailures and how many times the Joblet has already been retried.

Field Summary

static int	CANCELLED_STATE Joblet cancelled end state.
static int	CANCELLING_STATE Joblet cancelling.
static int	COMPLETED_STATE Joblet completed end state.
static int	COMPLETING_STATE Joblet completing state.
static int	CONTRACTED_STATE Joblet contracted to a resource.
static int	FAILED_STATE Joblet failed end state.
static int	FAILING_STATE Joblet failing state.
static int	INITIAL_STATE Joblet initial state.
static int	POST_CANCEL_STATE Joblet finishing cancellation.
static int	PRE_CANCEL_STATE Joblet starting cancellation.
static int	STARTED_STATE Joblet started on a resource.
static int	WAITING_RETRY_STATE Joblet waiting for a resource for retry.
static int	WAITING_STATE Joblet waiting for a resource.

Method Summary

void	cancel() Cancel this joblet if it is waiting or running.
void	cancel(java.lang.String reason) Cancel this joblet if it is running.
void	cancelAllTimers() Cancel all timers for this joblet instance.
void	fail() Fail a running joblet to force failover to another resource.
void	fail(java.lang.String reason) Fail a running joblet to force failover to another resource.
java.lang.String	getcwd() Retrieve the path of the current working directory in which this Joblet is running.
JobletParameterSpace	getParameterSpace() Retrieve the JobletParameterSpace defined for this Joblet instance.
boolean	isValidUser(java.lang.String username) Test if a supplied username is valid on a resource.
void	joblet_cancelled_event() The joblet_cancelled_event is fired when Joblet execution has been interrupted.
void	joblet_failed_event() The joblet_failed_event is fired when Joblet execution has failed either by code, runtime errors or by the self.fail() function.
void	joblet_pre_cancel_event() The joblet_pre_cancel_event is fired when Joblet execution is about to be interrupted.
void	joblet_started_event() joblet_started_event is fired when Joblet execution is started on a resource.
void	retry() Retry this joblet elsewhere if it is running.
void	retry(java.lang.String reason) Retry this joblet if it is running.
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 joblet 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 joblet value for use by a future invocation of a Provisioning Adapter pre or post hook job and/or joblet
void	sendClientEvent(java.lang.String name, org.python.core.PyDictionary params) Send an event to a client.
void	sendEvent(java.lang.String name, org.python.core.PyDictionary params) Send an event to the Job that scheduled this Joblet.
void	sendEvent(java.lang.String jobID, java.lang.String name, org.python.core.PyDictionary params) Send an event to the supplied Job instance.
void	sendJobletEvent(int jobletNumber, java.lang.String name, org.python.core.PyDictionary params) Send an event to Joblet execution on a resource.
void	stopJavaTimerThread()
void	terminate() Terminate a joblet that is running.

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

INITIAL_STATE

public static final int INITIAL_STATE

Joblet initial state.

See Also:

Constant Field Values

WAITING_STATE

public static final int WAITING_STATE

Joblet waiting for a resource.

See Also:

Constant Field Values

WAITING_RETRY_STATE

public static final int WAITING_RETRY_STATE

Joblet waiting for a resource for retry.

See Also:

Constant Field Values

CONTRACTED_STATE

public static final int CONTRACTED_STATE

Joblet contracted to a resource.

See Also:

Constant Field Values

STARTED_STATE

public static final int STARTED_STATE

Joblet started on a resource.

See Also:

Constant Field Values

PRE_CANCEL_STATE

public static final int PRE_CANCEL_STATE

Joblet starting cancellation.

See Also:

Constant Field Values

CANCELLING_STATE

public static final int CANCELLING_STATE

Joblet cancelling.

See Also:

Constant Field Values

POST_CANCEL_STATE

public static final int POST_CANCEL_STATE

Joblet finishing cancellation.

See Also:

Constant Field Values

COMPLETING_STATE

public static final int COMPLETING_STATE

Joblet completing state.

See Also:

Constant Field Values

FAILING_STATE

public static final int FAILING_STATE

Joblet failing state.

See Also:

Constant Field Values

FAILED_STATE

public static final int FAILED_STATE

Joblet failed end state.

See Also:

Constant Field Values

CANCELLED_STATE

public static final int CANCELLED_STATE

Joblet cancelled end state.

See Also:

Constant Field Values

COMPLETED_STATE

public static final int COMPLETED_STATE

Joblet completed end state.

See Also:

Constant Field Values

Method Detail

cancelAllTimers

public void cancelAllTimers()

Cancel all timers for this joblet instance.

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

stopJavaTimerThread

public void stopJavaTimerThread()

getcwd

public java.lang.String getcwd()

Retrieve the path of the current working directory in which this Joblet is running.
The directory is only applicable during this Joblet's execution. Depending on the configuration of the agent, the directory can be removed after Joblet execution.
The returned path String does not end with a trailing path separator.

Returns:

Path of Joblet's current working directory

joblet_started_event

public void joblet_started_event()

joblet_started_event is fired when Joblet execution is started on a resource. The Job writer is required to implement this function.

joblet_pre_cancel_event

public void joblet_pre_cancel_event()

The joblet_pre_cancel_event is fired when Joblet execution is about to be interrupted.
The Job writer can optionally implement this function to handle special preprocessing before cancellation such as sending a signal to a running process.

Example to send a signal to a running process before joblet is cancelled:

 class MyJoblet(Joblet):
      def joblet_started_event(self):
          self.exec = Exec()
          self.exec.setCommand("sleep 100")
          self.exec.execute()

      def joblet_pre_cancel_event(self):
          self.exec.signal("SIGABRT")
 

joblet_cancelled_event

public void joblet_cancelled_event()

The joblet_cancelled_event is fired when Joblet execution has been interrupted.
The Job writer can optionally implement this function to handle special postprocessing such as deleting temporary files.

Example to delete a temporary file when a Joblet is cancelled:

 class MyJoblet(Joblet):
      def joblet_started_event(self):
          self.tempfn = "/tmp/foo"
          self.exec = Exec()
          self.exec.setStdoutFile(self.tempfn)
          self.exec.setCommand("sleep 100")
          self.exec.execute()

      def joblet_cancelled_event(self):
          if os.path.exists(self.tempfn):
             os.remove(self.tempfn)

 

joblet_failed_event

public void joblet_failed_event()

The joblet_failed_event is fired when Joblet execution has failed either by code, runtime errors or by the self.fail() function. The Job writer can optionally implement this function to handle special postprocessing such as cleanup of a running process.

Example to send a signal to a running process before the Joblet is ended:

 class MyJoblet(Joblet):
      def joblet_started_event(self):
          self.exec = Exec()
          self.exec.setCommand("sleep 100")
          self.exec.execute()

      def joblet_failed_event(self):
          self.exec.signal("SIGABRT")

 

sendEvent

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

Send an event to the Job that scheduled this Joblet.

Example to send an event with the parameters dictionary containing two elements:

      self.sendEvent("custom_event", { "arg1":1,"arg2":"foo" } )
 

Parameters:

name - Name of event

params - Dictionary of event parameters

sendEvent

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

Send an event to the supplied Job instance. Use this method for sending events to a Job different from the Job that scheduled this Joblet.

Parameters:

jobID - ID of job to send event to

name - Name of event

params - Dictionary of event parameters

sendClientEvent

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

Send an event to a client.
The sends an event directly to a client application listening for events using the Client SDK.

Parameters:

name - Name of event

params - Dictionary of event parameters

sendJobletEvent

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

Send an event 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

terminate

public void terminate()

Terminate a joblet that is running.
This Joblet will end execution upon exit of the last running Joblet event. This method is necessary to end the joblet execution if the fact joblet.autoterminate is True.

getParameterSpace

public JobletParameterSpace getParameterSpace()

Retrieve the JobletParameterSpace defined for this Joblet instance.

Returns:

JobletParameterSpace for this Joblet. None if no ParameterSpace is defined

cancel

public void cancel()

Cancel this joblet if it is waiting or running. Has no effect if joblet is finished.

cancel

public void cancel(java.lang.String reason)

Cancel this joblet if it is running.
Has no effect if joblet is finished.

Parameters:

reason - string to store in job log

fail

public void fail()

Fail a running joblet to force failover to another resource.
If joblet has reached retry limit, then joblet ends in failed state. Has no effect if joblet is finished.

fail

public void fail(java.lang.String reason)

Fail a running joblet to force failover to another resource.
If joblet has reached retry limit, then joblet ends in failed state. Has no effect if joblet is finished.

Parameters:

reason - string to store in job log

retry

public void retry()

Retry this joblet elsewhere if it is running.
Has no effect if joblet is finished.

retry

public void retry(java.lang.String reason)

Retry this joblet if it is running.
Has no effect if joblet is finished.

Parameters:

reason - string to store in job log

isValidUser

public boolean isValidUser(java.lang.String username)

Test if a supplied username is valid on a resource.
If True is returned, then the username can run operations as that user on the resource. This includes running execs (assuming any required credentials are supplied) and running file operations on the resource. If enhanced exec is not installed on the resource, this returns False.

Parameters:

username - Name of user to test

Returns:

True if user is valid on this resource, False if not

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