Class UwsJob


  • public class UwsJob
    extends java.lang.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 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 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 Description
      UwsJob​(java.net.URL jobUrl)
      Constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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​(java.lang.String jobListUrl, java.util.Map<java.lang.String,​java.lang.String> stringParamMap, java.util.Map<java.lang.String,​HttpStreamParam> streamParamMap)
      Submits a job to a UWS service and returns a new UwsJob object.
      static java.lang.String getCurlPostEquivalent​(java.net.URL url, uk.ac.starlink.util.ContentCoding coding, java.util.Map<java.lang.String,​java.lang.String> stringParams, java.util.Map<java.lang.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.
      java.lang.String getJobId()
      Returns the server-assigned job-id for this job.
      java.net.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​(java.lang.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 java.net.HttpURLConnection postForm​(java.net.URL url, uk.ac.starlink.util.ContentCoding coding, java.util.Map<java.lang.String,​java.lang.String> stringParams, java.util.Map<java.lang.String,​HttpStreamParam> streamParams)
      General form posting method.
      static java.net.HttpURLConnection postMultipartForm​(java.net.URL url, uk.ac.starlink.util.ContentCoding coding, java.util.Map<java.lang.String,​java.lang.String> stringMap, java.util.Map<java.lang.String,​HttpStreamParam> streamMap, java.lang.String boundary)
      Performs an HTTP form POST with a name->value map and a name->stream map of parameters.
      void postPhase​(java.lang.String phase)
      Posts a phase for this job.
      static java.net.HttpURLConnection postUnipartForm​(java.net.URL url, uk.ac.starlink.util.ContentCoding coding, java.util.Map<java.lang.String,​java.lang.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​(java.util.Map<java.lang.String,​java.lang.String> paramMap)
      Encodes a name->value mapping as an array of bytes suitable for "application/x-www-form-urlencoded" transmission.
      java.lang.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​(java.net.URL jobUrl)
        Constructor.
        Parameters:
        jobUrl - the UWS {jobs}/(job-id) URL containing the details of this job
    • Method Detail

      • getJobUrl

        public java.net.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
      • 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​(java.lang.String phase)
                       throws java.io.IOException
        Posts a phase for this job.
        Parameters:
        phase - UWS job phase to assign
        Throws:
        java.io.IOException
      • postDestruction

        public void postDestruction​(java.lang.String epoch)
                             throws java.io.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:
        java.io.IOException
      • postExecutionDuration

        public void postExecutionDuration​(long nsec)
                                   throws java.io.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:
        java.io.IOException
      • start

        public void start()
                   throws java.io.IOException
        Starts the job by posting the RUN phase.
        Throws:
        UwsJob.UnexpectedResponseException - if HTTP responses other than UWS mandated ones occur
        java.io.IOException
      • waitForFinish

        public UwsJobInfo waitForFinish​(long pollMillis)
                                 throws java.io.IOException,
                                        java.lang.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
        java.io.IOException
        java.lang.InterruptedException
      • readInfo

        public UwsJobInfo readInfo()
                            throws java.io.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:
        java.io.IOException
      • readInfoBlocking

        public UwsJobInfo readInfoBlocking​(int timeoutSec,
                                           UwsJobInfo lastInfo)
                                    throws java.io.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:
        java.io.IOException
      • postDelete

        public void postDelete()
                        throws java.io.IOException
        Posts deletion of this job to the server.
        Throws:
        java.io.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 java.lang.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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • createJob

        public static UwsJob createJob​(java.lang.String jobListUrl,
                                       java.util.Map<java.lang.String,​java.lang.String> stringParamMap,
                                       java.util.Map<java.lang.String,​HttpStreamParam> streamParamMap)
                                throws java.io.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
        java.io.IOException - if some other IOException occurs
      • postForm

        public static java.net.HttpURLConnection postForm​(java.net.URL url,
                                                          uk.ac.starlink.util.ContentCoding coding,
                                                          java.util.Map<java.lang.String,​java.lang.String> stringParams,
                                                          java.util.Map<java.lang.String,​HttpStreamParam> streamParams)
                                                   throws java.io.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:
        java.io.IOException
      • postUnipartForm

        public static java.net.HttpURLConnection postUnipartForm​(java.net.URL url,
                                                                 uk.ac.starlink.util.ContentCoding coding,
                                                                 java.util.Map<java.lang.String,​java.lang.String> paramMap)
                                                          throws java.io.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:
        java.io.IOException
      • postMultipartForm

        public static java.net.HttpURLConnection postMultipartForm​(java.net.URL url,
                                                                   uk.ac.starlink.util.ContentCoding coding,
                                                                   java.util.Map<java.lang.String,​java.lang.String> stringMap,
                                                                   java.util.Map<java.lang.String,​HttpStreamParam> streamMap,
                                                                   java.lang.String boundary)
                                                            throws java.io.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:
        java.io.IOException
      • getCurlPostEquivalent

        public static java.lang.String getCurlPostEquivalent​(java.net.URL url,
                                                             uk.ac.starlink.util.ContentCoding coding,
                                                             java.util.Map<java.lang.String,​java.lang.String> stringParams,
                                                             java.util.Map<java.lang.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​(java.util.Map<java.lang.String,​java.lang.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