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.

See Also:

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

See Also:

Default Collection Metadata example in Oracle Database Introduction to Simple Oracle Document Access (SODA)

5.2 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. (See Default Collection Metadata example 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 and no creation time column. It 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.

creationTimeColumnName()

There is to be no creation time column. By default, the column is present. A null value here specifies that it is absent.

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

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").
    creationTimeColumnName(null).
    build();
 
// Create a new collection with the specified custom metadata
db.admin().createCollection("collectionName", collectionMetadata);

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

See Also:

Note:

The identifiers used for collection metadata components (schema name, table name, view name, database sequence name, and column names) must be valid Oracle quoted identifiers.Foot 1 Some characters and words that are allowed in Oracle quoted identifiers are strongly discouraged. For details, see Oracle Database SQL Language Reference.



Footnote Legend

Footnote 1:

Reminder: letter case is significant for a quoted SQL identifier; it is interpreted case-sensitively.