SODA Collection Configuration Using Custom Metadata

5 SODA Collection Configuration Using Custom Metadata

SODA collections are highly configurable. You can customize collection metadata, to obtain different behavior from that provided by default.

Note:

You can customize collection metadata to obtain different behavior from that provided by default. However, changing some components requires familiarity with Oracle Database concepts, such as SQL data types. Oracle recommends that you do not change such components unless you have a compelling reason. Because SODA collections are implemented on top of Oracle Database tables (or views), many collection configuration components are related to the underlying table configuration.

For example, if you change the content column type from the default value to VARCHAR2, then you must understand the implications: content size for VARCHAR2 is limited to 32K bytes, character-set conversion can take place, and so on.

Getting the Metadata of an Existing Collection

OracleCollectionAdmin method getMetadata() returns all of the metadata for a collection, as a JSON document.

collectionName.admin().getMetadata();

Creating Custom Metadata for a Collection

Collection metadata is represented as a JSON OracleDocument instance. You can create such an instance directly, but Oracle recommends that you instead use OracleRDBMSMetadataBuilder, which you obtain by invoking OracleRDBMSClient method createMetadataBuilder().

Two methods for creating collections are available on interface OracleDatabaseAdmin (accessed by invoking method admin() on an OracleDatabase object):

createCollection(String collectionName);
createCollection(String collectionName, OracleDocument collectionMetadata);

The first method, which accepts only one argument, creates a collection with the default metadata. The default metadata specifies database schema name, table name (for the table storing the collection), five table columns (key, content, version, last-modified timestamp, and creation timestamp), and the details of these table columns. Each table column is represented by a field with a JSON object as value. That object contains additional details about the column—name, SQL type, and so on.

The default metadata for a collection is presented in Default Collection Metadata in Oracle Database Introduction to Simple Oracle Document Access (SODA).

The second method, which accepts two arguments, lets you provide custom collection metadata in the form of a JSON OracleDocument object.

When invoking a createCollection() method, if a collection with the same name already exists then it is simply opened and its object is returned. If custom metadata is passed to the method and it does not match that of the existing collection then the collection is not opened and an error is raised. (To match, all metadata fields must have the same values.)

Method createMetadataBuilder() returns an OracleRDBMSMetadataBuilder instance that is preloaded with the default collection metadata. You can modify this preloaded metadata by calling OracleRDBMSMetadataBuilder methods that create custom metadata.

These methods correspond to different collection metadata components. You can customize these components by invoking builder methods in a chained manner. At the end of the chain, you invoke method build() to create collection metadata as a JSON OracleDocument object.

Example 5-1 illustrates this; it uses OracleRDBMSMetadataBuilder to create a collection that has custom metadata: a media type column. A media type column lets you store documents that are other than just JSON data, for example images and PDF documents.

The example first uses method createMetadataBuilder() to create a metadata builder object. It then invokes builder methods on that object to define the specific metadata to use, and it invokes build() to create a collectionMetadata object with that metadata. Finally, it creates a new collection that has this metadata.

In this case, the metadata that is specified, and the methods that define it, are as follows:

Method	Metadata
`mediaTypeColumnName()`	The media type column is to be named `MY_MEDIA_TYPE_COLUMN`. By default, there is no media type column.

Example 5-1 Creating a Collection That Has Custom Metadata

OracleRDBMSClient cl = new OracleRDBMSClient();
OracleRDBMSMetadataBuilder b = cl.createMetadataBuilder();
OracleDatabase db = cl.getDatabase(jdbcConnection);
 
// Create custom metadata
OracleDocument collectionMetadata =
  b.mediaTypeColumnName("MY_MEDIA_TYPE_COLUMN").
    build();
 
// Create a new collection with the specified custom metadata
db.admin().createCollection("collectionName", collectionMetadata);

SODA for Java Methods for Collection Metadata Components

The OracleRDBMSMetadataBuilder methods for selecting collection metadata components are described.

The OracleRDBMSMetadataBuilder methods for selecting collection metadata components have names similar to the components they select.

Table 5-1 Java Methods to Select Collection Metadata Components

Component	Method
Schema	`schemaName()`
Table or View	`tableName()` or `viewName()`
Key Column Name	`keyColumnName()`
Key Column Type	`keyColumnType()`
Key Column Max Length	`keyColumnMaxLength()`
Key Column Assignment Method	`keyColumnAssignmentMethod()`
Key Column Sequence Name	`keyColumnSequenceName()`
Content Column Name	`contentColumnName()`
Content Column Type	`contentColumnType()`
Content Column Max Length	`contentColumnMaxLength()`
Content Column JSON Validation	`contentColumnValidation()`
Content Column SecureFiles LOB Compression	`contentColumnCompress()`
Content Column SecureFiles LOB Cache	`contentColumnCache()`
Content Column SecureFiles LOB Encryption	`contentColumnEncrypt()`
Version Column Name	`versionColumnName()`
Version Column Generation Method	`versionColumnMethod()`
Last-Modified Time Stamp Column Name	`lastModifiedColumnName()`
Last-Modified Column Index Name	`lastModifiedColumnIndex()`
Creation Time Stamp Column Name	`creationTimeColumnName()`
Media Type Column Name	`mediaTypeColumnName()`
Read Only	`readOnly()`