---

sosc::JobTool Class Reference

List of all members.

Public Methods
	JobTool (DbTool dbTool)
void	addJob (String queue, String description, String type, String className, Map args) throws Exception
Job	runJob (String queue, Map args2) throws Exception
void	log (int jobId, String text) throws Exception
Static Public Methods
synchronized JobTool	initialize (DbTool dbTool) throws Exception
synchronized JobTool	getInstance () throws Exception
Public Attributes
final String	JOB_TABLE = "jobToolJobs"
final String	JOB_ARGUMENTS = "jobToolArguments"
final String	JOB_LOG = "jobToolLog"
Private Attributes
DbTool	db = null
ArrayList	jobs = new ArrayList()
Static Private Attributes
JobTool	jobTool = null
boolean	ready = false

---

Detailed Description

This is a simple Job control implementation that allows arbitrary job creation, execution, queueing with concurrency options for running multiple Threads.

The general pattern calls for JobTool to have a singleton instance that controls synchronization. In the backend the job definitions are stored in an SQL database, though that fact is subject to change and should not be relied upon by JobTool clients.

The original motivation for JobTool is to provide a simple "workqueue" pattern that allows an arbitrary number of jobs to be executed by a finite number of resources in a parallel fashion. JobTool provides the resource and Thread management functions.

Multiple job queues are supported.

JobTool requires a few SQL tables. You'll need to create them and assign an appropriate value to JOB_TABLE.

create table jobToolJobs (

	-- Unique job identifier
	id int primary key identity not null,

	-- Queue that this job belongs to.
	queue varchar(100) not null,

	-- Adhoc description of Job
	description varchar(100) null,

	-- 0: Starting state; job is queued
	-- 1: Job is running
	-- 2: Job finished (regardless of "result" of job)
	state int default 0, -- 0 queued; 1 running; 2 finished

	-- Time the job was created at
	created datetime default getdate() not null,

	-- Last time the job definition was updated
	updated datetime default getdate() not null,

	-- Type of job.  Only supported value right now is "java" for a Java class.
	type varchar(1024) not null,

	-- Job class that should be run when job is executed.
	-- type='java', class='net.threebit.SomeJobClass'
	class varchar(1024) not null

);

create table jobToolArguments (

  -- Job number
  job int not null,

  -- Argument key
  k varchar(1024) not null,

  -- Argument value
  v varchar(2048) null

);

create table jobToolLog (

  -- Job number
  job int not null,

	-- time of event
	created datetime default getdate() not null,

	-- Random text for now
	text varchar(1024) null

);

Definition at line 113 of file JobTool.java.

---

Constructor & Destructor Documentation

sosc::JobTool::JobTool (  DbTool    dbTool )  [inline]

This constructor is left public so subclassing can be done, but it should not be used. Use the singleton accessor instead. Definition at line 140 of file JobTool.java. Referenced by sosc::JobTool::initialize().

---

Member Function Documentation

void sosc::JobTool::addJob (  String    queue, String    description, String    type, String    className, Map    args )  throws Exception [inline]

Adds a new job to the job queue. The job's priority is the same as it's ID (determined by the database), meaning that JobTool is a FIFO queue. Returns: The job number of the job that was added. Definition at line 170 of file JobTool.java. References sosc::DbTool::commit(), sosc::DbTool::getInt(), sosc::JobTool::JOB_ARGUMENTS, sosc::JobTool::JOB_TABLE, sosc::JobTool::log(), sosc::DbTool::quote(), and sosc::DbTool::update().

synchronized JobTool sosc::JobTool::getInstance (    )  throws Exception [inline, static]

Returns the initialized JobTool singleton. Throws an exception if initialize() has not been called yet. Definition at line 158 of file JobTool.java. References sosc::JobTool::ready. Referenced by sosc::JobTool::initialize().

synchronized JobTool sosc::JobTool::initialize (  DbTool    dbTool )  throws Exception [inline, static]

ameter db The database tool that JobTool should use to access the job database. Returns: The same singleton as getInstance(). Provided for convenience. Definition at line 148 of file JobTool.java. References sosc::JobTool::getInstance(), sosc::JobTool::JobTool(), and sosc::JobTool::ready.

void sosc::JobTool::log (  int    jobId, String    text )  throws Exception [inline]

Makes a log entry for the specified job. There is a hidden synchronization so watch out. Definition at line 306 of file JobTool.java. Referenced by sosc::JobTool::addJob(), and sosc::JobTool::runJob().

Job sosc::JobTool::runJob (  String    queue, Map    args2 )  throws Exception [inline]

Runs the next call in the queue by instantiating it then calling the jobs "execute(Map args1, Map args2)" method, where "args1" is the jobs arguments when it was added and "args2" is the arguments specified with this method. This method is partially synchronized with the JobTool, but only for the part that mutates the job queue. After that, monitors are released and the Job runs in the Thread that calls this method. Callers should be aware that they will block until the Job finishes. An asynchronous version of this method may be added in the future. Returns: The Job object that ran so the caller can pick up any state that was left over. Note that the Job has completed (in one way or another at this point. May be null if there was a problem running the job. Definition at line 234 of file JobTool.java. References sosc::DbTool::commit(), sosc::DbTool::getString(), sosc::JobTool::JOB_ARGUMENTS, sosc::JobTool::JOB_TABLE, sosc::JobTool::log(), sosc::DbTool::query(), sosc::DbTool::quote(), sosc::DbTool::toMap(), and sosc::DbTool::update().

---

Member Data Documentation

DbTool sosc::JobTool::db = null [private]

Database access. Definition at line 122 of file JobTool.java.

final String sosc::JobTool::JOB_ARGUMENTS = "jobToolArguments"

Should be made private. Definition at line 128 of file JobTool.java. Referenced by sosc::JobTool::addJob(), and sosc::JobTool::runJob().

final String sosc::JobTool::JOB_LOG = "jobToolLog"

Should be made private. Definition at line 131 of file JobTool.java.

final String sosc::JobTool::JOB_TABLE = "jobToolJobs"

Should be made private. Definition at line 125 of file JobTool.java. Referenced by sosc::JobTool::addJob(), and sosc::JobTool::runJob().

ArrayList sosc::JobTool::jobs = new ArrayList() [private]

A list of the running jobs. Definition at line 134 of file JobTool.java.

JobTool sosc::JobTool::jobTool = null [static, private]

Singleton instance. May be null if nothing has been initialized yet. Definition at line 116 of file JobTool.java.

boolean sosc::JobTool::ready = false [static, private]

True when JobTool is ready for work. Definition at line 119 of file JobTool.java. Referenced by sosc::JobTool::getInstance(), and sosc::JobTool::initialize().

---

The documentation for this class was generated from the following file:

• JobTool.java

---