Package uk.ac.starlink.vo
Class UwsJob
java.lang.Object
uk.ac.starlink.vo.UwsJob
Job submitted using the Universal Worker Service pattern.
Instances of this class represent UWS jobs which have been created.
- Since:
- 18 Jan 2011
- Author:
- Mark Taylor
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Callback interface for objects wanting to be notified of job status changes.static class
Exception which may be thrown if a UWS HTTP request receives a response code which is not as mandated by UWS, but not obviously an error. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic int
Chunk size for HTTP transfer encoding; if <=0, don't chunk.static boolean
Whether to trim whitespace from line text responses (like job/phase). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
addJobWatcher
(UwsJob.JobWatcher watcher) Adds a callback which will be invoked whenever this job's phase is found to have changed.void
Attempts to delete this query's UWS job.static UwsJob
createJob
(String jobListUrl, Map<String, String> stringParamMap, Map<String, HttpStreamParam> streamParamMap) Submits a job to a UWS service and returns a new UwsJob object.static String
getCurlPostEquivalent
(URL url, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.auth.AuthContext context, boolean showSecret, Map<String, String> stringParams, Map<String, HttpStreamParam> streamParams, boolean isMultipart) Returns a snippet of text representing a shell invocation of thecurl(1)
command that posts a query corresponding to the given parameters.boolean
Indicates whether this job will be deleted when the JVM exits, if it has not been deleted before.getJobId()
Returns the server-assigned job-id for this job.Returns the URL for this job.Returns the most recently read job state.void
Posts deletion of this job to the server.void
postDestruction
(String epoch) Posts a value of the destruction time for this job.void
postExecutionDuration
(long nsec) Posts a value of the execution duration parameter for this job.static HttpURLConnection
postForm
(URL url, uk.ac.starlink.util.ContentCoding coding, Map<String, String> stringParams, Map<String, HttpStreamParam> streamParams) General form posting method.static HttpURLConnection
postMultipartForm
(URL url, uk.ac.starlink.util.ContentCoding coding, Map<String, String> stringMap, Map<String, HttpStreamParam> streamMap, String boundary) Performs an HTTP form POST with a name->value map and a name->stream map of parameters.void
Posts a phase for this job.static HttpURLConnection
postUnipartForm
(URL url, uk.ac.starlink.util.ContentCoding coding, Map<String, String> paramMap) Performs an HTTP form POST with a name->value map of parameters.readInfo()
Reads the current status document for this job from the server and both stores and returns the result.readInfoBlocking
(int timeoutSec, UwsJobInfo lastInfo) Makes a blocking call to read the current status document for this job from the server and both stores and returns the result.void
removeJobWatcher
(UwsJob.JobWatcher watcher) Removes a callback previously added byaddJobWatcher(uk.ac.starlink.vo.UwsJob.JobWatcher)
.void
setDeleteOnExit
(boolean delete) Determines whether this job will be deleted when the JVM exits, if it has not been deleted before.void
start()
Starts the job by posting the RUN phase.static byte[]
toPostedBytes
(Map<String, String> paramMap) Encodes a name->value mapping as an array of bytes suitable for "application/x-www-form-urlencoded" transmission.toString()
waitForFinish
(long pollMillis) Blocks until the job has reached a completion phase.
-
Field Details
-
HTTP_CHUNK_SIZE
public static int HTTP_CHUNK_SIZEChunk size for HTTP transfer encoding; if <=0, don't chunk. -
TRIM_TEXT
public static boolean TRIM_TEXTWhether to trim whitespace from line text responses (like job/phase). I'm not sure whether (trailing) whitespace is permitted in service responses in this context, but the ESAC GACS service appends "\r\n" to its phase endpoint result. I asked (17-Sep-2014) on the grid@ivoa.net mailing list what's the right answer, but no response, so accept trailing whitespace for now.
-
-
Constructor Details
-
UwsJob
Constructor.- Parameters:
jobUrl
- the UWS {jobs}/(job-id) URL containing the details of this job
-
-
Method Details
-
getJobUrl
Returns the URL for this job. This will normally be a child of the job list URL, and contains a representation of the job state, as well as providing the base URL for further access to the job.- Returns:
- job URL
-
addJobWatcher
Adds a callback which will be invoked whenever this job's phase is found to have changed. Note that the runnable will not in general be invoked from the AWT event dispatch thread.- Parameters:
watcher
- runnable to be notified on job phase change
-
removeJobWatcher
Removes a callback previously added byaddJobWatcher(uk.ac.starlink.vo.UwsJob.JobWatcher)
. Has no effect ifwatcher
is not currently registered.- Parameters:
watcher
- runnable to be removed
-
getLastInfo
Returns the most recently read job state. Invoking this method does not cause the state to be read.- Returns:
- job state object
-
postPhase
Posts a phase for this job.- Parameters:
phase
- UWS job phase to assign- Throws:
IOException
-
postDestruction
Posts a value of the destruction time for this job. The service is not obliged to accept it; completion without error does not necessarily mean that it has done. May not work after job has started.- Parameters:
epoch
- destruction time which should be an ISO-8601 string; it is passed directly to the service- Throws:
IOException
-
postExecutionDuration
Posts a value of the execution duration parameter for this job. The service is not obliged to accept it; completion without error does not necessarily mean that it has done. May not work after job has started.- Parameters:
nsec
- number of elapsed seconds for which job is permitted to run; zero is supposed to mean unlimited- Throws:
IOException
-
start
Starts the job by posting the RUN phase.- Throws:
UwsJob.UnexpectedResponseException
- if HTTP responses other than UWS mandated ones occurIOException
-
waitForFinish
Blocks until the job has reached a completion phase. Depending on the service's capabilities, this may be done using polling or a blocking call.- Parameters:
pollMillis
- polling time in milliseconds to assess job completion, if polling is required- Returns:
- job info corresponding to a completion state
- Throws:
UwsJob.UnexpectedResponseException
- if HTTP responses other than UWS mandated ones occurIOException
InterruptedException
-
readInfo
Reads the current status document for this job from the server and both stores and returns the result. The result becomes the new value of thegetLastInfo()
method.- Returns:
- job status
- Throws:
IOException
-
readInfoBlocking
Makes a blocking call to read the current status document for this job from the server and both stores and returns the result. The result becomes the new value of thegetLastInfo()
method.- Parameters:
timeoutSec
- maximum advised timeout in secondslastInfo
- last known job status- Returns:
- job status
- Throws:
IOException
-
postDelete
Posts deletion of this job to the server.- Throws:
IOException
- if job deletion failed for some reason
-
attemptDelete
public void attemptDelete()Attempts to delete this query's UWS job. This may harmlessly be called multiple times; calls following the first one have no effect. In case of failure a message is logged through the logging system. -
setDeleteOnExit
public void setDeleteOnExit(boolean delete) Determines whether this job will be deleted when the JVM exits, if it has not been deleted before.- Parameters:
delete
- true to delete on exit, false otherwise
-
getDeleteOnExit
public boolean getDeleteOnExit()Indicates whether this job will be deleted when the JVM exits, if it has not been deleted before.- Returns:
- true iff delete on exit
-
getJobId
Returns the server-assigned job-id for this job. It is the final part of the Job URL.- Returns:
- job ID
-
toString
-
createJob
public static UwsJob createJob(String jobListUrl, Map<String, String> stringParamMap, Map<String, throws IOExceptionHttpStreamParam> streamParamMap) Submits a job to a UWS service and returns a new UwsJob object. No status is posted. The phase following this method is expected to be PENDING.- Parameters:
jobListUrl
- base (job list) URL for UWS servicestringParamMap
- map of text parametersstreamParamMap
- map of streamed parameters- Returns:
- new UWS job
- Throws:
UwsJob.UnexpectedResponseException
- if a non-303 response was receivedIOException
- if some other IOException occurs
-
postForm
public static HttpURLConnection postForm(URL url, uk.ac.starlink.util.ContentCoding coding, Map<String, String> stringParams, Map<String, throws IOExceptionHttpStreamParam> streamParams) General form posting method. It can take zero or more string parameters and zero or more stream parameters, and posts them in an appropriate way.Authentication may be handled, but there will be no 3xx redirection.
- Parameters:
url
- destination URLcoding
- HTTP content coding; connection output should be decoded using the same valuestringParams
- name->value map for POST parameters; values will be URL encoded as requiredstreamParams
- name->parameter map for POST parameters- Returns:
- URL connection corresponding to the completed POST
- Throws:
IOException
-
postUnipartForm
public static HttpURLConnection postUnipartForm(URL url, uk.ac.starlink.util.ContentCoding coding, Map<String, String> paramMap) throws IOExceptionPerforms an HTTP form POST with a name->value map of parameters. They are posted with MIME type "application/x-www-form-urlencoded".Authentication may be handled, but there will be no 3xx redirection.
- Parameters:
url
- destination URLcoding
- HTTP content coding; connection output should be decoded using the same valueparamMap
- name->value map of parameters; values will be encoded as required- Returns:
- URL connection corresponding to the completed POST
- Throws:
IOException
-
postMultipartForm
public static HttpURLConnection postMultipartForm(URL url, uk.ac.starlink.util.ContentCoding coding, Map<String, String> stringMap, Map<String, throws IOExceptionHttpStreamParam> streamMap, String boundary) Performs an HTTP form POST with a name->value map and a name->stream map of parameters. The form is written in multipart/form-data format. See RFC 2046 Sec 5.1.Authentication may be handled, but there will be no 3xx redirection.
- Parameters:
url
- destination URLcoding
- HTTP content coding; connection output should be decoded using the same valuestringMap
- name->value map of parametersstreamMap
- name->stream map of parametersboundary
- multipart boundary; if null a default value is used- Returns:
- URL connection corresponding to the completed POST
- Throws:
IOException
-
getCurlPostEquivalent
public static String getCurlPostEquivalent(URL url, uk.ac.starlink.util.ContentCoding coding, uk.ac.starlink.auth.AuthContext context, boolean showSecret, Map<String, String> stringParams, Map<String, HttpStreamParam> streamParams, boolean isMultipart) Returns a snippet of text representing a shell invocation of thecurl(1)
command that posts a query corresponding to the given parameters.This can be a useful diagnostic tool when attempting to reproduce service invocations. Use with care however, the returned string is not guaranteed to do exactly what this java code does.
- Parameters:
url
- destination URLcoding
- HTTP content coding; connection output should be decoded using the same valuecontext
- authentication context in useshowSecret
- if true, sensitive information like passwords may appear in the output; if false they must be omittedstringParams
- name->value map for POST parameters; values will be URL encoded as requiredstreamParams
- name->parameter map for POST parametersisMultipart
- true if form POST is done using multipart/form-data encoding, false for application/x-www-form-urlencoded; must be true if streamParams is not empty- Returns:
- line of pseudo-shell script giving curl invocation
- See Also:
-
toPostedBytes
Encodes a name->value mapping as an array of bytes suitable for "application/x-www-form-urlencoded" transmission.- Parameters:
paramMap
- name->value mapping- Returns:
- byte array suitable for POSTing
-