Sun StorageTek 5800 System SDK Developer's Guide

Chapter 2 Example Applications

This chapter provides information about the Java and C example applications that are provided with the 5800 system SDK.

The following topics are discussed:

Example Application Summary

Table 2–1 summarizes the Java and C example applications provided with the 5800 system SDK. All code examples are command-line applications.

For detailed information about the Java example applications, see Java Example Applications.

For detailed information about the C example applications, see C Example Applications.

Table 2–1 5800 system Client SDK Example Applications

Application 

Java Version  

C Version  

StoreFile – Enables you to specify a file from the command line to store on a 5800 system server as data. You can also specify metadata to include with the file.

StoreFile

StoreFile

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

CheckIndexed

CheckIndexed

RetrieveData – Enables you to retrieve data from the 5800 system server by Object ID. The data object is sent to standard output or to a file specified on the command line.

RetrieveData

RetrieveData

RetrieveMetadata – Enables you to retrieve a metadata record from the 5800 system server associated with the supplied OID. The metadata record is printed to standard output.

RetrieveMetadata

RetrieveMetadata

AddMetadata – Enables you to specify name-value pairs from the command line to store on a 5800 system server as a metadata record.

AddMetadata

AddMetadata

DeleteRecord – Deletes a record from the 5800 system server for an OID supplied on the command line.

DeleteRecord

DeleteRecord

Query – Queries a 5800 system server for specified metadata. The query string is provided on the command line. Query can print out the results as a list of name-value pairs or as a list of OIDs. You can specify the maximum number of results returned.

Query

Query

RetrieveSchema – Retrieves the schema from a 5800 system server, printing it to standard output.

RetrieveSchema

RetrieveSchema

GetDate– Gets the date.

GetDate

N/A 

Java Example Applications

This section provides detailed information about the Java example applications provided with the 5800 system client SDK.

Examples Overview

Included with the 5800 system SDK are several command-line example applications that demonstrate the Java API. The example applications are located in the SDK in the java/examples directory. These example applications come complete with a build script.

Software Requirements

The Java example applications require at minimum the JDK™ 5.0 software.


Note –

For Windows 2003, add C:\Program Files\Java\jdk version\bin to the PATH environment variable.


Running the Applications

UNIX (.sh) and Windows (.bat) scripts for running the example applications are provided in the java/scripts/ directory. These scripts must be run from the java/scripts/ directory. The scripts illustrate the CLASSPATH environment variable required. The .jar files are in the java/lib/ directory.


Note –

The usage messages printed by the applications omit the CLASSPATH environment variable for the sake of readability. If you are running the example application without using the provided scripts, then you must set the CLASSPATH environment variable manually.


Building the Java Example Applications

To build the Java example applications, go to the java/examples/ directory and execute the master-build.sh script for Solaris and Linux environments or the master-build.bat script for Windows environments. These scripts build the examples and put them in the honeycomb-sdk.jar archive located in the java/lib directory.

Running a Java Example Application

Once you have built the Java example applications, go to the java/scripts directory and execute the .sh scripts for Solaris and Linux environments or .bat scripts for Windows environments:

Syntax: script_name arguments

See the scripts for details of how the applications are run.

About the Example Application Source Code

The Java example applications are all simple applications that follow the same basic structure. First, Commandline.parse is called to parse the argument list. Next, the appropriate method in the NameValueObjectArchive class is called to communicate with the 5800 system server. Finally, output is delivered back to either standard output, a file, or both. Refer to the comments in the sample code for further details.

Example Applications

The following sections describe the Java example applications that are included with the 5800 system client SDK:

StoreFile

Stores a file and associated metadata to a 5800 system server.

Synopsis

     java StoreFile <IP | HOST> <FILE> [OPTIONS]

Description

Stores a file and its associated metadata record. If no -m options are specified, a metadata record without user content is generated. The OID of the metadata record is printed to stdout.


Note –

StoreFile interprets the time in metadata arguments as local time zone unless the T..Z format indicating UTC is used. For example, 1952-10-27T00:30:29.999Z.


Options

     -m <name>=<value>

Any number of -m options can be specified. Each -m option specifies a single (name,value) pair.

<name> should be specified in the format <namespace>.<attribute>. Use double quotes if <value> is a string containing spaces.

     
-h

Print this message.

Examples

   java StoreFile 10.152.0.12 myFile
     java StoreFile server myFile.jpg \
          -m filesystem.mimetype="image/jpeg"
     java StoreFile server myFile \
          -m system.test.type_char="do re mi"
     java StoreFile server myFile \
          -m system.test.type_string="fa so la"
     java StoreFile server myFile \
          -m system.test.type_long=123
     java StoreFile server myFile \
          -m system.test.type_double=1.23
     java StoreFile server myFile \
          -m system.test.type_binary=0789abcdef
     java StoreFile server myFile \
          -m system.test.type_date=2010-10-20
     java StoreFile server myFile \
          -m system.test.type_time=23:30:29
     java StoreFile server myFile \
          -m system.test.type_timestamp="2010-10-20 23:30:29.999"
     java StoreFile server myFile \
          -m name1=value1 -m name2="value 2"

Source Code

java/examples/StoreFile.java

CheckIndexed

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

Synopsis

     java CheckIndexed <IP | HOST> <OID> [OPTIONS]

Description

Check with the 5800 systemserver to determine if the specified OID has become queryable. If not, attempt to make it queryable.

A short message about the supplied OID is printed to stdout:


          Object OID was already queryable.
          Object OID not yet queryable.
          Object OID has now been made queryable.

Options

     
-h

Print this message.

Examples

      java CheckIndexed server \
            0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000
      java CheckIndexed 10.152.0.12 \
            0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000

Source Code

java/examples/CheckIndex.java

RetrieveData

Retrieves data from a 5800 system server.

Synopsis

     java RetrieveData <IP | HOST> <OID> [FILE] [OPTIONS]

Description

Retrieves data from the 5800 system. The OID specifies what data to retrieve. Data is written to FILE, if specified, otherwise to stdout.

Options

     
-h

Print this message.

Examples

     java RetrieveData archivehost \
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
         /archive/log.1
     java RetrieveData 10.152.0.12 \
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
         /archive/log.2

Source Code

java/examples/RetrieveData.java

RetrieveMetadata

Retrieves data (and metadata) from a specified 5800 system server.


Note –

RetrieveMetadata always displays the time in the time zone of the shell running the program.


Synopsis

     java RetrieveMetadata <IP | HOST> <OID> [OPTIONS]

Description

Retrieves a data record and metadata from the 5800 system server. The metadata record identified by the supplied OID is printed to stdout.

Options

     
-h

Print this message.

Examples

     java RetrieveMetadata 10.152.0.12 \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000

Source Code

java/examples/RetrieveMetadata.java

AddMetadata

Adds a metadata record to an already stored object.

Synopsis

     java AddMetadata <IP | HOST> <OID> [OPTIONS]

Description

Adds a new metadata record to an existing data object.

Options

     -m <name>=<value>

Any number of -m options can be specified. Each option specifies a single (name, value) pair.

<name> should be specified in the format <namespace>.<attribute>. Use double quotes if <value> is a string containing spaces.

     
-h

Print this message.

Examples

     java AddMetadata server \
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \
         -m filesystem.mimetype="image/jpeg"
     java AddMetadata server \
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \ 
         -m system.test.type_char="do re mi"
     java AddMetadata server 
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \ 
         -m system.test.type_string="fa so la"
     java AddMetadata server 
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \
         -m system.test.type_long=123
     java AddMetadata server 
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \
         -m system.test.type_double=1.23
     java AddMetadata 
         server 0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \
         -m system.test.type_date=1952-10-27
     java AddMetadata server \
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \
         -m system.test.type_time=23:30:29
     java AddMetadata server \
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \
         -m system.test.type_timestamp="1952-10-27 23:30:29.999"
     java AddMetadata server \
         0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000@ \
         -m name1=value1 -m name2="value 2"

Source Code

java/examples/AddMetadata.java

DeleteRecord

Deletes the Sun 5800 system metadata record associated with an OID.

Synopsis

     java DeleteRecord <IP | Host> <OID> [OPTIONS]

Description

Deletes the record with the specified OID. If this record is the only record pointing to the data, the data will also be deleted.

Options

     
-v

Print deleted OID to stdout.

     
-h

Print this message.

Examples

     java DeleteRecord server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000

Source Code

java/examples/DeleteRecord.java

Query

Queries a 5800 system server for metadata records that match the query string passed on the command line.


Note –

Query requires the T..Z UTC format. For example, 1952-10-27T00:30:29.999Z.


Synopsis

     java Query <IP | HOST> <QUERY> [OPTIONS]

Description

Queries for metadata records. QUERY is of the form:

     <name1>=’<value1>’ AND <name2>=’<value2>’ OR ...

See the examples below for formatting of various types of values. The OID and any specified fields of metadata records that match the query are printed to stdout.

<name> should be specified in the format <namespace>.<attribute>.

Note that names that are keywords need to be enclosed in escaped double quotes ("\"<name>\"=’<value>’"). Refer to the list of keywords in Chapter 4, Sun StorageTek 5800 System Query Language, in Sun StorageTek 5800 System Client API Reference Guide. Also note that some shells such as csh might not accept the escaped quotes because they are embedded in other quotes.

Options

     
-s <FIELD>

Specifies a field to be retrieved, much like an SQL select clause. To retrieve multiple fields, repeat this option. By default, the results are returned as a list of OIDs.

     
-n <number of results>

The maximum number of metadata records or OIDs that will be returned. The default is 1000.

     
-h

Print this message.

Examples

In the following examples, “first” is a keyword.

     java Query server "book.author=’King’"
     java Query server "\"first\"=’a’"
     java Query 10.152.0.12 "mp3.artist=’The Beatles’ AND mp3.album=’Abbey Road’"
     java Query 10.152.0.12 "mp3.artist=’The Beatles’" -s mp3.album -s mp3.title
     java Query 10.152.0.12 system.test.type_char="’do re mi’"
     java Query 10.152.0.12 system.test.type_string="’fa so la’"
     java Query 10.152.0.12 system.test.type_long=123
     java Query 10.152.0.12 system.test.type_double=1.23
     java Query 10.152.0.12 system.test.type_binary="x’0789abcdef’"
     java Query 10.152.0.12 system.test.type_date="’2010-10-20’"
     java Query 10.152.0.12 system.test.type_time="’23:30:29’"
     java Query 10.152.0.12 system.test.type_timestamp="{timestamp’2010-10-20T23:30:29.123Z’}"

Source Code

java/examples/Query.java

RetrieveSchema

Returns the schema defined on a 5800 system server to standard output.

Synopsis

     java RetrieveSchema [OPTIONS] <IP | HOST>

Description

Retrieves the metadata schema from a 5800 system server, printing it to stdout.

Options

     
-h

Print this message.

Examples

     java RetrieveSchema archivehost

Source Code

java/examples/RetrieveSchema.java

GetDate

Gets the date.

Synopsis

     java GetDate <IP | HOST> [OPTIONS]

Description

Gets the current date used to compute time setting and checking during store and delete operations.

Options

     
-h

Print this message.

Examples

     java GetDate server

Source Code

java/examples/GetDate.java

C Example Applications

This section provides detailed information on the C example applications provided with the 5800 system client SDK.

Example Overview

Included with the 5800 system SDK are several command-line example applications that demonstrate the use of the C API. The example applications are located in the SDK under c/examples. Appropriate libraries are supplied for Solaris SPARC, Solaris x86, Red Hat Linux, and Windows.

Software Requirements

Also see Software Requirements.

Building the C Example Applications

To build the C example applications, go to the c/examples directory and run make. This will build the example applications and put them in the c/examples/OS/build directory.

Each C example application can be built separately by running make program_name.

Running a C Example Application

Once you have built the C example applications, go to the c/examples/<OS>/build directory and execute the binary file with the appropriate command line. The examples depend on libhoneycomb.so.

About the C Example Application Source Code

First, the function parseCommandline is called to parse the command line and store the information in a struct called Commandline. Next, any files that contain data to be sent to the 5800 system server are opened. The appropriate 5800 system C API is then called. Finally, output is delivered back to either standard output, a file, or both. Refer to the comments in the sample code for further details.

Example Applications

The following C example applications are included with the 5800 system client SDK:

StoreFile

Stores a file and associated metadata on a 5800 system server.

Synopsis

     StoreFile <IP | HOST> <FILE> [OPTIONS]

Description

Stores a file and its associated metadata record. If no -m options are specified, a metadata record without user content is generated. The OID of the metadata record is printed to stdout.

Options

-m <name>=<value>

Any number of -m options can be specified. Each option specifies a single (name,value) pair.

<name> should be specified in the format <namespace>.<attribute>. Use double quotes if <value> is a string containing spaces.

-h

Print this message.

Examples

     StoreFile server /var/log/messages
     StoreFile server ~/journal
     StoreFile server myfile.jpg -m filesystem.mimetype="image/jpeg"
     StoreFile 10.152.0.12 myfile -m system.test.type_char="do re mi"
     StoreFile 10.152.0.12 myfile -m system.test.type_string="fa so la"
     StoreFile 10.152.0.12 myfile -m system.test.type_long=123
     StoreFile 10.152.0.12 myfile -m system.test.type_double=1.23
     StoreFile 10.152.0.12 myfile -m system.test.type_binary=0789abcdef
     StoreFile 10.152.0.12 myfile -m system.test.type_date=2010-10-20
     StoreFile 10.152.0.12 myfile -m system.test.type_time=23:30:29
     StoreFile 10.152.0.12 myfile \
          -m system.test.type_timestamp="2010-10-20T23:30:29.999"
     StoreFile 10.152.0.12 myfile -m name1=value1 -m name2="value 2"

Source Code

c/examples/StoreFile.c

CheckIndexed

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

Synopsis

     CheckIndexed <IP | HOST> <OID> [OPTIONS]

Description

Check with the 5800 systemserver to determine if the specified OID has become queryable. If not, attempt to make it queryable.

A short message about the supplied OID is printed to stdout:


          Object OID was already queryable.
          Object OID not yet queryable.
          Object OID has now been made queryable.

Options

     
-h

Print this message.

Examples

       CheckIndexed archivehost \
              0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000
       CheckIndexed 10.152.0.12 \
              0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 

Source Code

c/examples/CheckIndexed.c

RetrieveData

Retrieves a data object from a 5800 system server.

Synopsis

     RetrieveData <IP | HOST> <OID> <FILE> [OPTIONS]

Description

Retrieves data from the 5800 system. The OID specifies what data to retrieve. Data is written to FILE, if specified, otherwise to stdout.

Options

     
-h

Print this message.

Examples

     RetrieveData storagetek \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          /archive/log.1

Source Code

c/examples/RetrieveData.c

RetrieveMetadata

Retrieves a metadata record from a specified 5800 system server.

Synopsis

     RetrieveMetadata <IP | HOST> <OID> [OPTIONS]

Description

Retrieves metadata from the 5800 system. The OID specifies what data to retrieve. Metadata is printed to stdout.

Options

     
-h

Print this message.

Examples

     RetrieveMetadata archivehost \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000
     RetrieveMetadata 10.152.0.12 \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000

Source Code

c/examples/RetrieveMetadata.c

AddMetadata

Adds a metadata record to existing data.

Synopsis

     AddMetadata <IP | HOST> <OID> [OPTIONS]

Description

Adds a new metadata record to an existing data object.

Options

     
-m <name>=<value>

Any number of -m options can be specified. Each option specifies a single (name, value) pair.

<name> should be specified in the format <namespace>.<attribute>. Use double quotes if <value> is a string containing spaces.

-h

Print this message.

Examples

     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m filesystem.mimetype="image/jpeg"
     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m system.test.type_char="do re mi"
     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m system.test.type_string="fa so la"
     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m system.test.type_long=123
     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m system.test.type_double=1.23
     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m system.test.type_date=1992-10-27
     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m system.test.type_time=23:30:29
     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m system.test.type_timestamp="1992-10-27T23:30:29"
     AddMetadata server \
          0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000 \
          -m name1=value1 -m name2="value 2"

Source Code

c/examples/AddMetadata.c

DeleteRecord

Deletes a record associated with an OID.

Synopsis

     DeleteRecord <IP | HOST> <OID> [OPTIONS]

Description

Deletes a record associated with an OID. The OID specifies which record to delete. The record consists of all metadata associated with the OID, or the data if it is a data OID. The OID itself becomes inaccessible. If this OID is the last OID associated with the data, the data is also deleted.

Options

-v

Print deleted OID to stdout.

-h

Print this message.

Examples

     DeleteRecord server 0200004f75ee01094cc13e11dbbad000e08159832d000024d40200000000

Source Code

c/examples/DeleteRecord.c

Query

Queries a 5800 system server for metadata records that match the query string passed on the command line.


Note –

Query requires the T..Z UTC format. For example, 1952-10-27T00:30:29.999Z.


Synopsis

     Query <IP | HOST> <QUERY> [OPTIONS]

Description

Queries for metadata records. QUERY is of the form:

<name1>=’<value1>’ AND <name2>=’<value2>’ OR ...

See the examples below for formatting of various types of values. The OID and any specified fields of metadata records that match the query are printed to stdout.

<name> should be specified in the format <namespace>.<attribute>.

Note that names that are keywords need to be enclosed in escaped double quotes ("\"<name>\"=’<value>’"). Refer to the list of keywords in Chapter 4, Sun StorageTek 5800 System Query Language, in Sun StorageTek 5800 System Client API Reference Guide. Also note that some shells such as csh may not accept the escaped quotes because they are embedded in other quotes.

Options

-s <FIELD>

Print out results as metadata name-value records. Use as many -s switches as needed to define all fields that will be printed to stdout.

-n <number of results>

The maximum number of metadata records or OIDs that will be returned. The default is 1000.

-h

Print this message.

Examples

In the following examples, “first” is a keyword.

     Query archivehost "book.author=’King’"
     Query archivehost "\"first\"=’a’"
     Query archivehost system.test.type_char="’do re mi’"
     Query archivehost system.test.type_string="’fa so la’"
     Query archivehost system.test.type_long=123
     Query archivehost system.test.type_double=1.23
     Query archivehost system.test.type_binary="x’0789abcdef’"
     Query archivehost system.test.type_date="’2010-10-20’"
     Query archivehost system.test.type_time="’22:10:29’"
     Query archivehost system.test.type_timestamp="{timestamp’2010-10-20T23:30:29.123Z’}"
     Query 10.152.0.12 "mp3.artist=’The Beatles’ AND mp3.album=’Abbey Road’"
     Query 10.152.0.12 "mp3.artist=’The Beatles’" -s mp3.album -s mp3.title
     Query 10.152.0.12 "system.test.type_timestamp={timestamp ’1952-10-27T08:30:29.999Z’}"

Source Code

c/examples/Query.c

RetrieveSchema

Prints metadata attributes to stdout.

Synopsis

     RetrieveSchema <IP | HOST> [OPTIONS]

Description

Retrieves the schema from a 5800 system server, printing it to stdout.

Options

     
-h

Print this message.

Examples

     RetrieveSchema archivehost

Source Code

c/examples/RetrieveSchema.c