Class UwsJob

Method Details

• 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, uk.ac.starlink.util.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.

  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, uk.ac.starlink.util.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".

  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, uk.ac.starlink.util.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.

  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, uk.ac.starlink.util.ContentCoding coding, 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.

  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

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

  streamParams - name->parameter map for POST parameters

  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