node-deadline/lib/jobs/README.md

Module to interface with Deadline Compute Management System by Thinkbox Software

#Deadline.jobs

Ownes all functionality related to Deadline jobs.

###Deadline.jobs.get( options, callback )

Base function for retrieving jobs from Deadline, takes an options object defining which jobs to get.
With no options or an empty options object, this function returns all jobs.

**NOTE:** Deadline.jobs.get is also provided under Deadline.get.jobs for better code clarity if desired.
(ie: `deadline.jobs.get.by.id === deadline.get.jobs.by.id`)

**NOTE:** Jobs are not persistent across requests, and jobs that are to be edited should be done so
and saved before creating another query which includes the same job, or two job states will exist.

####Options

**status:** *get only jobs matching the given status(es)* ( enum )
```
{ status: Deadline.COMPLETE | Deadline.FAILED }
```

**id:** *get only jobs with the given id(s)* ( string | array[string] )
```
{ id: "55b911f1ec46630980bba101" }
{ id: ["55b911f1ec46630980bba101", "55b911f1ec46630980bba102"] }
```

**department:** *get only jobs from the given department(s)* ( string | array[string] )
```
{ department : "myDepartment" }
{ department : ["myDepartment", "myOtherDepartment"] }
```

**user:** *get only jobs submitted by the given user(s)* ( string | array[string] )
```
{ user : "username" }
{ user : ["user1", "user2"] }
```

**machine:** *get only jobs submitted from the given machine(s)* ( string | array[string] )
```
{ machine : "machineName" }
{ machine : ["machine1", "machine2"] }
```

**group:** *get only jobs from the given group(s)* ( string | array[string] )
```
{ group : "myGroup" }
{ group : ["myGroup", "myOtherGroup"] }
```

**pool:** *get only jobs whose primary pool is any of the given pool names* ( string | array[string] )
```
{ pool: "myPool" }
{ pool: ["myPool", "myOtherPool"] }
```

**secondaryPool:** *same as pool, but matches job's secondary pool* ( string | array[string] )
```
{ secondaryPool: "mySecondaryPool" }
{ secondarypool: ["mySecondaryPool", "myOtherSecondaryPool"] }
```

**eitherPool:** *same as pool, but returns jobs with matching primary pool **or** secondary pool* ( string | array[string] )
```
{ eitherPool: "myPool" }
{ eitherPool: ["myPool", "myOtherPool"] }
```

**priority:** *matches jobs with the given priority, priorities or in a range of priorities* ( number | array[number] )
```
{ priority: 10 }
{ priority: [0, 5] } //either 0 or 5
{ priority: new Deadline.jobs.FrameRange( "0-20x5" ) } //either 0, 5, 10, 15, or 20
``

**updated:** *matches jobs based on their last updated time stamp* ( object(before[Date], after[Date]) )
```
var yesterday = new Date();
yesterday.setTime( new Date().getTime() - 1000 * 60 * 60 * 24 )
{
  updated: {
    before: new Date(),
    after: yesterday
  }
}
``

**extraInfo:** *matches jobs with the given extra info value(s)* ( object )
```javascript
//match a singular key-value
{ extraInfo: {Ex0: "myExtraInfo"} }
//match any of the values
{ extraInfo: {Ex0: ["eitherThis", "orThis"] } }
{ extraInfo: {
  //match multiple keys
  Ex0: ["eitherThis", "orThis"],
  Ex2: "thisToo"
} }
```

####Callback

Called when the query is complete, takes two parameters: error and results

- **error:** a Deadline.Error object or null if OK
- **results:** an array of jobs mathing the request, empty if none found, null if there was a fatal error

###Deadline.jobs.get.by

This object provides all of the above available options in Deadline.jobs.get
as individual functions for better code clarity, if applicable. Valid options here
mirrors the valid options for Deadline.jobs.get()

```javascript
deadline.jobs.get.by.state( Deadline.COMPLETE );
deadline.jobs.get.by.id( "55b911f1ec46630980bba101" );
```

###Deadline.jobs.get.any( properties, callback )

The same as Deadline.jobs.get() but mathches any of the given properties rather than all of them.

####Callback

Called when the query is complete, takes two parameters: error and results

- **error:** a Deadline.Error object or null if OK
- **results:** an array of jobs mathing the request, empty if none found, null if there was a fatal error

###Deadline.jobs.get.find( query, callback )

Accepts a raw MongoDB query to use in the
[collection.find](http://mongodb.github.io/node-mongodb-native/2.0/api/Collection.html#find) method.
*This methond is used internally by all other get methods, and should not be used when another suitable get method exists for
the query in question*

###Deadline.jobs.set( jobs, callback )

####jobs
Either a single Deadline.Job or an array of them. This function decides what data should be updated on the job (if any)
and they submits those changes to the server.

**Note** *Not all properties on a job can be changed, using this workflow is crucial in ensuring that the Deadline database
is not corrupted by this module.*

####Callback

Called when the query is complete, takes one parameter: error

- **error:** a Deadline.Error object or null if OK

##Deadline.jobs.Job

Represents a singular Job from the Deadline database ( [readme](./Job/md) ).

##Deadline.jobs.FrameRange

A utility class for parsing and managing frame ranges in in Deadline ( [readme](./FrameRange.md) ).