public interface JobInfo
extends java.io.Serializable
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.
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. |
java.lang.String getXML(java.lang.String newLinePrefix) throws UWSException
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:
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.
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.UWSException
- If any error occurs while building the XML
representation of this jobInfo.void write(javax.servlet.http.HttpServletResponse response) throws java.io.IOException, UWSException
{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.
response
- HTTP response in which the jobInfo content must be
written.java.io.IOException
- If there is any error while writing the jobInfo
content.UWSException
- If there is any error while formating the jobInfo
content.void setJob(UWSJob myJob)
JobInfo
that it is now owned by the given job.myJob
- The new owner of this JobInfo
.
This parameter may be NULL.void destroy() throws UWSException
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.
UWSException
- If all associated resources can not be freed.