com.splunk
Class Job

java.lang.Object
  extended by com.splunk.Resource
      extended by com.splunk.Entity
          extended by com.splunk.Job
All Implemented Interfaces:
java.util.Map<java.lang.String,java.lang.Object>

public class Job
extends Entity

The Job class represents a job, which is an individual instance of a running or completed search or report, along with its related output.


Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
java.util.Map.Entry<K,V>
 
Field Summary
 
Fields inherited from class com.splunk.Entity
toUpdate
 
Fields inherited from class com.splunk.Resource
actions, path, refreshArgs, service, title
 
Method Summary
protected  java.lang.String actionPath(java.lang.String action)
          Returns the action path.
 Job cancel()
          Stops the current search and deletes the result cache.
 Job control(java.lang.String action)
          Performs the requested action on this job.
 Job control(java.lang.String action, java.util.Map args)
          Performs the requested action on this job.
 Job disablePreview()
          Disables preview for this job.
 Job enablePreview()
          Enables preview for this job (although it might slow search considerably).
 Job finish()
          Stops the job and provides intermediate results available for retrieval.
 java.util.Date getCursorTime()
          Returns the earliest time from which no events are later scanned.
 java.lang.String getDelegate()
          Returns a value that indicates how jobs were started (such as the scheduler).
 int getDiskUsage()
          Returns the disk usage for this job.
 java.lang.String getDispatchState()
          Returns the dispatch state for this job.
 float getDoneProgress()
          Returns the approximate progress of the job, in the range of 0.0 to 1.0.
 int getDropCount()
          Returns the number of possible events that were dropped due to the rt_queue_size (the number of events that the indexer should use for this search).
 java.util.Date getEarliestTime()
          Returns the earliest time in the time range to search.
 int getEventAvailableCount()
          Returns the count of events stored by search that are available to be retrieved from the events endpoint.
 int getEventCount()
          Returns the count of events (pre-transforming) that were generated.
 int getEventFieldCount()
          Returns the count of event fields.
 boolean getEventIsStreaming()
          Indicates whether the events from this job are available by streaming.
 boolean getEventIsTruncated()
          Indicates whether any events from this job have not been stored.
 java.io.InputStream getEvents()
          Returns the InputStream IO handle for this job's events.
 java.io.InputStream getEvents(JobEventsArgs args)
          Returns the InputStream IO handle for this job's events.
 java.io.InputStream getEvents(java.util.Map args)
          Returns the InputStream IO handle for this job's events.
 java.lang.String getEventSearch()
          Returns the subset of the entire search that is before any transforming commands.
 java.lang.String getEventSorting()
          Returns a value that indicates how events are sorted.
 java.lang.String getKeywords()
          Returns all positive keywords used by this job.
 java.lang.String getLabel()
          Returns this job's label.
 java.util.Date getLatestTime()
          Returns the latest time in the time range to search.
 java.lang.String getName()
          Returns this job's name (its search ID).
 int getNumPreviews()
          Returns the number of previews that have been generated so far for this job.
 int getPriority()
          Returns this job's priority in the range of 0-10.
 java.lang.String getRemoteSearch()
          Returns the search string that is sent to every search peer for this job.
 java.lang.String getReportSearch()
          Returns the reporting subset of this search, which is the streaming part of the search that is send to remote providers if reporting commands are used.
 int getResultCount()
          Returns the total count of results returned for this search job.
 boolean getResultIsStreaming()
          Indicates whether the job's results are available by streaming.
 int getResultPreviewCount()
          Returns the number of result rows in the latest preview results for this job.
 java.io.InputStream getResults()
          Returns the InputStream IO handle for the results from this job.
 java.io.InputStream getResults(JobResultsArgs args)
          Returns the InputStream IO handle for the results from this job.
 java.io.InputStream getResults(java.util.Map args)
          Returns the InputStream IO handle for the results from this job.
 java.io.InputStream getResultsPreview()
          Returns the InputStream IO handle for the preview results from this job.
 java.io.InputStream getResultsPreview(JobResultsPreviewArgs args)
          Returns the InputStream IO handle for the preview results from this job.
 java.io.InputStream getResultsPreview(java.util.Map args)
          Returns the InputStream IO handle for the preview results from this job.
 float getRunDuration()
          Returns the time that the search job took to complete.
 int getScanCount()
          Returns the number of events that are scanned or read off disk.
 java.lang.String getSearch()
          Returns this job's search title.
 java.lang.String getSearchEarliestTime()
          Returns the earliest time in the time range to search.
 java.lang.String getSearchLatestTime()
          Returns the latest time in the time range to search.
 java.io.InputStream getSearchLog()
          Returns the InputStream IO handle to the search log for this job.
 java.io.InputStream getSearchLog(java.util.Map args)
          Returns the InputStream IO handle to the search log for this job.
 java.lang.String[] getSearchProviders()
          Returns a list of search peers that were contacted for this search.
 java.lang.String getSid()
          Returns the unique search identifier (SID) for this job.
 int getStatusBuckets()
          Returns the maximum number of timeline buckets for this job.
 java.io.InputStream getSummary()
          Returns the InputStream IO handle for the summary for this job.
 java.io.InputStream getSummary(JobSummaryArgs args)
          Returns the InputStream IO handle for the summary for this job.
 java.io.InputStream getSummary(java.util.Map args)
          Returns the InputStream IO handle for the summary for this job.
 java.io.InputStream getTimeline()
          Returns the InputStream IO handle for the timeline for this job.
 java.io.InputStream getTimeline(java.util.Map args)
          Returns the InputStream IO handle for the timeline for this job.
 int getTtl()
          Returns this job's time to live--that is, the time before the search job expires and is still available.
 boolean isDone()
          Indicates whether the job is done.
 boolean isFailed()
          Indicates whether the job failed.
 boolean isFinalized()
          Indicates whether the job is finalized (forced to finish).
 boolean isPaused()
          Indicates whether the job is paused.
 boolean isPreviewEnabled()
          Indicates whether preview for the job is enabled.
 boolean isReady()
          Indicates whether the job has been scheduled and is ready to return data.
 boolean isRealTimeSearch()
          Indicates whether the job is a real-time search.
 boolean isRemoteTimeline()
          Indicates whether the job has a remote timeline component.
 boolean isSaved()
          Indicates whether the job is to be saved indefinitely.
 boolean isSavedSearch()
          Indicates whether this job was run as a saved search (via scheduler).
 boolean isZombie()
          Indicates whether the process running the search is dead but with the search not finished.
 Job pause()
          Pauses the current search.
 Job refresh()
          Refreshes this job.
 void remove()
          Unsupported.
 void setPriority(int value)
          Sets this job's priority in the range of 0-10.
 
Methods inherited from class com.splunk.Entity
clear, containsKey, containsValue, disable, enable, entrySet, get, getMetadata, isDisabled, isEmpty, isNameChangeAllowed, keySet, put, putAll, remove, size, update, update, validate, values
 
Methods inherited from class com.splunk.Resource
getPath, getService, getTitle, invalidate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Method Detail

actionPath

protected java.lang.String actionPath(java.lang.String action)
Returns the action path.

Overrides:
actionPath in class Entity
Parameters:
action - The requested action.
Returns:
The action path.

control

public Job control(java.lang.String action)
Performs the requested action on this job. Valid values are: "pause", "unpause", "finalize", "cancel", "touch", "setttl", "setpriority", "enablepreview", and "disablepreview".

Parameters:
action - The action to perform.
Returns:
The search job.

control

public Job control(java.lang.String action,
                   java.util.Map args)
Performs the requested action on this job. Valid values are: "pause", "unpause", "finalize", "cancel", "touch", "setttl", "setpriority", "enablepreview", and "disablepreview".

Parameters:
action - The action to perform.
args - Optional arguments for this action ("ttl" and "priority").
Returns:
The search job.

cancel

public Job cancel()
Stops the current search and deletes the result cache.

Returns:
The search job.

disablePreview

public Job disablePreview()
Disables preview for this job.

Returns:
The search job.

enablePreview

public Job enablePreview()
Enables preview for this job (although it might slow search considerably).

Returns:
The search job.

finish

public Job finish()
Stops the job and provides intermediate results available for retrieval.

Returns:
The search job.

pause

public Job pause()
Pauses the current search.

Returns:
The search job.

getCursorTime

public java.util.Date getCursorTime()
Returns the earliest time from which no events are later scanned. (Use this as a progress indicator.)

Returns:
The earliest time.
See Also:
getLatestTime(), getEarliestTime(), getDoneProgress()

getDelegate

public java.lang.String getDelegate()
Returns a value that indicates how jobs were started (such as the scheduler).

Returns:
The delegate, or null if not specified.

getDiskUsage

public int getDiskUsage()
Returns the disk usage for this job.

Returns:
The disk usage, in bytes.

getDispatchState

public java.lang.String getDispatchState()
Returns the dispatch state for this job.
Valid values are: QUEUED, PARSING, RUNNING, PAUSED, FINALIZING, FAILED, or DONE.

Returns:
This job's dispatch state.

getDoneProgress

public float getDoneProgress()
Returns the approximate progress of the job, in the range of 0.0 to 1.0.
doneProgress = (latestTime-cursorTime)/(latestTime-earliestTime)

Returns:
This job's progress.
See Also:
getLatestTime(), getCursorTime(), getEarliestTime()

getDropCount

public int getDropCount()
Returns the number of possible events that were dropped due to the rt_queue_size (the number of events that the indexer should use for this search). For real-time searches only.

Returns:
The number of dropped events.

getEarliestTime

public java.util.Date getEarliestTime()
Returns the earliest time in the time range to search.

Returns:
The earliest time, in UTC format.
See Also:
getLatestTime(), getCursorTime(), getDoneProgress()

getEventAvailableCount

public int getEventAvailableCount()
Returns the count of events stored by search that are available to be retrieved from the events endpoint.

Returns:
The count of available events.

getEventCount

public int getEventCount()
Returns the count of events (pre-transforming) that were generated.

Returns:
The number of events.

getEventFieldCount

public int getEventFieldCount()
Returns the count of event fields.

Returns:
The number of event fields.

getEventIsStreaming

public boolean getEventIsStreaming()
Indicates whether the events from this job are available by streaming.

Returns:
true if events can be streamed, false if not.

getEventIsTruncated

public boolean getEventIsTruncated()
Indicates whether any events from this job have not been stored.

Returns:
true if the event return is truncated, false if not.

getEvents

public java.io.InputStream getEvents()
Returns the InputStream IO handle for this job's events.

Returns:
The event InputStream IO handle.

getEvents

public java.io.InputStream getEvents(java.util.Map args)
Returns the InputStream IO handle for this job's events.

Parameters:
args - Optional arguments. For a list of possible parameters, see the Request parameters for the GET search/jobs/{search_id}/events endpoint in the REST API documentation.
Returns:
The event InputStream IO handle.

getEvents

public java.io.InputStream getEvents(JobEventsArgs args)
Returns the InputStream IO handle for this job's events.

Parameters:
args - Optional arguments (see JobEventsArgs).
Returns:
The event InputStream IO handle.

getEventSearch

public java.lang.String getEventSearch()
Returns the subset of the entire search that is before any transforming commands. The original search should be the "eventSearch" + "reportSearch".

Returns:
The event search query.
See Also:
getReportSearch()

getEventSorting

public java.lang.String getEventSorting()
Returns a value that indicates how events are sorted.

Returns:
"asc" if events are sorted in time order (oldest first), "desc" if events are sorted in inverse time order (latest first), or "none" if events are not sorted.

getKeywords

public java.lang.String getKeywords()
Returns all positive keywords used by this job. A positive keyword is a keyword that is not in a NOT clause.

Returns:
The search job keywords.

getLabel

public java.lang.String getLabel()
Returns this job's label.

Returns:
The search job label.

getLatestTime

public java.util.Date getLatestTime()
Returns the latest time in the time range to search.

Returns:
The latest time, in UTC format.
See Also:
getCursorTime(), getEarliestTime(), getDoneProgress()

getName

public java.lang.String getName()
Returns this job's name (its search ID).

Overrides:
getName in class Resource
Returns:
The search job name.

getNumPreviews

public int getNumPreviews()
Returns the number of previews that have been generated so far for this job.

Returns:
The number of previews.

getPriority

public int getPriority()
Returns this job's priority in the range of 0-10.

Returns:
The search job priority.

setPriority

public void setPriority(int value)
Sets this job's priority in the range of 0-10.

Parameters:
value - The new priority.

getRemoteSearch

public java.lang.String getRemoteSearch()
Returns the search string that is sent to every search peer for this job.

Returns:
The remote search query string.

getReportSearch

public java.lang.String getReportSearch()
Returns the reporting subset of this search, which is the streaming part of the search that is send to remote providers if reporting commands are used. The original search should be the "eventSearch" + "reportSearch".

Returns:
The reporting search query.
See Also:
getEventSearch()

getResultCount

public int getResultCount()
Returns the total count of results returned for this search job. This is the subset of scanned events that actually matches the search terms.

Returns:
The number of results.

getResultIsStreaming

public boolean getResultIsStreaming()
Indicates whether the job's results are available by streaming.

Returns:
true if results can be streamed, false if not.

getResultPreviewCount

public int getResultPreviewCount()
Returns the number of result rows in the latest preview results for this job.

Returns:
The number of result rows.

getResults

public java.io.InputStream getResults()
Returns the InputStream IO handle for the results from this job.

Returns:
The results InputStream IO handle.

getResults

public java.io.InputStream getResults(java.util.Map args)
Returns the InputStream IO handle for the results from this job.

Parameters:
args - Optional arguments. For a list of possible parameters, see the Request parameters for the GET search/jobs/{search_id}/results endpoint in the REST API documentation.
Returns:
The results InputStream IO handle.

getResults

public java.io.InputStream getResults(JobResultsArgs args)
Returns the InputStream IO handle for the results from this job.

Parameters:
args - Optional arguments (see JobResultsArgs).
Returns:
The results InputStream IO handle.

getResultsPreview

public java.io.InputStream getResultsPreview()
Returns the InputStream IO handle for the preview results from this job.

Returns:
The preview results InputStream IO handle.

getResultsPreview

public java.io.InputStream getResultsPreview(java.util.Map args)
Returns the InputStream IO handle for the preview results from this job.

Parameters:
args - Optional arguments. For a list of possible parameters, see the Request parameters for the GET search/jobs/{search_id}/results_preview endpoint in the REST API documentation.
Returns:
The preview results InputStream IO handle.

getResultsPreview

public java.io.InputStream getResultsPreview(JobResultsPreviewArgs args)
Returns the InputStream IO handle for the preview results from this job.

Parameters:
args - Optional arguments (see JobResultsPreviewArgs).
Returns:
The preview results InputStream IO handle.

getRunDuration

public float getRunDuration()
Returns the time that the search job took to complete.

Returns:
The run-time duration, in seconds.

getScanCount

public int getScanCount()
Returns the number of events that are scanned or read off disk.

Returns:
The number of events.

getSearch

public java.lang.String getSearch()
Returns this job's search title.

Returns:
The search title.

getSearchEarliestTime

public java.lang.String getSearchEarliestTime()
Returns the earliest time in the time range to search.

Returns:
This earliest search time, in epoch format.
See Also:
getLatestTime(), getCursorTime(), getDoneProgress()

getSearchLatestTime

public java.lang.String getSearchLatestTime()
Returns the latest time in the time range to search.

Returns:
The latest search time, in epoch format.
See Also:
getEarliestTime(), getCursorTime(), getDoneProgress()

getSearchLog

public java.io.InputStream getSearchLog()
Returns the InputStream IO handle to the search log for this job.

Returns:
The search log InputStream IO handle.

getSearchLog

public java.io.InputStream getSearchLog(java.util.Map args)
Returns the InputStream IO handle to the search log for this job.

Parameters:
args - Optional argument ("attachment").
Returns:
The search log InputStream IO handle.

getSearchProviders

public java.lang.String[] getSearchProviders()
Returns a list of search peers that were contacted for this search.

Returns:
The search peers.

getSid

public java.lang.String getSid()
Returns the unique search identifier (SID) for this job.

Returns:
The job's SID.

getSummary

public java.io.InputStream getSummary()
Returns the InputStream IO handle for the summary for this job.

Returns:
The summary InputStream IO handle.

getSummary

public java.io.InputStream getSummary(java.util.Map args)
Returns the InputStream IO handle for the summary for this job.

Parameters:
args - Optional arguments. For a list of possible parameters, see the Request parameters for the GET search/jobs/{search_id}/summary endpoint in the REST API documentation.
Returns:
The summary InputStream IO handle.

getSummary

public java.io.InputStream getSummary(JobSummaryArgs args)
Returns the InputStream IO handle for the summary for this job.

Parameters:
args - Optional arguments (see JobSummaryArgs).
Returns:
The summary InputStream IO handle.

getStatusBuckets

public int getStatusBuckets()
Returns the maximum number of timeline buckets for this job.

Returns:
The number of timeline buckets.

getTimeline

public java.io.InputStream getTimeline()
Returns the InputStream IO handle for the timeline for this job.

Returns:
The timeline InputStream IO handle.

getTimeline

public java.io.InputStream getTimeline(java.util.Map args)
Returns the InputStream IO handle for the timeline for this job.

Parameters:
args - Optional arguments ("output_time_format" and "time_format").
Returns:
The timeline InputStream IO handle.

getTtl

public int getTtl()
Returns this job's time to live--that is, the time before the search job expires and is still available. If this value is 0, it means the job has expired.

Returns:
The time to live, in seconds.

isDone

public boolean isDone()
Indicates whether the job is done.

Returns:
true if the job is done, false if not.

isFailed

public boolean isFailed()
Indicates whether the job failed.

Returns:
true if the job failed, false if not.

isFinalized

public boolean isFinalized()
Indicates whether the job is finalized (forced to finish).

Returns:
true if the job is finalized, false if not.

isPaused

public boolean isPaused()
Indicates whether the job is paused.

Returns:
true if the job is paused, false if not.

isPreviewEnabled

public boolean isPreviewEnabled()
Indicates whether preview for the job is enabled.

Returns:
true if preview is enabled, false if not.

isReady

public boolean isReady()
Indicates whether the job has been scheduled and is ready to return data.

Returns:
true if the job is ready to return data, false if not.

isRealTimeSearch

public boolean isRealTimeSearch()
Indicates whether the job is a real-time search.

Returns:
true if the job is a real-time search, false if not.

isRemoteTimeline

public boolean isRemoteTimeline()
Indicates whether the job has a remote timeline component.

Returns:
true if the job has a remote timeline component, false if not.

isSaved

public boolean isSaved()
Indicates whether the job is to be saved indefinitely.

Returns:
true if the job has been saved, false if not.

isSavedSearch

public boolean isSavedSearch()
Indicates whether this job was run as a saved search (via scheduler).

Returns:
true if the job is from a saved search, false if not.

isZombie

public boolean isZombie()
Indicates whether the process running the search is dead but with the search not finished.

Returns:
true if the job is a zombie, false if not.

refresh

public Job refresh()
Refreshes this job.

Overrides:
refresh in class Entity
Returns:
The search job.

remove

public void remove()
Unsupported. Removes this job. This method is unsupported and will throw an exception.

Overrides:
remove in class Entity