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:
-
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
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)
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 |
---|---|
|
The media type column is to be named |
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").
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
See Also:
-
OracleRDBMSMetadataBuilder
methods Javadoc for more information about collection metadata components -
Oracle Database Introduction to Simple Oracle Document Access (SODA)
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.