Catalog and Archive Service - Web Services Access

Web Services Access

Accessing a Catalog and Archive server using Web Services is possible using XML-RPC over HTTP. To do so, the server must be started as the XML-RPC version. By default, such a server listens on port 1196, but setting the system property jpl.eda.archive.xmlrpc.port can change the port number.

To set up the HTTP connection, use no HTTP authentication with a POST request and text/xml MIME type. Make sure your XML-RPC client can support 15-June-1999 specification of XML-RPC. The object name is archive . The remainder of this document describes the Web Services methods the archive server supports.

Session Management

Methods:

createSession
destroySession
ping

The first thing you should do when using the archive service is create a new session. A session is identified with a string generated by the archive server. You then use this string with each archive method until you finally destroy the session. You can also call a "ping" method to test if your session is valid. Note that sessions automatically time out if you forget to destroy it.

createSession

Expects:	No arguments
Returns:	< string > : session ID
Faults:	Archi veException: if the session cannot be created

Creates a new session and returns its name.

destroySession

Expects:	< string > : session ID
Returns:	< int > : always 0
Faults:	UnknownSessionException: if the session name is unknown

Destroys the named session.

ping

Expects:	< string > : session ID
Returns:	< string > : response message
Faults:	ArchiveException: if the session name is unknown or the session cannot be pinged

Pings the named session.

Storing Products

Methods:

addBegin
openFile
writeFile
closeFile
addEnd
rollback

These methods enable you to store products into the archive. After creating a session, start by calling addBegin . You can then store as many products as needed by calling openFile , writeFile , and closeFile repeatedly. When you're done, call addEnd . If for any reason you need to abort the transaction, call rollback which will undo everything back to the point of the addBegin .

addBegin

Expects:	< string > : session ID < string > : dataset name < string > : product name < array > : product items < string > : metadata
Returns:	< int > : always 0
Faults:	ArchiveException: if the transaction cannot be started

Begins an "add" transaction. The product items is an < array > of < struct > s. Each struct should have two members:

type : < string > that identifies the type of the product to add; possible values are:
- FILE_METADATA : metadata contained in one of the product files
- FILE_DATA_LOCAL : product data contained in the client's local filesystem
- FILE_DATA_REMOTE : product data contained elsewhere
In nearly all cases, you want to use FILE_DATA_LOCAL (for products in files) or FILE_METADATA (for product metadata stored in a file).
reference : < string > that locates the product data or metadata. In nearly all cases, you want to use a string of the form file:// path-to-file to point to a file in the filesystem.

openFile

Expects:	< string > : session ID < int > : file number < string > : mode
Returns:	< int > : always 0
Faults:	ArchiveException: if the file cannot be opened

Opens a file to store into the archive server. Call this after calling addBegin . Call this as many times as structs you passed in the product items array in the addBegin call. The file number corresponds with its matching entry in the product items array. The mode is either READ or WRITE . When storing products, always set this value to WRITE .

Once you call openFile , you can upload the product data by repeatedly calling writeFile . Only one file can be open at a time. Call closeFile once you've uploaded the complete file.

writeFile

Expects:	< string > : session ID < base64 > : fragment data < int > : offset < int > : length
Returns:	< int > : always 0
Faults:	ArchiveException: if the fragment can't be stored

Writes a fragment into an open file. The data comes from the base64-encoded byte array. The offset tells where in the array the server will start copying data into the archive. The length tells how many bytes out of the array to copy. Call this method repeatedly until you've uploaded the entire file, then call closeFile .

closeFile

Expects:	< string > : session ID
Returns:	< int > : always 0
Faults:	ArchiveException: if the file can't be closed

Closes any current ly open file.

rollback

Expects:	< string > : session ID
Returns:	< int > : always 0
Faults:	UnknownSessionException: if the file can't be closed

Aborts any changes to the archive since the session's most recent call to addBegin . No products or metadata are stored.

Retrieving Products

Methods:

getBegin
openFile
readFile
closeFile
getEnd

These methods enable you to retrieve products from the archive. After creating a session, start by calling getBegin . You can then retrieve as many products as needed by calling openFile , readFile , and closeFile repeatedly. When you're done, call getEnd .

getBegin

Expects:	< string > : session ID < string > : dataset name < string > : product name < int > : version number
Returns:	< array > : array of < struct > s describing the types and references of each file comprising the product
Faults:	ArchiveException: if an error occurs

Call this method to start retrieving a version of a named product from a dataset . This method returns an < array > of < struct > s having the same composition as described above for addBegin . There's one struct for each file that comprises the product.

You can then call openFile to open one of the files of the product; pass the READ string as the mode in which to open the file (see openFile above). Call readFile to retrieve the file's contents (see readFile below). Finally, call closeFile to close the open file (see closeFile above).

readFile

Expects:	< string > : session ID
Returns:	< base64 > : contents the currently open file
Faults:	ArchiveException: if an error occurs

Call this method after calling openFile with the READ mode to retrieve a file. The entire file contents is returned as a base-64 binary object.