SODA collections are highly configurable. You can customize collection metadata, to obtain different behavior from that provided by default.
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
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.
Oracle Database Introduction to Simple Oracle Document Access (SODA) for general information about SODA document collections and their metadata
Oracle Database Introduction to Simple Oracle Document Access (SODA) for reference information about collection metadata components
5.1 Getting the Metadata of an Existing Collection
getMetadata() returns all of the metadata for a collection, as a JSON document.
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
Two methods for creating collections are available on interface
OracleDatabaseAdmin (accessed by invoking method
admin() on an
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
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.)
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
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
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:
The media type column is to be named
There is to be no creation time column. By default,
the column is present. A
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
OracleRDBMSMetadataBuilder methods for selecting collection metadata components are described.
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
OracleRDBMSMetadataBuildermethods Javadoc for more information about collection metadata components
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 LegendFootnote 1:
Reminder: letter case is significant for a quoted SQL identifier; it is interpreted case-sensitively.