Package oracle.soda

Interface OracleDocument

public interface OracleDocument

Represents a document with (typically) JSON content.

The content can also be another MIME type: image, audio, video, etc.

The document has the following components:

• key
• content
• created-on timestamp
• last-modified timestamp
• version or checksum (suitable for ETag)
• media type ("application/json" for JSON documents)

created-on and last-modified timestamps are not tracked for collections based on JSON Collection Tables and Duality Views (introduced in Oracle Database 23ai). For such collections these values are null.

It is valid for any of the above components to be missing in a given OracleDocument.

Some examples:

• OracleCollection.insert(OracleDocument) and OracleCollection.insertAndGet(OracleDocument) input documents may contain content only. Key is automatically generated by the insert operation. If the collection is configured with client-assigned keys, the input document needs to contain the key as well.
• Documents returned by OracleCursor obtained by calling col.find().getCursor() may contain key, content, created-on timestamp, last-modified timestamp, and version.
• Result documents returned by OracleCollection.insertAndGet(OracleDocument) or OracleOperationBuilder.replaceOneAndGet(OracleDocument) may contain key, created-on timestamp, last-modified timestamp, and version. These documents will not have any content.

Method Summary

Modifier and Type	Method	Description
<T> T	getContentAs(Class<T> type)	Returns the content as the specified type.
byte[]	getContentAsByteArray()	Returns the content as a byte array.
String	getContentAsString()	Returns the content as a String.
int	getContentLength()	Returns the length of content if know.
String	getCreatedOn()	Returns the timestamp of creation of this document in ISO format.
String	getKey()	Returns the key.
String	getLastModified()	Returns the timestamp of the last modification to this document in ISO format.
String	getMediaType()	Returns the media type.
String	getVersion()	Returns a string suitable for use as a version of the document.
boolean	isJSON()	Returns true is this document has media type "application/json".

Method Detail

getKey

String getKey()

Returns the key.

Returns:

the key as a String. null if the key is not available

getContentAsByteArray

byte[] getContentAsByteArray()
                      throws OracleException

Returns the content as a byte array.

Returns:

content as a byte[], or null if the content is not available.

Throws:

OracleException - if there's an error returning content as byte[]

getContentAsString

String getContentAsString()
                   throws OracleException

Returns the content as a String.

Returns:

content as a String, or null if the content is not available

Throws:

OracleException - if there's an error returning content as String

getContentAs

<T> T getContentAs(Class<T> type)
            throws OracleException

Returns the content as the specified type. The following types are supported:

Class	Description
javax.json.JsonValue jakarta.json.JsonValue oracle.sql.json.OracleJsonValue	The JSON type value is returned as JsonValue or OracleJsonValue. Any derived interface, such as JsonObject may also be used. JsonObject obj = doc.getContentAs(JsonObject.class);
javax.json.stream.JsonParser jakarta.json.stream.JsonParser oracle.sql.json.OracleJsonParser	The JSON type value is returned as an event stream.
java.lang.String java.io.Reader	The JSON type value is returned as JSON text.

Deprecation Notice: support for javax.json will be removed in an upcoming release.

Type Parameters:

T - the type of the returned content

Parameters:

type - the type of the returned content

Returns:

content as an instance of the specified type or null if the content is not available

Throws:

OracleException - if there's an error returning content as the specified type or if a mapping to the specified type is not supported

getMediaType

String getMediaType()

Returns the media type. JSON objects have media type "application/json".

Returns:

media type as a String, or null if the media type is not available

getLastModified

String getLastModified()

Returns the timestamp of the last modification to this document in ISO format. null for collections based on JSON Collection Tables and Duality Views (introduced in Oracle Database 23ai).

Returns:

a String representation of the timestamp, or null if the timestamp is not available

getCreatedOn

String getCreatedOn()

Returns the timestamp of creation of this document in ISO format. null for collections based on JSON Collection Tables and Duality Views (introduced in Oracle Database 23ai).

Returns:

a String representation of the timestamp, or null if the timestamp is not available

getVersion

String getVersion()

Returns a string suitable for use as a version of the document. This is typically a version number, precise timestamp, or checksum of the actual content.

Returns:

a String representation of the version, or null if the version is not available

getContentLength

int getContentLength()

Returns the length of content if know. -1 is not known.

Returns:

length of content, in bytes. -1 if not known.

isJSON

boolean isJSON()

Returns true is this document has media type "application/json".

Returns:

true if this document has media type "application/json", false otherwise