uws.job.jobInfo

Interface JobInfo

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

SingleValueJobInfo, XMLJobInfo

public interface JobInfo
extends java.io.Serializable

API wrapping an object which provides more information about a job.

It can be a simple information (e.g. job progress ; see SingleValueJobInfo) or a whole job description instead of parameters as described in REC-UWS-1.0, "1.3. Job description language, service contracts and universality" (e.g. an XML document ; see XMLJobInfo).

Representation

As requested by REC-UWS-1.0, the function getXML(String) must return an XML representation of this jobInfo, but that does not mean that the additional job information have to be in XML ; they can be an XML, a .txt, an image, ... The function getXML(String) just needs to return a representation of this jobInfo: either the jobInfo content itself or a link to access it into details.

The function write(HttpServletResponse) is only used when ONLY the content of a job's jobInfo is requested: with the URL {uws-root}/{job-list}/{job-id}/jobInfo. It allows to return the real content of this jobInfo (if not already the XML returned by getXML(String)).

Resource management

In case the jobInfo is associated with other resources (e.g. memory, file, ...), the function destroy() must be able to discard them. This function is always called at job destruction.

Backup

The implementation of a JobInfo being free, the only viable way to backup a such object is by Java Class Serialization (see Serializable, ObjectOutputStream and ObjectInputStream). A default serialization is already implemented, but it can be customized by overriding the following functions:

• private void writeObject(java.io.ObjectOutputStream out) throws IOException
• private void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException;
• private void readObjectNoData() throws ObjectStreamException;

See the Javadoc of Serializable for more details.

Link with UWSJob

Once a JobInfo is attached to a job (thanks to UWSJob.setJobInfo(JobInfo)), the function setJob(UWSJob) is called. In some implementation, no action is needed (see SingleValueJobInfo), but in some others it may be required to either keep a link with the parent job or to execute some special action.

Warning: Since a JobInfo must be Serializable it is recommended to flag complex objects like UWSJob as transient as much as possible in order to make the backup and restore processes lighter. Some objects like the parent job are naturally restored when setJob(UWSJob) is called. See XMLJobInfo for a concrete example.

Since:

4.2

Version:

4.2 (06/2017)

Author:

Grégory Mantelet (ARI)

Method Summary

Modifier and Type	Method and Description
void	destroy() Free/Discard any resource associated with this JobInfo.
java.lang.String	getXML(java.lang.String newLinePrefix) Get the XML representation of this JobInfo.
void	setJob(UWSJob myJob) Notify this JobInfo that it is now owned by the given job.
void	write(javax.servlet.http.HttpServletResponse response) Write the content of this jobInfo as a complete HTTP response when the URL {uws-root}/{job-list}/{job-id}/jobInfo is requested.

Method Detail

getXML

java.lang.String getXML(java.lang.String newLinePrefix)
                 throws UWSException

Get the XML representation of this JobInfo.

Note 1: This function does not force the jobInfo to be in XML but asks for a piece of XML document to append to the XML representation of a job and representing this jobInfo. It may be a full serialization of it or merely a link (see Xlink) toward a complete document (XML or not).

Note 2: The returned piece of XML can refer to the following XML schemas:

• "http://www.ivoa.net/xml/UWS/v1.0" (no prefix),
• "http://www.w3.org/1999/xlink" (prefix: xlink),
• "http://www.w3.org/2001/XMLSchema" (prefix: xs),
• "http://www.w3.org/2001/XMLSchema-instance" (prefix: xsi).

If more namespaces are needed they should be specified directly at the root of the XML returned by this function (if possible with a valid xsi:schemaLocation). An alternative would be to extend XMLSerializer in order to append the needed namespaces to the root XML node of any formatted XML documents.

Parameters:

newLinePrefix - Characters (generally white-spaces) that should prefix all new line of the returned piece of XML. New line characters should also be included in this string ; if not, the returned XML should be on a single line. This parameter may be NULL.

Returns:

XML representation of this jobInfo.

Throws:

UWSException - If any error occurs while building the XML representation of this jobInfo.

write

void write(javax.servlet.http.HttpServletResponse response)
    throws java.io.IOException,
           UWSException

Write the content of this jobInfo as a complete HTTP response when the URL {uws-root}/{job-list}/{job-id}/jobInfo is requested.

Important: At least the Content-Type, the Content-Length and Character-Encoding should be set in addition of the response content.

Note: If formatted into XML, the root node of the returned document may be the UWS node "jobInfo" or not, depending on your desired implementation. Since the UWS standard does not specify any way to retrieve individually a jobInfo, this part is left here totally free to the developer will.

Parameters:

response - HTTP response in which the jobInfo content must be written.

Throws:

java.io.IOException - If there is any error while writing the jobInfo content.

UWSException - If there is any error while formating the jobInfo content.

setJob

void setJob(UWSJob myJob)

Notify this JobInfo that it is now owned by the given job.

Parameters:

myJob - The new owner of this JobInfo. This parameter may be NULL.

destroy

void destroy()
      throws UWSException

Free/Discard any resource associated with this JobInfo.

Note: This function should be called only at job destruction. It particularly aims to delete any file containing the full content of this JobInfo, but it should also be used for any other kind of associated resource.

Throws:

UWSException - If all associated resources can not be freed.