test

Sun StorageTek 5800 System Client API Reference Guide

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 WritabableByteChannel.

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();