uws.job.jobInfo

Class XMLJobInfo

java.lang.Object

uws.job.jobInfo.XMLJobInfo

All Implemented Interfaces:

java.io.Serializable, JobInfo

public class XMLJobInfo
extends java.lang.Object
implements JobInfo

A full XML document attached to a job.

XML representation

The document stored inside this JobInfo is considered formatted in XML. So the functions getXML(String) and write(HttpServletResponse) will return them as such.

Note 1: The represented document is supposed to be XML, but absolutely no verification is performed by XMLJobInfo.

Note 2: getXML(String) will skip the XML declaration (e.g. <?xml version="1.0" encoding="utf-8"?>) if any is provided. On the contrary, write(HttpServletResponse) will write an exact copy of the stored XML document. Both functions can be overwritten if a different behavior is needed.

Note 3: The stored XML document 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 stored XML document (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.

Internal representation and Creation

This class proposes the two following constructors, each for a different internal representation:

• XMLJobInfo(String) for an in-memory string. The given string is supposed to contained the full XML document and will be stored as such in this class. This constructor should be used only for small XML document.
• XMLJobInfo(UploadFile) for an XML file storage. The given UploadFile is supposed to give access to the complete XML document.This constructor should be used for large XML document.

Modification

By default, this implementation of JobInfo does not allow the modification of its XML document. If needed, this class should be extended with the adequate functions.

Backup/Restoration

An UploadFile can not be serialized using the Java Class Serialization mechanism because it does not implement the Serializable interface. Consequently, the given UploadFile will be marked as transient and will have to be rebuilt when needed after a restoration process.

However, it can be rebuilt only if:

1. an access to a UWSFileManager is possible.
2. the location of the file is known.

The first point (1) is fortunately possible through a UWSJob object. This object is known after attachment to a job thanks to the function setJob(UWSJob). So, a link toward the parent job should be kept ; also marked as transient: see the attribute job.

For the second point (2), the location of the file must be kept as a non-transient attribute (see location) so that being backuped with the other non-transient attributes of this class. In order to backup this location up-to-date, the function writeObject(java.io.ObjectOutputStream) updates location before the normal Java Class Serialization.

So finally, the restoration of the UploadFile will be done by getXML(String) and write(HttpServletResponse) with the function restoreFile().

Since:

4.2

Version:

4.4 (03/2019)

Author:

Grégory Mantelet (ARI;CDS)

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	content XML document represented by this JobInfo.
protected UploadFile	file Link toward the XML file represented by this JobInfo.
protected UWSJob	job The job owning this JobInfo.
protected int	length Precise length (in bytes) of the represented XML document.
protected java.lang.String	location XML file location.

Constructor Summary

Constructors

Constructor and Description
XMLJobInfo(java.lang.String smallXML) Build a JobInfo representing a small XML document.
XMLJobInfo(UploadFile xmlFile) Build a JobInfo representing a large XML document stored inside a file.

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.
protected void	restoreFile() Restore the link toward the XML file represented by 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

location

protected java.lang.String location

XML file location.

Warning: This field ONLY aims to contain the updated result of file.getLocation().

file

protected transient UploadFile file

Link toward the XML file represented by this JobInfo.

Important: This field must be used when a large XML document has to be represented by this JobInfo.

Note: It can be set only by XMLJobInfo(UploadFile). If set, content must be NULL.

content

protected java.lang.String content

XML document represented by this JobInfo.

Important: This field MUST be used ONLY for small XML document in order to keep enough memory free for the normal UWS service operations.

Note: It can be set only by XMLJobInfo(String). If set, file must be NULL.

length

protected int length

Precise length (in bytes) of the represented XML document.

job

protected transient UWSJob job

The job owning this JobInfo.

Note: This field is set only by setJob(UWSJob) and is used only by restoreFile() in order to rebuild file after a UWS service restoration.

Constructor Detail

XMLJobInfo

public XMLJobInfo(java.lang.String smallXML)
           throws java.lang.NullPointerException

Build a JobInfo representing a small XML document.

Important: This constructor should be used only for small XML document because the given string will be kept as such in memory. If the given string is too large, not enough memory will be available for normal UWS service operations.

If you estimate the XML document is too big to stay in memory, you should save it in a file and use the constructor XMLJobInfo(UploadFile).

Parameters:

smallXML - The small XML document to represent.

Throws:

java.lang.NullPointerException - If the given string is NULL or empty.

XMLJobInfo

public XMLJobInfo(UploadFile xmlFile)
           throws java.lang.NullPointerException

Build a JobInfo representing a large XML document stored inside a file.

Parameters:

xmlFile - Link toward the large XML document to represent.

Throws:

java.lang.NullPointerException - If the given file is NULL or empty.

Method Detail

getXML

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

Description copied from interface: JobInfo

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.

Specified by:

getXML in interface JobInfo

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

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

Description copied from interface: JobInfo

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.

Specified by:

write in interface JobInfo

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

public void setJob(UWSJob myJob)

Description copied from interface: JobInfo

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

Specified by:

setJob in interface JobInfo

Parameters:

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

destroy

public void destroy()
             throws UWSException

Description copied from interface: JobInfo

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.

Specified by:

destroy in interface JobInfo

Throws:

UWSException - If all associated resources can not be freed.

restoreFile

protected void restoreFile()
                    throws UWSException

Restore the link toward the XML file represented by this JobInfo.

This function has an effect only if file is NULL but not location ; indeed, such configuration can be encountered only if this XMLJobInfo has been de-serialized.

Nothing can be done if the parent job is unknown. In other words, this JobInfo has to be attached to a job first (i.e. setJob(UWSJob) has to be called first with a non-NULL parameter). If not, an exception will be thrown.

Throws:

UWSException - If this JobInfo is not attached to a job.