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:
  • Field Details

    • 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 Details

    • UwsJob

      public UwsJob(URL jobUrl)
      Constructor.
      Parameters:
      jobUrl - the UWS {jobs}/(job-id) URL containing the details of this job
  • 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