public class UwsJob extends Object
Modifier and Type | Class and Description |
---|---|
static interface |
UwsJob.JobWatcher
Callback interface for objects wanting to be notified of job status
changes.
|
static class |
UwsJob.UnexpectedResponseException
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.
|
Modifier and Type | Field and Description |
---|---|
static int |
HTTP_CHUNK_SIZE
Chunk size for HTTP transfer encoding; if <=0, don't chunk.
|
static boolean |
TRIM_TEXT
Whether to trim whitespace from line text responses (like job/phase).
|
Modifier and Type | Method and Description |
---|---|
void |
addJobWatcher(UwsJob.JobWatcher watcher)
Adds a callback which will be invoked whenever this job's phase
is found to have changed.
|
void |
attemptDelete()
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,
ContentCoding coding,
AuthContext context,
boolean showSecret,
Map<String,String> stringParams,
Map<String,HttpStreamParam> streamParams)
Returns a snippet of text representing a shell invocation of the
curl(1) command that posts a query corresponding
to the given parameters. |
boolean |
getDeleteOnExit()
Indicates whether this job will be deleted when the JVM exits,
if it has not been deleted before.
|
String |
getJobId()
Returns the server-assigned job-id for this job.
|
URL |
getJobUrl()
Returns the URL for this job.
|
UwsJobInfo |
getLastInfo()
Returns the most recently read job state.
|
void |
postDelete()
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,
ContentCoding coding,
Map<String,String> stringParams,
Map<String,HttpStreamParam> streamParams)
General form posting method.
|
static HttpURLConnection |
postMultipartForm(URL url,
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 |
postPhase(String phase)
Posts a phase for this job.
|
static HttpURLConnection |
postUnipartForm(URL url,
ContentCoding coding,
Map<String,String> paramMap)
Performs an HTTP form POST with a name->value map of parameters.
|
UwsJobInfo |
readInfo()
Reads the current status document for this job from the server
and both stores and returns the result.
|
UwsJobInfo |
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 by
addJobWatcher(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.
|
String |
toString() |
UwsJobInfo |
waitForFinish(long pollMillis)
Blocks until the job has reached a completion phase.
|
public static int HTTP_CHUNK_SIZE
public static boolean TRIM_TEXT
public UwsJob(URL jobUrl)
jobUrl
- the UWS {jobs}/(job-id) URL containing
the details of this jobpublic URL getJobUrl()
public void addJobWatcher(UwsJob.JobWatcher watcher)
watcher
- runnable to be notified on job phase changepublic void removeJobWatcher(UwsJob.JobWatcher watcher)
addJobWatcher(uk.ac.starlink.vo.UwsJob.JobWatcher)
.
Has no effect if watcher
is not currently registered.watcher
- runnable to be removedpublic UwsJobInfo getLastInfo()
public void postPhase(String phase) throws IOException
phase
- UWS job phase to assignIOException
public void postDestruction(String epoch) throws IOException
epoch
- destruction time which should be an ISO-8601 string;
it is passed directly to the serviceIOException
public void postExecutionDuration(long nsec) throws IOException
nsec
- number of elapsed seconds for which job is permitted
to run; zero is supposed to mean unlimitedIOException
public void start() throws IOException
UwsJob.UnexpectedResponseException
- if HTTP responses other than
UWS mandated ones occurIOException
public UwsJobInfo waitForFinish(long pollMillis) throws IOException, InterruptedException
pollMillis
- polling time in milliseconds to assess
job completion, if polling is requiredUwsJob.UnexpectedResponseException
- if HTTP responses other than
UWS mandated ones occurIOException
InterruptedException
public UwsJobInfo readInfo() throws IOException
getLastInfo()
method.IOException
public UwsJobInfo readInfoBlocking(int timeoutSec, UwsJobInfo lastInfo) throws IOException
getLastInfo()
method.timeoutSec
- maximum advised timeout in secondslastInfo
- last known job statusIOException
public void postDelete() throws IOException
IOException
- if job deletion failed for some reasonpublic void attemptDelete()
public void setDeleteOnExit(boolean delete)
delete
- true to delete on exit, false otherwisepublic boolean getDeleteOnExit()
public String getJobId()
public static UwsJob createJob(String jobListUrl, Map<String,String> stringParamMap, Map<String,HttpStreamParam> streamParamMap) throws IOException
jobListUrl
- base (job list) URL for UWS servicestringParamMap
- map of text parametersstreamParamMap
- map of streamed parametersUwsJob.UnexpectedResponseException
- if a non-303 response was receivedIOException
- if some other IOException occurspublic static HttpURLConnection postForm(URL url, ContentCoding coding, Map<String,String> stringParams, Map<String,HttpStreamParam> streamParams) throws IOException
Authentication may be handled, but there will be no 3xx redirection.
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 parametersIOException
public static HttpURLConnection postUnipartForm(URL url, ContentCoding coding, Map<String,String> paramMap) throws IOException
Authentication may be handled, but there will be no 3xx redirection.
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 requiredIOException
public static HttpURLConnection postMultipartForm(URL url, ContentCoding coding, Map<String,String> stringMap, Map<String,HttpStreamParam> streamMap, String boundary) throws IOException
Authentication may be handled, but there will be no 3xx redirection.
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 usedIOException
public static String getCurlPostEquivalent(URL url, ContentCoding coding, AuthContext context, boolean showSecret, Map<String,String> stringParams, Map<String,HttpStreamParam> streamParams)
curl(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.
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 parameterspostForm(java.net.URL, java.lang.String, java.lang.String)
Copyright © 2024 Central Laboratory of the Research Councils. All Rights Reserved.