Revision as of 05:34, 7 November 2013

Obsidian 2.3 introduced a new unified Embedded API which contains all the same actions and semantics as the REST API. It replaces the old Legacy API.

This API is accessible through Java, and can be used in software environments where the REST API is unavailable or undesired.

Javadoc is also available to supplement this page.

Overview

The Obsidian Embedded API allows your application a way to access Obsidian data, schedule jobs, and control Obsidian in a variety of ways.

The API gives users the power to do things like initialize scheduled jobs at deployment time, trigger jobs based on events in your applications, and expose pieces of the Obsidian API in their own custom user interfaces.

Accessing the API

The Embedded API is written in Java and can be be accessed within the context of a running Obsidian node, although the scheduler itself need not be active.

In addition, it can be embedded in applications that are not running Obsidian, simply by including Obsidian's dependent libraries and properties file.

Authorization

The Embedded API is not secured, though all actions accept an audit user which is linked to actions which modify Obsidian state. Any code that has access to the Obsidian database via its defined credentials can manipulate Obsidian job configurations.

Transactions

By default, when you invoke actions within the API, each individual call is in its own transaction which is committed when successful, and rolls back on failure.

However, you can wrap multiple API calls into a single transaction, so you get one unit of work which either is fully committed or rolled back. An example is shown below. For full semantics, see AbstractAPIManager.withTransaction.

final String auditUser = "Bob";

List<HostDetail> updated = new HostManager().withTransaction(auditUser, new Callable<<HostDetail>>() {
    
    public List<HostDetail> call() throws Exception {
        
        // disable some hosts in an atomic manner (does not have to be the same instance of even type of Manager class)
        HostDetail hostA = new HostManager().updateHost("hostA", new HostUpdateRequest().withEnabled(false), auditUser );
        HostDetail hostB = new HostManager().updateHost("hostB", new HostUpdateRequest().withEnabled(false), auditUser );
            
        // this is within the same transaction
        new JobManager().resubmitRuntime(jobToResubmit, auditUser);

        return Arrays.asList(hostA, hostB);
    }
});
     
System.out.println("Updated hosts: " + updated);

API Basics

The API is exposed through Manager classes in the package com.carfey.ops.api.embedded:

JobManager - Create and manage jobs.
RuntimeManager - List job runtime history, resubmit jobs, preview scheduled times, etc.
HostManager - Manage and list active scheduling hosts (i.e. nodes).
CustomCalendarManager - Manage custom calendars.

To invoke an API method, simply create a new Manager instance, and invoke the appropriate method:

RuntimeListing recentRuntimes = new RuntimeManager().listRuntimes(new RuntimeListingParameters());

You can reuse manager instances if you like, but it is ultimately up to your preference, as it offers no clear

Exceptions

API calls generally throw three types of exceptions:

ValidationException - some sort of validation error occurred.
MissingEntityException - The requested entity could not be found by the ID supplied.
All other Exception types - some other type of error that you probably can't do much with (database issues, etc.).

When integrating the API into your application, you may wish to apply appropriate handling to ValidationException and MissingEntityException, but otherwise you can treat exceptions as a generic server errors.

Enumerations

Below are valid values for commonly used fields in the API. These are also used by the REST API.

Corresponding Java enums can be found in the package com.carfey.ops.api.enums.

Job Status

ENABLED
DISABLED
UNSCHEDULED_ACTIVE or UNSCHEDULED ACTIVE
CHAIN_ACTIVE or CHAIN ACTIVE
AD_HOC_ACTIVE or AD HOC ACTIVE

Job History Status

READY
RUNNING
COMPLETED
FAILED
MISSED
DIED
CONFLICTED
OVERLAPPED
ABANDONED
CONFLICT_MISSED or CONFLICT MISSED
CHAIN_SKIPPED or CHAIN SKIPPED

Job Recovery Type

NONE
LAST
ALL
CONFLICTED

Job Parameter Type

STRING
INTEGER
LONG
DECIMAL
BOOLEAN
CLASS

JobManager API

JobManager is used to manage job configurations. If you are looking for ways to view or manage job runtimes, see RuntimeManager.

List/Search Jobs

You can list or search existing jobs using JobManager.listJobs(), which accepts an optional JobListingParameters and returns a JobListing.

You can limit the returned jobs by providing a JobListingParameters.

JobListingParameters Fields

Field	Required?	Notes
activeStatuses	N	Restricts the preview to the selected statuses.
effectiveDate	N	If querying by activeStatuses, this allows you to indicate what point in time to compare against the job status. Defaults to next minute.
hosts	N	If specified, only jobs that run on the specified host name(s) are included.
nicknames	N	If specified, only jobs matching the supplied nicknames are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs containing the word "order", use "%order%".
filterParameters	N	If specified, values supplied in thie map can be used to match on job parameter values, either custom or defined. If multiple values for the same name (i.e. key) are supplied, a job is matched if any of its configured values match one of the supplied values. If multiple names are used, each must have a matching value for the job to be returned. Usage note: This can be used to tag jobs with searchable metadata by configuring custom parameters. For example, if jobs belong to logical groups, you may create a custom parameter on applicable jobs named "group" and use filterParameters to locate jobs belonging to specific groups, such as "customer" or "order".

REST equivalent: Get a list of jobs

Get a Job's Details

To get full job information, including all historical schedules and parameter information, call JobManager.getJob() with the appropriate job ID. The method will return a JobDetail, or throw a MissingEntityException if it does not exist.

REST equivalent: Get details of an existing job

Add a Job

You can add a new job using JobManager.addJob(), which accepts a JobCreationRequest.

When you create the job, you provide an initial schedule.

Note: When supplying effective and end dates for schedules, seconds must be omitted. To do so, use com.carfey.jdk.lang.DateTime.clearSeconds(), which returns a copy of the date with seconds removed.

JobCreationRequest Fields

Field	Required?	Notes
jobClass	Y	Fully qualified class name of the job. Max 255 chars.
nickname	Y	Unique nickname for the job. Max 255 chars.
pickupBufferMinutes	N	Pickup buffer minutes which defaults to 2. Integer greater than zero.
recoveryType	Y	Recovery type as defined in Enumerations.
state	Y	Initial schedule's job status as defined in Enumerations.
schedule	Y/N	If state is ENABLED, the mandatory cron-style schedule for the job. If not ENABLED, this should be omitted.
effectiveDate	N	Optional effective date for the initial schedule, with no seconds specified. If not set, this defaults to next minute. Until this date is reached, the job is DISABLED.
endDate	N	Optional end date for the initial schedule, with no seconds specified. If set, the job will become DISABLED after this date passes.
customCalendarId	N	Optional custom calendar id.
hosts	N	Zero or more host names that this job may run on. If none set, the job may run on any host.
minExecutionDuration	N	The minimum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
maxExecutionDuration	N	The maximum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
autoRetryCount	N	Number of auto retries on non-interrupted execution failure. Defaults to 0, which means none are desired.
chainAll	N	Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created. Defaults to false.
parameters	Y/N	Zero or more parameter definitions. If a job defines required parameters with the `@Configuration` annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.

REST equivalent: POST a new job

Update a Job

You can update an existing job using JobManager.updateJob(), which accepts a job ID and a JobUpdateRequest. The method will return the new state of the job as a JobDetail, or throw a MissingEntityException if it does not exist.

This does not support schedule changes or additions. For schedule changes, see Add a New Schedule to a Job.

This method will only update fields that are supplied in the JobUpdateRequest. You may update one or more fields as desired.

JobUpdateRequest Format

Field	Required?	Notes
jobClass	N	Fully qualified class name of the job. Max 255 chars.
nickname	N	Unique nickname for the job. Max 50 chars.
pickupBufferMinutes	N	Pickup buffer minutes. Integer greater than zero.
recoveryType	N	Recovery type as defined in Enumerations.
hosts	N	Zero or more host names that this job may run on. If none set, the job may run on any host.
minExecutionDuration	N	The minimum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
maxExecutionDuration	N	The maximum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "2h".
autoRetryCount	N	Number of auto retries on non-interrupted execution failure. 0 if none are desired.
chainAll	N	Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
parameters	N	Zero or more parameter definitions. If a job defines required parameters with the `@Configuration` annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.

REST equivalent: PUT updates to an existing job

Delete a Job

You can delete an existing job using JobManager.deleteJob(), which accepts a job ID and cascade flag. The method will return the final state of the job before deletion as a JobDetail, or throw a MissingEntityException if it does not exist.

Parameters

Field	Required?	Notes
cascade	Y	If set to true, all job conflict and chain definitions for this job will also be deleted. If set to false, any existing job conflicts or chain definitions will cause the request to fail.

REST equivalent: Delete an existing job

List a Job's Schedules

You can access the full history of a job's schedules via JobManager.listJobSchedules(), which will return JobScheduleListing.

Note that the full schedule history can also be obtained via the schedules field of the JobDetail returned by JobManager.getJob().

REST equivalent: Get a list of an existing job's schedules

Add a New Schedule to a Job

You can add a new schedule to a job via JobManager.addJobSchedule(), which accepts a ScheduleCreationRequest.

This may be used to immediately change a job's scheduling state, or to schedule a future change. Creating a new schedule automatically splits and merges existing schedules. For example, if you have an enabled job and you disabled it for a day, the job will automatically re-enable after that day.

Note: When supplying effective and end dates for schedules, seconds must be omitted. To do so, use com.carfey.jdk.lang.DateTime.clearSeconds(), which returns a copy of the date with seconds removed.

ScheduleCreationRequest Fields

Field	Required?	Notes
state	Y	The schedule's job status as defined in Enumerations.
schedule	Y/N	If state is ENABLED, the mandatory cron-style schedule for the job. If not ENABLED, this should be omitted.
effectiveDate	N	Optional effective date for the schedule, with no seconds specified. If not set, this defaults to next minute. Until this date is reached, the job is DISABLED.
endDate	N	Optional end date for the schedule, with no seconds specified. If set, the job will become DISABLED after this date passes.
customCalendarId	N	Optional custom calendar for schedule.

REST equivalent: POST a new schedule to an existing job

RuntimeManager API

RuntimeManager is used to manage and view scheduled job runtimes (i.e. history). If you are looking for ways to view or manage jobs, see JobManager.

List Scheduled Runtimes

To get a list of scheduled or completed job runtimes (i.e. history), use RuntimeManager.listRuntimes(), which accepts an optional RuntimeListingParameters instance. The results in the returned RuntimeListing are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of scheduled time.

Note: The nextPageStartKey field in the RuntimeListing indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the Admin System tab). To fetch the next page of results, invoke the same method with the startKey field on RuntimeListingParameters set to the returned nextPageStartKey.

RuntimeListingParameters Fields

Field	Required?	Notes
jobIds	N	Restricts the search to the selected jobs.
statuses	N	Restricts the search to the selected statuses. See Enumerations for valid values.
hosts	N	If specified, only job runtimes that are assigned to the specified host(s) are included.
startDate	N	Start date for the job runtimes to return (inclusive). Defaults to 24 hours ago.
endDate	N	End date for the job runtimes to return (inclusive). Defaults to a day after the start time. Must be after the start time.
startKey	N	If requesting the next page of results from a previous call, set it to the returned `nextPageStartKey`.

REST equivalent: Get a list of scheduled runtimes

Get Details on a Scheduled or Completed Runtime

To get full details on a scheduled or completed job runtime, including job results and one-time run configuration, use RuntimeManager.getRuntime(). The method returns a RuntimeResult, which has a nested RuntimeDetail containing the full job output and one-time run parameters, or throws a MissingEntityException if it does not exist.

REST equivalent: GET details of an existing scheduled or completed runtime

Preview Runtimes

To preview future runtimes for one or more jobs, use RuntimeManager.listRuntimePreview(), which accepts an optional RuntimePreviewParameters instance to filter the results. The method returns a RuntimePreviewListing.

This method is useful to see when jobs will run during a given time period. Note that these are an estimate of runtimes and cannot account for overlapped jobs, schedule changes or other issues that may result in altered execution times. Results are ordered by scheduled time descending.

Note: The capped field in the returned RuntimePreviewListing indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the Admin System tab). If you are hitting this condition, try limiting your date range or other parameters. Due to the nature of the runtime preview, paging is not feasible.

RuntimePreviewParameters Fields

Field	Required?	Notes
jobIds	N	Restricts the preview to the selected jobs.
startDate	N	Start date for the runtimes to preview (inclusive). Defaults to the current minute.
endDate	N	End date for the runtimes to preview (inclusive). Defaults to a day after the start time. Must be after the start time.

REST equivalent: GET a list of runtime previews

Schedule a New Runtime for a Job

To submit an ad hoc job run (executed immediately), or a one-time run scheduled for a later time, use RuntimeManager.submitRuntime(). A RuntimeSubmissionRequest must be supplied. The method returns a RuntimeSubmissionResult if it succeeds, or throws a MissingEntityException if the specified job ID does not exist.

Note: The job must be in a valid state to allow for execution (i.e. "UNSCHEDULED ACTIVE", "ENABLED", or "AD HOC ACTIVE").

RuntimeSubmissionRequest Fields

Field	Required?	Notes
scheduledTime	N	The scheduled time, when the request is for a scheduled one-time run. If not supplied, the runtime is submitted for immediate execution as an ad hoc job.
parameters	N	Zero or more parameter definitions. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. If the parameter name matches a parameter defined for the job, it must be of the same type.

REST equivalent: POST a new scheduled runtime for an existing job

Resubmit a Failed Job Runtime

If a job execution fails and you wish to resubmit it, use RuntimeManager.resubmitRuntime() with the appropriate job runtime ID. The method returns a RuntimeResubmissionResult if the action succeeds, or throws a MissingEntityException if the specified job runtime ID does not exist.

REST equivalent: POST a resubmission request for a failed job runtime

HostManager API

Coming soon

CustomCalendarManager API