Sun StorageTek 5800 System Client API Reference Manual

Java API

The 5800 system Java client library provides a simple way of communicating with 5800 system clusters. It provides programatic access to the 5800 system network protocol, which operates over HTTP. You can implement most applications using a handful of these classes, but access to “expert” features is also included.

This section discusses the following topics:

Java API Packages

The Java API is implemented in two packages:

Java API Documentation

The Java API documentation (Javadoc) is located in the SDK java/doc/htdocs directory, and can be accessed using a browser.

Basic Concepts

The root of the 5800 system Java client API is the NameValueObjectArchive class, which represents a connection to a single 5800 system server. All operations are initiated by invoking methods on a NameValueObjectArchive instance after initializing it with the address of a cluster. The fact that a cluster of machines, rather than a single server, is handling the requests is transparent to the application programmer.

A NameValueObjectArchive uses instances of the ObjectIdentifier class to uniquely identify stored data objects. That is, there is a one-to-one correspondence between instances of ObjectIdentifer and 5800 system metadata objects.


Note –

There is potentially a many-to-one relationship between metadata and data objects.


When using NameValueObjectArchive, all metadata queries are executed against a 5800 system server’s user-configurable index of name-value pair lists. This class also ensures that a metadata entry is created for every data object stored, even if no metadata is provided at store time.

An instance of the NameValueObjectArchive class functions as a proxy for the 5800 system server. Instantiation incurs some overhead in establishing communication, so reusing a single instance is the recommended practice. Multithreading is supported with the same instance.

NameValueObjectArchive also allows all metadata operations to be performed in terms of two classes that represent metadata records: SystemRecord and NameValueRecord. These classes represent 5800 system metadata entries. When using NameValueObjectArchive, every stored data object has a corresponding NameValueRecord that contains the extended attributes stored with that data object, and each NameValueRecord has a reference to its SystemRecord, which contains built-in system attributes such as data object size and creation time. In this model, all instances of ObjectIdentifer returned from store operations and metadata queries correspond directly to instances of NameValueRecord.

The results of a 5800 system metadata query are returned using instances of the QueryResultSet class, which the application can step through to retrieve metadata or identifiers. This class manages the details of fetching one batch of results after another.

Key Classes

This section provides an overview of the following key classes in the 5800 system Java client API. For more information on using the following classes, see Basic Concepts. Also see the Javadoc provided with the 5800 system SDK.

For more information on using these classes, see Basic Concepts.

NameValueObjectArchive

The NameValueObjectArchive class is the main entry point into the 5800 system. Each instance of NameValueObjectArchive provides access to a specific 5800 system server, functioning as a proxy object on which operations can be performed. Multiple simultaneous operations can be accomplished in separate threads on the same NameValueObjectArchive instance. Communication with the 5800 system server is entirely by means of HTTP requests. A pool of HTTP connections is maintained for efficiency.

A NameValueObjectArchive instance enables you to store, retrieve, query and delete object data and associated metadata records. Metadata is associated with an object in a set of name-value pairs (see NameValueRecord). Metadata records can be used to associate application-specific information with the raw data, such as name, mime type, or purge date. Metadata records consist of structured data that can be queried. Object data is opaque to the 5800 system.

A NameValueObjectArchive instance always ensures that a metadata record is created on the 5800 system server for each newly stored object, even if no metadata is provided with the store. This enables a model of programming where every stored data object is accessed by name-value metadata records (for example, for examining results from queries or performing delete operations). Object data is never deleted directly; it is deleted when its last referencing metadata record is deleted.

For additional information, see NameValueObjectArchive Application Access.

NameValueSchema

An instance of NameValueSchema represents information about the name-value metadata that the 5800 system system uses to index data. This instance can be used to enumerate the fields available in the schema as attributes. Each attribute has a name and a type.

See the Sun StorageTek 5800 System Administrator’s Guide for information on how to define attributes.

ObjectIdentifier

Instances of ObjectIdentifier uniquely represent objects in a 5800 system store. The 5800 system creates these instances when objects are stored and are returned to the client as part of the store result.ObjectIdentifier instances can be stored outside of the 5800 system and used later for retrieving objects. External storage can be accomplished using an identifier's string representation by invoking the toString method. An instance of ObjectIdentifier can be reconstituted using the constructor that takes String as an argument.

QueryResultSet

Instances of QueryResultSet provide access to the objects and metadata matching a query. The query results can be stepped through using the next method. The individual results are identifiers representing objects that match the query.

If selectKeys was specified in the original query, these metadata fields can be accessed using the typed getter methods with each field’s name.

SystemRecord

Instances of SystemRecord represent the system metadata for an object, including OID, object size, SHA1 hash, and creation time. They are returned by storeObject and storeMetadata.

NameValueRecord

Instances of NameValueRecord represent metadata used by the 5800 system to store and index user-extensible lists of name-value pairs. For convenience, instances of NameValueRecord also contain references to the SystemRecord instances of the objects they represent.

NameValueObjectArchive Application Access

Most applications make use of the NameValueObjectArchive class. This class ensures that a default metadata entry is created for every data object stored, even if no metadata is explicitly provided at store time.

The NameValueObjectArchive object functions as a proxy for the 5800 system server. All access is enabled by invoking methods on this object.

The following key methods and classes are used with the NameValueObjectArchive class:

NameValueObjectArchive

Initializes a new NameValueObjectArchive with the address or host name of a 5800 system server, using the provided port.

Synopsis

     public NameValueObjectArchive(java.lang.String address) 
          throws ArchiveException, java.io.IOException
     public NameValueObjectArchive(String address, int port) 
          throws ArchiveException, IOException

Description

The NameValueObjectArchive is instantiated by supplying the address of the 5800 system cluster in the constructor. The resulting data object can then be used to interact with that cluster.

delete

Deletes the metadata record.

Synopsis

     public void 
         delete(ObjectIdentifier identifier) 
         throws ArchiveException, java.io.IOException

Description

Takes a NameValueRecord OID.

Deletes the metadata record. If it is the last metadata record referencing the underlying object data, the underlying object data will also be deleted.

storeObject

Uploads a new data object with an associated name-value metadata record.

Synopsis

     public SystemRecord storeObject(java.nio.channels.ReadableByteChannel dataChannel)
     public SystemRecord 
         storeObject(ReadableByteChannel dataChannel,NameValueRecord record) 
         throws ArchiveException,IOException

Description

Takes a ReadableByteChannel (and an optional NameValueRecord) and returns a SystemRecord instance containing the system metadata for the new object.

storeMetadata

Creates a new metadata record in the name-value object archive linked to the data object identified by the OID.

Synopsis

     public SystemRecord storeMetadata(ObjectIdentifier linkOID,
         NameValueRecord record); 
         throws ArchiveException, java.io.IOException

Description

Takes a NameValueRecord and OID and returns a SystemRecord instance containing the system metadata for the new metadata record.

checkIndexed

Checks if the metadata for an object is present in the query engine, and inserts the metadata if it is not present.

Synopsis

     public int checkIndexed(ObjectIdentifier identifier)
             throws ArchiveException, IOException

Description

checkIndexed is intended as way to resolve a store index exception under program control (see The 5800 System Query Integrity Model for more information).

Once a store index exception occurs (as indicated by a SystemRecord.isIndexed value of false after a store operation) then archive.checkIndexed(oid) can be called repeatedly until it returns any non-zero value. This will ensure that the metadata for the object has been inserted into the query engine; the object should then start to show up in matching queries.

checkIndexed returns an int value that indicates if the metadata for this object has been inserted into the query engine. The value is -1 if the metadata was already inserted before this operation was called, 0 if the metadata has still not been inserted, or 1 if the metadata was just now inserted.

retrieveObject

Writes all of the data for the specified object into the provided channel, returning the amount of data actually retrieved.

Synopsis

     public long retrieveObject(ObjectIdentifier oid,
         WritableByteChannel dataChannel)
         throws ArchiveException, java.io.IOException
     public long retrieveObject(ObjectIdentifier oid,
         java.nio.channels.WritableByteChannel 
         dataChannel,long firstByte,
         long lastByte)
         throws ArchiveException, java.io.IOException

Description

Takes an OID and downloads the data object into a supplied WritableByteChannel.

retrieveMetadata

Returns a NameValueRecord instance containing the system and name-value metadata for the metadata record identified by the OID.

Synopsis

     public NameValueRecord 
         retrieveMetadata(ObjectIdentifier oid) 
         throws ArchiveException, java.io.IOException

Description

Returns a NameValueRecord instance containing the system and name-value metadata for the metadata record identified by the OID.

getSchema

Returns the runtime configuration of the name-value object archive as a NameValueSchema instance.

Synopsis

     public NameValueSchema getSchema()
          throws ArchiveException, java.io.IOException

Description

Returns the runtime configuration of the name-value object archive as a NameValueSchema instance.

query

Returns a ResultSet of SystemRecord instances containing MetadataRecord OIDs.

Synopsis

     public QueryResultSet 
         query(java.lang.String query,int resultsPerFetch) 
         throws ArchiveException, java.io.IOException

Description

Takes a where clause and returns a QueryResultSet of SystemRecord instances containing MetadataRecord OIDs.

The query parameter is a where clause in the 5800 system query syntax, which is a subset of SQL.

Returns a QueryResultSet. The results are stepped through by calling the next method and using the typed getXXX accessor methods.


Note –

For more information on the 5800 system query language, refer to Chapter 4, Sun StorageTek 5800 System Query Language.


query (with selectKeys)

Returns a ResultSet of NameValueRecord instances containing the selected values.

Synopsis

     public QueryResultSet 
         query(java.lang.String query, java.lang.String[] selectKeys,int maxResults) 
         throws ArchiveException, java.io.IOException

Description

Takes a where clause and a select clause and returns a QueryResultSet of NameValueRecord instances containing the selected values.

selectKeys identifies the values to be returned, functioning as an SQL select clause.

The query parameter is a where clause in the 5800 system query syntax, which is a subset of SQL.

Returns a QueryResultSet. The results are stepped through by calling the next method and using the getObjectIdentifier accessor.


Note –

For more information on the 5800 system query language, refer to Chapter 4, Sun StorageTek 5800 System Query Language.


query (with PreparedStatement)

Returns the OIDs of metadata records matching the query as a QueryResultSet instance.

Synopsis

     public QueryResultSet query(PreparedStatement query, 
          int resultsPerFetch)

Description

Takes a PreparedStatement and returns a QueryResultSet of SystemRecord instances containing MetadataRecord OIDs.

The PreparedStatement parameter enables queries with dynamic parameters to pass typed data items to the query.

Returns a QueryResultSet. The results are stepped through by calling the next method and using the typed getXXX accessor methods.


Note –

For more information on the 5800 system query language, refer to Chapter 4, Sun StorageTek 5800 System Query Language.


query (with PreparedStatement and selectKeys)

Returns specified fields from metadata records matching the query as a QueryResultSet instance.

Synopsis

     public QueryResultSet 
         query(PreparedStatement query, 
         java.lang.String[] selectKeys, 
         int resultsPerFetch)

Description

Takes a where clause and a select clause and returns a QueryResultSet of NameValueRecord instances containing the selected values.

selectKeys identifies the values to be returned, functioning as an SQL select clause.

The PreparedStatement parameter enables queries with dynamic parameters to pass typed data items to the query.

Returns a QueryResultSet. The results are stepped through by calling the next method and using the getObjectIdentifier accessor.


Note –

For more information on the 5800 system query language, refer to Chapter 4, Sun StorageTek 5800 System Query Language.


PreparedStatement

Extends com.sun.honeycomb.common.Encoding

Synopsis

     public PreparedStatement(java.lang.String sql);

Description

Used to implement queries with Dynamic Parameters, which is the preferred way to pass typed data items to a StorageTek 5800 query.

The number of bindParameter calls should match the number of question marks (?) in the query string in the prepared statement. Parameters are specified positionally. For example, a bindParameter call with index = 1 supplies a value for the first ? in the supplied query string. Once a value has been supplied for each of the dynamic parameters, then the PreparedStatement may be passed to the NameValueObjectArchive.query method to be executed, for example:

    NameValueObjectArchive archive = new NameValueObjectArchive(hostname);
    Date date_value= new java.sql.Date();
    PreparedStatement stmt = new PreparedStatement("date_field<?”);
    stmt.bindParameter(date_value,1);
    QueryResultSet qrs = archive.query(stmt);

QueryResultSet

The QueryResultSet class is used to page through OIDs and associated metadata returned by NameValueObjectArchive.query. See the javadoc for the getXXX methods for getting typed metadata.

next

Sets the QueryResultSet to point at the next record.

Synopsis

     boolean next()

Description

Sets the QueryResultSet to point at the next record. Returns true if there is a next record, false if not.

getObjectIdentifier

Gets the ObjectIdentifier of the current metadata record.

Synopsis

     ObjectIdentifier getObjectIdentifier()

Description

Gets the ObjectIdentifier of the current metadata record.

isQueryComplete

Returns whether the set of results constitutes a complete set

Synopsis

     boolean isQueryComplete()

Description

Returns whether the set of results constitutes a complete set. See The 5800 System Query Integrity Model.

getQueryIntegrityTime

Returns the most recent time at which all store index exceptions are known to have been resolved.

Synopsis

     long getQueryIntegrityTime()

Description

The query integrity time is a time such that all store index exceptions from before that time have been resolved. There is an ideal query integrity time, which is the time of the oldest still-unresolved store index exception: an ideal implementation when asked for the query integrity time would always report this ideal value. In actual implementation, the reported query integrity time might be hours or even days earlier than the ideal query integrity time, depending on how far the ongoing system healing has progressed.

QueryIntegrityTime

Get detailed status on which store index exceptions might still be unresolved

Synopsis

     QueryResultSet.isQueryComplete(), QueryResultSet.getQueryIntegrityTime();