ArchiveClient (Catalog and Archive Service 2.0.2 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

jpl.eda.archive
Class ArchiveClient

java.lang.Object
  jpl.eda.archive.ArchiveClient

public class ArchiveClient
extends java.lang.Object

This class serves as the client interface to the Catalog and Archive Service.

This class uses the following property:

jpl.eda.archive.chunkSize
May contain an integer representing the size of the chunks to send to the server. Defaults to 32768.

Version:: $Revision: 1.5 $
Author:: D. Crichton, S. Hardman

Constructor Summary
`ArchiveClient(java.lang.String archiveServiceName)` Constructor given an Archive Service name.

Method Summary
`int`	`add(java.lang.String datasetName, java.lang.String productName, ProductList productList, java.lang.String metadata)` Add a product to the archive.
`void`	`close(java.lang.String id)` Notify the server that a particular file transfer has completed via the `retrieveChunk()` method.
`void`	`delete(int productId)` Delete a product from the archive.
`void`	`delete(java.lang.String datasetName, java.lang.String productName)` Delete all versions of a product from the archive.
`void`	`delete(java.lang.String datasetName, java.lang.String productName, int productVersion)` Delete a product from the archive.
`ProductList`	`get(int productId, java.lang.String pathSpec)` Get the product from the archive.
`ProductList`	`get(java.lang.String datasetName, java.lang.String productName, int productVersion, java.lang.String pathSpec)` Get the product from the archive.
`ProductList`	`get(java.lang.String datasetName, java.lang.String productName, java.lang.String pathSpec)` Get the latest version of the product from the archive.
`int`	`getId(java.lang.String datasetName, java.lang.String productName, int productVersion)` Get the product identifier for the product.
`ProductList`	`getList(int productId)` Get the item list for the product from the archive.
`java.lang.String`	`getMetadata(int productId)` Get the XML formatted metadata for the product.
`java.lang.String`	`getMetadata(java.lang.String datasetName, java.lang.String productName)` Get the XML formatted metadata for the product with the latest version.
`java.lang.String`	`getMetadata(java.lang.String datasetName, java.lang.String productName, int productVersion)` Get the XML formatted metadata for the product.
`java.util.List`	`getProfiles(jpl.eda.xmlquery.XMLQuery query)` Query for products that match the specified criteria across all datasets.
`java.util.List`	`getProfiles(jpl.eda.xmlquery.XMLQuery query, java.lang.String datasetName)` Query for products that match the specified criteria for the given dataset.
`static void`	`main(java.lang.String[] argv)` Execute the archive client.
`java.lang.String`	`ping()` Ping the server.
`void`	`queue()` Check the queue and execute any tasks that have exceeded their wait time.
`byte[]`	`retrieveChunk(java.lang.String id, long offset, int length)` Retrieve a fragment of the data from the specified file.
`void`	`updateMetadata(int productId, java.lang.String metadata)` Update the database with the XML formatted metadata for the product.

Methods inherited from class java.lang.Object

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

Constructor Detail

ArchiveClient

public ArchiveClient(java.lang.String archiveServiceName)
              throws ArchiveException

Constructor given an Archive Service name. This constructor finds the Archive Service object from the naming service and makes it available for the client's use.
Parameters:: archiveServiceName - The name of the archive service.
Throws:: ArchiveException - If the object found was not the Archive Service.

Method Detail

add

public int add(java.lang.String datasetName,
               java.lang.String productName,
               ProductList productList,
               java.lang.String metadata)
        throws ArchiveException

Add a product to the archive.

Parameters:

datasetName - The name of the dataset for the product to be added.

productName - The name of the product to be added. A product name must begin with a letter, number or a period. Every other character in the name must be a letter, number, period, underscore, dash or colon.

productList - The list of items for the product which consists of zero, one or more productReference and productType pairs.

productReference - The URL reference to a product item. Example value: file:///home/user/test.xml or http://cas.jpl.nasa.gov/dtd/metadata.dtd.
productType - The type of the product item. Valid values:
- FILE_METADATA - An XML file conforming to the CAS metadata structure which will be parsed with the resulting element/value pairs stored in the catalog.
- FILE_DATA_LOCAL - Any file intended to be transferred from the client to the server for local storage.
- FILE_DATA_REMOTE - Any file intended to be referenced from its current location, instead of being transferred to the server.

metadata - This is a string representation of the XML metadata structure. This parameter may be null.

Returns:

The version number of the product.

Throws:

ArchiveException - If an exception occurs validating the dataset or product name, or reading or writing the files.

getId

public int getId(java.lang.String datasetName,
                 java.lang.String productName,
                 int productVersion)
          throws ArchiveException

Get the product identifier for the product.

Parameters:: datasetName - The name of the dataset for the product.; productName - The name of the product.; productVersion - The version number of the product.
Returns:: The product identifier.
Throws:: ArchiveException - If retrieving the identifier from the server fails.

get

public ProductList get(java.lang.String datasetName,
                       java.lang.String productName,
                       java.lang.String pathSpec)
                throws ArchiveException

Get the latest version of the product from the archive.

Parameters:: datasetName - The name of the dataset for the product to be retrieved.; productName - The name of the product to be retrieved.; pathSpec - The directory location where the retrieved files should be placed.
Returns:: The list of product item references associated with the product to be retrieved.
Throws:: ArchiveException - If retrieving the product from the server fails or a malformed reference is encountered.

get

public ProductList get(java.lang.String datasetName,
                       java.lang.String productName,
                       int productVersion,
                       java.lang.String pathSpec)
                throws ArchiveException

Get the product from the archive.

Parameters:: datasetName - The name of the dataset for the product to be retrieved.; productName - The name of the product to be retrieved.; productVersion - The version number of the product to be retrieved.; pathSpec - The directory location where the retrieved files should be placed.
Returns:: The list of product item references associated with the product to be retrieved.
Throws:: ArchiveException - If retrieving the product from the server fails or a malformed reference is encountered.

get

public ProductList get(int productId,
                       java.lang.String pathSpec)
                throws ArchiveException

Get the product from the archive.

Parameters:: productId - The identifier for the product to be retrieved.; pathSpec - The directory location where the retrieved files should be placed.
Returns:: The list of product item references associated with the product to be retrieved.
Throws:: ArchiveException - If retrieving the product from the server fails or a malformed reference is encountered.

getList

public ProductList getList(int productId)
                    throws ArchiveException

Get the item list for the product from the archive. This method is intended to be called by the ArchiveProductHandler class and does not transfer the files.

Parameters:: productId - The identifier for the product to be retrieved.
Returns:: The list of product item references associated with the product to be retrieved.
Throws:: ArchiveException - If retrieving the product list from the server fails or a malformed reference is encountered.

getMetadata

public java.lang.String getMetadata(java.lang.String datasetName,
                                    java.lang.String productName)
                             throws ArchiveException

Get the XML formatted metadata for the product with the latest version.

Parameters:: datasetName - The name of the dataset for the product.; productName - The name of the product.
Returns:: An XML formatted representation of the metadata.
Throws:: ArchiveException - If retrieving the metadata from the server fails.

getMetadata

public java.lang.String getMetadata(java.lang.String datasetName,
                                    java.lang.String productName,
                                    int productVersion)
                             throws ArchiveException

Get the XML formatted metadata for the product.

Parameters:: datasetName - The name of the dataset for the product.; productName - The name of the product.; productVersion - The version of the product.
Returns:: An XML formatted representation of the metadata.
Throws:: ArchiveException - If retrieving the metadata from the server fails.

getMetadata

public java.lang.String getMetadata(int productId)
                             throws ArchiveException

Get the XML formatted metadata for the product.

Parameters:: productId - The identifier of the product.
Returns:: An XML formatted representation of the metadata.
Throws:: ArchiveException - If retrieving the metadata from the server fails.

updateMetadata

public void updateMetadata(int productId,
                           java.lang.String metadata)
                    throws ArchiveException

Update the database with the XML formatted metadata for the product.

Parameters:: productId - The identifier of the product.; metadata - This is a string representation of the XML metadata structure.
Throws:: ArchiveException - If updating the metadata on the server fails.

delete

public void delete(java.lang.String datasetName,
                   java.lang.String productName)
            throws ArchiveException

Delete all versions of a product from the archive.

Parameters:: datasetName - The name of the dataset for the products to be deleted.; productName - The name of the products to be deleted.
Throws:: ArchiveException - If the delete on server fails.

delete

public void delete(java.lang.String datasetName,
                   java.lang.String productName,
                   int productVersion)
            throws ArchiveException

Delete a product from the archive.

Parameters:: datasetName - The name of the dataset for the product to be deleted.; productName - The name of the product to be deleted.; productVersion - The version number of product to be deleted.
Throws:: ArchiveException - If the delete on server fails.

delete

public void delete(int productId)
            throws ArchiveException

Delete a product from the archive.

Parameters:: productId - The identifier of product to be deleted.
Throws:: ArchiveException - If the delete on server fails.

queue

public void queue()
           throws ArchiveException

Check the queue and execute any tasks that have exceeded their wait time.

Throws:: ArchiveException - If the server throws an exception.

ping

public java.lang.String ping()
                      throws ArchiveException

Ping the server.

Returns:: A message identifying the server.
Throws:: ArchiveException - If the server throws an exception.

getProfiles

public java.util.List getProfiles(jpl.eda.xmlquery.XMLQuery query)
                           throws ArchiveException

Query for products that match the specified criteria across all datasets. Return the metadata describing those products in Profile format.

Parameters:: query - The XMLQuery object.
Returns:: A list of Profile objects.
Throws:: ArchiveException - If the server throws an exception.

getProfiles

public java.util.List getProfiles(jpl.eda.xmlquery.XMLQuery query,
                                  java.lang.String datasetName)
                           throws ArchiveException

Query for products that match the specified criteria for the given dataset. Return the metadata describing those products in Profile format.

Parameters:: query - The XMLQuery object.; datasetName - The name of the dataset to query.
Returns:: A list of Profile objects.
Throws:: ArchiveException - If the server throws an exception.

retrieveChunk

public byte[] retrieveChunk(java.lang.String id,
                            long offset,
                            int length)
                     throws ArchiveException

Retrieve a fragment of the data from the specified file.

Parameters:: id - The unique identifier for the file which is the archive reference.; offset - Skip into the file the specified number of bytes.; length - The number of bytes to read from the file.
Returns:: A fragment of the data in the file.
Throws:: ArchiveException - If the server throws an exception.

close

public void close(java.lang.String id)
           throws ArchiveException

Notify the server that a particular file transfer has completed via the retrieveChunk() method.

Parameters:: id - The unique identifier for the file which is the archive reference.
Throws:: ArchiveException - If the id parameter is invalid.

main

public static void main(java.lang.String[] argv)

Execute the archive client.

See the description for the specific method called by the event for detailed information regarding the arguments. Where an argument value varies from the method, the argument description is detailed here. The minimum command-line arguments are as follows:

serverName - The name of the Catalog and Archive Server where the event will be performed.
event - The type of event to perform. The valid values are add, getId, getByName, getByVersion, getById, getList, getMetadataByName, getMetadataByVersion, getMetadataById, deleteByName, deleteByVersion, deleteById, getProfiles, queue, or ping.

The add event calls the add() method in this class and expects these additional arguments:
<datasetName> <productName> [<productReference_1> <productType_1> ... <productReference_n> <productType_n>] [<metadata>]

The getId event calls the getId() method in this class and expects these additional arguments:
<datasetName> <productName> <productVersion>

The getBy* events call the appropriate get() method in this class and expect these additional arguments:
getByName <datasetName> <productName> [<pathSpec>]
getByVersion <datasetName> <productName> <productVersion> [<pathSpec>]
getById <productId> [<pathSpec>]

dirName - The directory location where the retrieved files should be placed. The default value is the current working directory.

The getList event calls the getList() method in this class and expects this additional argument:
<productId>

The getMetadata* events call the appropriate getMetadata() method in this class and expect these additional arguments:
getMetadataByName <datasetName> <productName>
getMetadataByVersion <datasetName> <productName> <productVersion>
getMetadataById <productId>

The updateMetadata event calls the updateMetadata() method in this class and expects these additional arguments:
<productId> <metadata>

The delete* events call the appropriate delete() method in this class and expect these additional arguments:
deleteByName <datasetName> <productName>
deleteByVersion <datasetName> <productName> <productVersion>
deleteById <productId>

The getProfiles event calls the appropriate getProfiles() method in this class and expects these additional arguments:
<query> [<datasetName>]

query - A keyword query string. Example value: "CAS.ProductName LIKE EDM".
datasetName - The name of the dataset. This argument is optional and if not provided, all datasets will be queried.

The queue and ping events call the queue() and ping() methods, respectively, and require no additional arguments.

The program exits with status 0 on success, 1 on failure.

Parameters:: argv - The command-line arguments.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

jpl.eda.archive Class ArchiveClient

ArchiveClient

add

getId

get

get

get

getList

getMetadata

getMetadata

getMetadata

updateMetadata

delete

delete

delete

queue

ping

getProfiles

getProfiles

retrieveChunk

close

main

jpl.eda.archive
Class ArchiveClient