uk.ac.starlink.vo

Class UwsJob

java.lang.Object

uk.ac.starlink.vo.UwsJob

public class UwsJob
extends Object

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:

IVOA UWS Recommendation

Nested Class Summary

Nested Classes

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.

Field Summary

Fields

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).

Constructor Summary

Constructors

Constructor and Description
UwsJob(URL jobUrl) Constructor.

Method Summary

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, boolean isMultipart) 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

HTTP_CHUNK_SIZE

public static int HTTP_CHUNK_SIZE

Chunk size for HTTP transfer encoding; if <=0, don't chunk.

TRIM_TEXT

public static boolean TRIM_TEXT

Whether 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 Detail

UwsJob

public UwsJob(URL jobUrl)

Constructor.

Parameters:

jobUrl - the UWS {jobs}/(job-id) URL containing the details of this job

Method Detail

getJobUrl

public URL 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

public void addJobWatcher(UwsJob.JobWatcher watcher)

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

public void removeJobWatcher(UwsJob.JobWatcher watcher)

Removes a callback previously added by addJobWatcher(uk.ac.starlink.vo.UwsJob.JobWatcher). Has no effect if watcher is not currently registered.

Parameters:

watcher - runnable to be removed

getLastInfo

public UwsJobInfo getLastInfo()

Returns the most recently read job state. Invoking this method does not cause the state to be read.

Returns:

job state object

postPhase

public void postPhase(String phase)
               throws IOException

Posts a phase for this job.

Parameters:

phase - UWS job phase to assign

Throws:

IOException

postDestruction

public void postDestruction(String epoch)
                     throws IOException

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

public void postExecutionDuration(long nsec)
                           throws IOException

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

public void start()
           throws IOException

Starts the job by posting the RUN phase.

Throws:

UwsJob.UnexpectedResponseException - if HTTP responses other than UWS mandated ones occur

IOException

waitForFinish

public UwsJobInfo waitForFinish(long pollMillis)
                         throws IOException,
                                InterruptedException

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 occur

IOException

InterruptedException

readInfo

public UwsJobInfo readInfo()
                    throws IOException

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 the getLastInfo() method.

Returns:

job status

Throws:

IOException

readInfoBlocking

public UwsJobInfo readInfoBlocking(int timeoutSec,
                                   UwsJobInfo lastInfo)
                            throws IOException

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 the getLastInfo() method.

Parameters:

timeoutSec - maximum advised timeout in seconds

lastInfo - last known job status

Returns:

job status

Throws:

IOException

postDelete

public void postDelete()
                throws IOException

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

public String getJobId()

Returns the server-assigned job-id for this job. It is the final part of the Job URL.

Returns:

job ID

toString

public String toString()

Overrides:

toString in class Object

createJob

public static UwsJob createJob(String jobListUrl,
                               Map<String,String> stringParamMap,
                               Map<String,HttpStreamParam> streamParamMap)
                        throws IOException

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 service

stringParamMap - map of text parameters

streamParamMap - map of streamed parameters

Returns:

new UWS job

Throws:

UwsJob.UnexpectedResponseException - if a non-303 response was received

IOException - if some other IOException occurs

postForm

public static HttpURLConnection postForm(URL url,
                                         ContentCoding coding,
                                         Map<String,String> stringParams,
                                         Map<String,HttpStreamParam> streamParams)
                                  throws IOException

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 URL

coding - HTTP content coding; connection output should be decoded using the same value

stringParams - name->value map for POST parameters; values will be URL encoded as required

streamParams - name->parameter map for POST parameters

Returns:

URL connection corresponding to the completed POST

Throws:

IOException

postUnipartForm

public static HttpURLConnection postUnipartForm(URL url,
                                                ContentCoding coding,
                                                Map<String,String> paramMap)
                                         throws IOException

Performs 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 URL

coding - HTTP content coding; connection output should be decoded using the same value

paramMap - 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,
                                                  ContentCoding coding,
                                                  Map<String,String> stringMap,
                                                  Map<String,HttpStreamParam> streamMap,
                                                  String boundary)
                                           throws IOException

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 URL

coding - HTTP content coding; connection output should be decoded using the same value

stringMap - name->value map of parameters

streamMap - name->stream map of parameters

boundary - 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,
                                           ContentCoding coding,
                                           AuthContext context,
                                           boolean showSecret,
                                           Map<String,String> stringParams,
                                           Map<String,HttpStreamParam> streamParams,
                                           boolean isMultipart)

Returns a snippet of text representing a shell invocation of the 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.

Parameters:

url - destination URL

coding - HTTP content coding; connection output should be decoded using the same value

context - authentication context in use

showSecret - if true, sensitive information like passwords may appear in the output; if false they must be omitted

stringParams - name->value map for POST parameters; values will be URL encoded as required

streamParams - name->parameter map for POST parameters

isMultipart - 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:

curl, postForm(java.net.URL, java.lang.String, java.lang.String)

toPostedBytes

public 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.

Parameters:

paramMap - name->value mapping

Returns:

byte array suitable for POSTing