uk.ac.starlink.vo
Class UwsJob

java.lang.Object
  extended by 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
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
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
UwsJob(URL jobUrl)
          Constructor.
 
Method Summary
 void addPhaseWatcher(Runnable watcher)
          Adds a callback which will be invoked whenever this job's phase is read by readPhase().
 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.
 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.
 String getLastPhase()
          Returns the most recently read job phase.
 long getLastPhaseTime()
          Returns the epoch at which the job phase was last read.
 void postDelete()
          Posts deletion of this job to the server.
static HttpURLConnection postForm(URL url, Map<String,String> stringParams, Map<String,HttpStreamParam> streamParams)
          General form posting method.
static HttpURLConnection postMultipartForm(URL url, 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, Map<String,String> paramMap)
          Performs an HTTP form POST with a name->value map of parameters.
 UwsJobInfo readJob()
          Reads XML text from the job URL which describes the server's record of the current state of the job, and returns the result as a UwsJobInfo object.
 void readPhase()
          Reads the current UWS phase for this job from the server and stores the result.
 void removePhaseWatcher(Runnable watcher)
          Removes a callback previously added by addPhaseWatcher(java.lang.Runnable).
 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()
           
 String waitForFinish(long poll)
          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

getLastPhase

public String getLastPhase()
Returns the most recently read job phase. Invoking this method does not cause the phase to be read.

Returns:
phase

getLastPhaseTime

public long getLastPhaseTime()
Returns the epoch at which the job phase was last read. The return value is the value of System.currentTimeMillis() at that epoch.

Returns:
phase read time epoch in milliseconds
See Also:
getLastPhase()

postPhase

public void postPhase(String phase)
               throws IOException
Posts a phase for this job.

Parameters:
phase - UWS job phase to assign
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 String waitForFinish(long poll)
                     throws IOException,
                            InterruptedException
Blocks until the job has reached a completion phase. It is polled at the given interval.

Parameters:
poll - polling time in milliseconds to assess job completion
Returns:
final phase
Throws:
UwsJob.UnexpectedResponseException - if HTTP responses other than UWS mandated ones occur
IOException
InterruptedException

readPhase

public void readPhase()
               throws IOException
Reads the current UWS phase for this job from the server and stores the result. The result is available from the getLastPhase() method, and the associated getLastPhaseTime value is also set.

Throws:
IOException

addPhaseWatcher

public void addPhaseWatcher(Runnable watcher)
Adds a callback which will be invoked whenever this job's phase is read by readPhase(). 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

removePhaseWatcher

public void removePhaseWatcher(Runnable watcher)
Removes a callback previously added by addPhaseWatcher(java.lang.Runnable). Has no effect if watcher is not currently registered.

Parameters:
watcher - runnable to be removed

readJob

public UwsJobInfo readJob()
                   throws IOException,
                          SAXException
Reads XML text from the job URL which describes the server's record of the current state of the job, and returns the result as a UwsJobInfo object.

Returns:
job status
Throws:
IOException
SAXException

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

Parameters:
url - destination URL
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,
                                                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".

Parameters:
url - destination URL
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,
                                                  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.

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

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


Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.