Sun Microsystems 5800 - Manual

Tables TABLE 4–1 Canonical String Representation of Data Types .................................................. 119 9

Preface The Sun StorageTek 5800 System Client API Reference Manual is written for programmers and application developers who develop custom applications for the Sun StorageTek TM 5800 System. This document, along with the Sun StorageTek 5800 SystemSDK Reference Manual , provides the information that...

Related Third-Party Web Site References Third-party URLs are referenced in this document and provide additional, related information. Note – Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any ...

TABLE P–1 Typographic Conventions (Continued) Typeface Meaning Example AaBbCc123 Book titles, new terms, and terms to beemphasized Read Chapter 6 in the User's Guide . A cache is a copy that is stored locally. Do not save the file. Note: Some emphasized items appear bold online. Shell Prompts in Com...

Sun StorageTek 5800 System Client API The Sun TM StorageTek TM 5800 system client API provides programmatic access to a 5800 system server to store, retrieve, query, and delete object data and metadata. Synchronous versions areprovided in C and Java TM languages. A future release will implement a no...

This chapter provides a summary of key points of the 5800 system usage model that are usefulfor understanding either API. In the following sections, the terms from the Java API are used as an aid to exposition. In allcases, a simple equivalent using the C API is available. ■ Chapter 4, “Sun StorageT...

The 5800 System Metadata Model Metadata means “data about the data”; it describes the data and helps to determine how the datashould be interpreted. In addition, metadata can be used to facilitate querying the 5800 systemfor objects that match a particular set of search criteria. For the 5800 system...

The metadata associated with an object is immutable. There is no operation to modify themetadata associated with an object after the object has been stored. Instead, the storeMetadata operation can be used to create a completely new object by associating new user metadata withthe underlying data and...

Query expressions can use much of the power of Structured Query Language (SQL). Each queryexpression combines SQL functions and operators, field names from the metadata schema, andliteral values. There are no query expressions that select objects based on the data stored in theobject itself; all que...

Note – The format of records as stored in the reliable and scalable object archive is not suitable for fast query. To enable searching, the queryable fields from the metadata are indexed in aquery engine that can provide fast and flexible query services. The query engine is basically anSQL database....

Sun StorageTek 5800 System Java Client API This chapter provides information on the 5800 system Java client API. The following topics are discussed: ■ “Overview of the 5800 System Java Client API” on page 25 ■ “Java Client Application Deployment” on page 27 ■ “Java API” on page 27 Note – You can fin...

The 5800 system Java client library provides a platform-independent mechanism to upload dataand metadata to a 5800 system, and to retrieve and query the data and metadata. The Java clientlibrary works with any implementation of J2SE TM platform 4.0 or later with HTTP connectivity to the 5800 system ...

Updating Client View of the Schema In the Java client API, the schema is fetched when the NameValueObjectArchive class is instantiated. If the schema has changed, the client application needs to create a new NameValueArchive . A local copy of the schema is used for some metadata operations. Java Cli...

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 invokingmethods on a NameValueObjectArchive instance after initializing it with the address of a cluster. The ...

■ “ ObjectIdentifier ” on page 29 ■ “ QueryResultSet ” on page 30 ■ “ SystemRecord ” on page 30 ■ “ NameValueRecord ” on page 30 For more information on using these classes, see “Basic Concepts” on page 28 . NameValueObjectArchive The NameValueObjectArchive class is the main entry point into the 580...

later for retrieving objects. External storage can be accomplished using an identifier's stringrepresentation 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 provi...

■ “ query (with PreparedStatement )” on page 35 ■ “ query (with PreparedStatement and selectKeys )” on page 35 ■ “ PreparedStatement ” on page 36 ■ “ QueryResultSet ” on page 37 ■ “ getObjectIdentifier ” on page 37 ■ “ isQueryComplete ” on page 37 ■ “ getQueryIntegrityTime ” on page 38 ■ “ QueryInte...

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

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

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

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

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

getQueryIntegrityTime Returns the most recent time at which all store index exceptions are known to have beenresolved. Synopsis long getQueryIntegrityTime() Description The query integrity time is a time such that all store index exceptions from before that time havebeen resolved. There is an ideal ...

Sun StorageTek 5800 System C Client API This chapter provides detailed information on the 5800 system C client API. The following topics are discussed: ■ “Overview of the 5800 System C Client API” on page 39 ■ “C Client Application Deployment” on page 43 ■ “Nonblocking C API” on page 43 ■ “Synchrono...

Architecture The 5800 system C API client supports two different access patterns: a synchronous “EZ” accessvery similar to the current Java implementation, and a more flexible, nonblocking access basedon the POSIX model. Note – For this release, the nonblocking C API client is not implemented. Inter...

Memory Usage The 5800 system C client library generally follows the model of populating externally allocateddata structures such as handles, buffers, and result arrays. Some internal data structures are generated during XML document construction. These datastructures are allocated and freed using th...

hcerr_t hc_init(allocator_t, deallocator_t, reallocator_t); This function must be called once per process to initialize the memory functions used in the5800 system C API. It also initializes global session properties. A global session is initialized once per process, regardless of how many threads i...

■ oid — The objectid for this object, equivalent to the system.object_id field. ■ digest_algo — Always set to " sha1 " for this release. Equivalent to the system.object_hash_alg field. ■ data_digest — An array of bytes that represent the content digest of this object's data. Equivalent to th...

Synchronous C API A multiplatform synchronous C API in which operations are accomplished in a few simplefunction calls is provided for the 5800 system. The API calls include operations for storing,retrieving, deleting, and querying of data and metadata records. Multiple threads are supported,and ope...

– “ hc_nvr_get_time ” on page 82 – “ hc_nvr_get_timestamp ” on page 83 – “ hc_pstmt_create ” on page 100 – “ hc_pstmt_free ” on page 101 – “ hc_pstmt_set_string ” on page 101 – “ hc_pstmt_set_char ” on page 102 – “ hc_pstmt_set_double ” on page 103 – “ hc_pstmt_set_long ” on page 104 – “ hc_pstmt_se...

Description Function pointers of read_from_data_source type are used to upload object data. The function pointer and opaque cookie reference are supplied as arguments to “ hc_store_both_ez ” on page 87 and other functions that store object data. The data source reader function will be called repeate...

Description This structure defines the 5800 system C client API error codes. Synchronous C API Functions The 5800 system synchronous C API functions are defined to perform the following tasks: ■ “Managing 5800 System Sessions” on page 53 ■ “Managing a Schema” on page 59 ■ “Manipulating Name-Value Re...

response_codep OUT: Updated to be the HTTP response code. errstr IN: Updated to be the error returned in the response body if the response code is not 200 (OK). errstr should not be written to by the application (that is, it is read only), and will persist until the next request to the 5800 system s...

hc_session_get_archive Returns the current archive object associated with this session. Synopsis hcerr_t hc_session_get_archive(hc_session_t *session, hc_archive_t **archivep); Description This function returns the current archive object associated with this session. Note – The archive object is not...

IN: Should range from 0 up to the count-1 returned in “ hc_schema_get_count ” on page 61 . namep OUT: Updated to point to a string that is an attribute name of one attribute in the schema. typep OUT: Updated to be the type associated with that name in the schema. If the server schemareferences a typ...

▼ To Use the API for Storing Name-Value Records Call hc_init once per process. Call “ hc_session_create_ez ” on page 53 to initialize the session and download the schema. Create the metadata record with “ hc_nvr_create ” on page 65 . Fill the new metadata piece by piece with hc_nvr_add_metadata_* fu...

Creating and Freeing Name-Value Records The following functions are defined to create and free name-value records: ■ “ hc_nvr_create ” on page 65 ■ “ hc_nvr_free ” on page 66 hc_nvr_create Creates a name-value record. Synopsis hcerr_t hc_nvr_create(hc_session_t *session, hc_long_t nslots, hc_nvr_t *...

See Also “ hc_nvr_free ” on page 66 hc_nvr_free Frees a name-value record. Synopsis hcerr_t hc_nvr_free(hc_nvr_t *nvr); Description This function frees a name-value record that was created by “ hc_nvr_create ” on page 65 . Parameter nvr IN: Points to the name-value-record to be freed. Return Codes H...

Retrieving Name-Value Records The following functions are defined to retrieve name-value records: ■ “ hc_nvr_get_count ” on page 76 ■ “ hc_nvr_get_value_at_index ” on page 77 ■ “ hc_nvr_get_long ” on page 78 ■ “ hc_nvr_get_double ” on page 79 ■ “ hc_nvr_get_string ” on page 80 ■ “ hc_nvr_get_binary ...

HCERR_OOM HCERR_INVALID_NVR HCERR_ILLEGAL_ARGUMENT Storing Data and Metadata The following functions are defined to store data and metadata and to enforce indexing ofmetadata where necessary: ■ “ hc_store_both_ez ” on page 87 ■ “ hc_store_metadata_ez ” on page 88 ■ “ hc_check_indexed_ez ” on page 89...

Retrieving Data and Metadata The following functions are defined to retrieve data and metadata: ■ “ hc_retrieve_ez ” on page 91 ■ “ hc_retrieve_metadata_ez ” on page 92 ■ “ hc_range_retrieve_ez ” on page 93 hc_retrieve_ez Retrieves data for the specified OID. Synopsis hcerr_t hc_retrieve_ez(hc_sessi...

HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_OID HCERR_ILLEGAL_ARGUMENT Querying Metadata The following functions are defined for simple queries: ■ “ hc_query_ez ” on page 94 ■ “ hc_qrs_next_ez ” on page 96 ■ “ hc_qrs_is_query_complete ” on page 97 ■ “ hc_qrs_get_query_integrity_time ” on ...

Return Codes HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_INVALID_RESULT_SET hc_qrs_get_query_integrity_time Returns a time that helps get more detail on which store index exceptions might still beunresolved. Synopsis hcerr_t hc_qrs_get_query_integrity_time(hc_query_result_set_t *rset, hc_long_t *quer...

// list all OIDs from yesterday with test_status t = 86400; // 86400 sec/day date = gmtime(&t); res = hc_pstmt_set_date(pstmt, 1, date); res = hc_pstmt_query_ez(pstmt, selects, 1, 2000, &rset); while (1) { hc_oid oid; hc_nvr_t *nvr int finished; hc_string_t test_status; res = hc_qrs_next_ez(...

Parameters session IN: Pointer to the session. oid IN: The specified OID. Return Codes HCERR_OK HCERR_BAD_REQUEST HCERR_OOM HCERR_NULL_SESSION HCERR_INVALID_SESSION HCERR_INVALID_OID Translating Error and Type Codes The following functions are defined for translating error codes and type codes into ...

Operation The query format is similar to the where clause of an SQL query. The two main differences are that 5800 system queries do not contain embedded subqueries, and that the only “columns” thatare available are the attributes defined in the 5800 system schema. Many features of the underlying met...

Queries A query in the 5800 system query language is translated into an equivalent query for theunderlying database that implements the query engine. The database used in a live 5800 systemis Sun's High Availability Database (HADB). The database used by the 5800 system emulator isApache TM Derby. Si...

SQL Syntax in 5800 System Queries General Unicode characters outside of the ASCII range in queries are allowed in only two placesto the 5800 system. Specifically, both attribute names and literal values may contain generalUnicode characters. All text that is not either an attribute name nor a litera...

Literals for 5800 System Data Types For each 5800 system data type, there is a syntax to include literals of that type in a query string.The syntax is {type_name ’ stringliteral ’ } . For example, consider the query: timestamp_field<{timestamp ’ 2006-10-26T12:00:00Z ’ } In particular, this syntax...

■ When converting a typed value to a string as the result of the getAsString operation on a NameValueRecord or a QueryResultSet operation ■ When parsing a literal value as described in “Literals for 5800 System Data Types” on page 119 to create a typed query value from a string representation of tha...

Examples of Supported Query Expressions ■ {fn LCASE(mp3.artist)} LIKE ’ %floyd% ’ AND system.object_size > 2000000 ■ (object_size < 200) OR " Collation " = ’ en-US ’ ■ {fn TIMESTAMPDIFF(SQL_TSI_YEAR, system.test.type_timestamp, ’ 2007-04-02 01:50:50.999 ’ )} < 3 ■ {fn TIMESTAMPADD(S...

■ SIN(float) ■ SQRT(float) ■ TAN(float) SQL Words That Are Allowed in Queries Some SQL reserved words (such as BETWEEN or LIKE ) are allowed in queries and are expected to occur. An SQL reserved word cannot be used as an attribute name unless it is enclosed in doublequotes (for example, " FIRST ...

Programming Considerations and BestPractices This chapter provides considerations and practices that can help you create efficient 5800system applications. The following topics are discussed: ■ “Retries and Timeouts” on page 127 ■ “Query Size Limit” on page 127 ■ “Limit the Size of Schema Query Para...

field consumes the same number of bytes as the length of the value. A string value consumestwice as many bytes as the length of the value. These sizes are similar to what is described in the Sun StorageTek 5800 System Administration Guide , Table 7-6, Number of Bytes Used by Each Element Type in a S...

Index Numbers and Symbols 5800 system Honeycomb project, 17summary, 16-17 B best practices max results per fetch, 128retries and timeouts, 127schema query size, 128 C C client API application deployment, 43architecture, 40failure and recovery, 43 hc_cleanup , 42 hc_init , 41-42 hc_system_record_t , ...