Package oracle.soda.rdbms

Interface OracleRDBMSMetadataBuilder

  • public interface OracleRDBMSMetadataBuilder
    Builds custom collection metadata, expressed as a JSON OracleDocument. The resulting OracleDocument must be supplied to OracleDatabaseAdmin.createCollection(String, OracleDocument) method to create a collection with the provided metadata. Custom collection metadata is needed when you want to specify, for example, how the collection is stored, or that the collection is read-only, or remove some of the optional (e.g. version, created-on timestamp, last modified timestamp) columns from the underlying table storing the collection. Custom collection metadata can also be used to map a pre-existing SQL table to a new SODA collection.

    The builder is created as follows: 

         OracleRDBMSClient client = ...
     OracleRDBMSMetadataBuilder builder = client.createMetadataBuilder();
    The resulting builder is initialized with default metadata settings. These settings can be modified using various OracleRDBMSMetadataBuilder methods. For example, to change the key assignment method to client-assigned, and to change the content column type to VARCHAR2, invoke keyColumnAssignmentMethod(String) and contentColumnType(String) as follows: 

         builder.keyColumnAssignmentMethod("CLIENT").contentColumnType("VARCHAR2");
    Once the desired changes to the default metadata settings are made, the OracleDocument representing collection metadata in JSON should be created as follows: 

         OracleDocument metadata = builder.build();
    This metadata document is supplied to the OracleDatabaseAdmin.createCollection(String, OracleDocument) method to create a collection with the specified custom metadata: 

         OracleDatabase db = ...
     OracleCollection collection = db.admin().createCollection("myCollection", metadata);
    See Also:
    OracleRDBMSClient.createMetadataBuilder(), OracleDatabaseAdmin.createCollection(String, oracle.soda.OracleDocument)

    • Method Detail

      • schemaName

        OracleRDBMSMetadataBuilder schemaName​(String schemaName)
        Sets the SQL schema name for the underlying database object. If schemaName is null, the schema associated with the connection will be used.
        Parameters:
        schemaName - the name of the schema or null
        Returns:
        a reference to this object

      • tableName

        OracleRDBMSMetadataBuilder tableName​(String tableName)
        Sets the SQL table name. A collection is based off of a table or a view. Calling this method will override the view name if previously set using viewName(String). If tableName is null, the collection will be created using a table name based on the name of the collection name.
        Parameters:
        tableName - the name of the table. May be null
        Returns:
        a reference to this object
        See Also:
        viewName(String)

      • viewName

        OracleRDBMSMetadataBuilder viewName​(String viewName)
        Sets the SQL view name. A collection is based off of a table or a view. Calling this method will override the table name if previously set using tableName(String) If viewName is null, the collection will be created using a table name based on the name of the collection name.
        Parameters:
        viewName - the name of the view. May be null
        Returns:
        a reference to this object
        See Also:
        tableName(String)

      • contentColumnName

        OracleRDBMSMetadataBuilder contentColumnName​(String name)
        Sets the name of the content column. If name is null, the default value "JSON_DOCUMENT" is used.
        Parameters:
        name - the name of the column. May be null
        Returns:
        a reference to this object

      • contentColumnType

        OracleRDBMSMetadataBuilder contentColumnType​(String sqlType)
                                      throws OracleException
        Sets the SQL type of the content column. The value must be either "VARCHAR2", "NVARCHAR2", "RAW", "BLOB", "CLOB", or "NCLOB". If sqlType is null, the default value "BLOB" is used.

        Changing the content column type may automatically remove other related settings:

        • Setting to LOB type will remove the content column maximum length.
        • Setting to a non-LOB type will remove all SecureFile LOB settings.
        Parameters:
        sqlType - the type of the content column. May be null
        Returns:
        a reference to this object
        Throws:
        OracleException - if sqlType is not one of the expected values

      • contentColumnMaxLength

        OracleRDBMSMetadataBuilder contentColumnMaxLength​(int maxLength)
                                           throws OracleException
        Sets the maximum length of the content column. If maxLength is 0, then the maximum is unspecified and the default value of 2000 will be used, if applicable. If the content column type is a LOB type and a maximum length is specified, an error will be raised when build() is called.
        Parameters:
        maxLength - the maximum size
        Returns:
        a reference to this object
        Throws:
        OracleException - if maxLength is negative
        See Also:
        contentColumnType(String)

      • contentColumnValidation

        OracleRDBMSMetadataBuilder contentColumnValidation​(String validation)
                                            throws OracleException
        Sets the validation mode for the content column. The value of validation must be one of "STANDARD", "STRICT", or "LAX". If validation is null, the default "STANDARD" mode is used.
        Parameters:
        validation - the validation mode. May be null
        Returns:
        a reference to this object.
        Throws:
        OracleException - if validation is not null, "STANDARD", "STRICT", or "LAX"

      • contentColumnCompress

        OracleRDBMSMetadataBuilder contentColumnCompress​(String compress)
                                          throws OracleException
        Sets the SecureFiles LOB compress setting for the content column. The value of compress must be one of "NONE", "HIGH", "MEDIUM", or "LOW". This setting is not applicable if the content column type is not a LOB type. If compress is null, the default value "NONE" is used.

        If the compression is set to something other than "NONE" and the column is not a LOB type, an error will be raised when build() is called.

        Parameters:
        compress - the compression mode. May be null
        Returns:
        a reference to this object
        Throws:
        OracleException - if compress is not one of the expected values
        See Also:
        contentColumnType(String)

      • contentColumnCache

        OracleRDBMSMetadataBuilder contentColumnCache​(boolean cache)
        Sets the SecureFiles LOB cache setting for the content column. This setting is not applicable if the content column type is not a LOB type. The default value is true.

        If the cache is true and the column is not a LOB type, an error will be raised when build() is called.

        Parameters:
        cache - specifies if caching is used
        Returns:
        a reference to this object
        See Also:
        contentColumnType(String)

      • contentColumnEncrypt

        OracleRDBMSMetadataBuilder contentColumnEncrypt​(String encrypt)
                                         throws OracleException
        Sets the SecureFiles LOB encryption setting for the content column. The value of encrypt must be "NONE", "3DES168", "AES128", "AES192", "AES256". If encrypt is null, the default value "NONE" is used. This setting is not applicable if the content column type is not a LOB type. If encrypt is anything other than "NONE" and the column is not a LOB type, an error will be raised when build() is called.
        Parameters:
        encrypt - the encryption type. May be null
        Returns:
        a reference to this object
        Throws:
        OracleException - if encrypt is not one of the expected values
        See Also:
        contentColumnType(String)

      • keyColumnName

        OracleRDBMSMetadataBuilder keyColumnName​(String name)
        Sets the name of the key column. If name is null, they default value "ID" is used.
        Parameters:
        name - the name of the key column. May be null
        Returns:
        a reference to this object

      • keyColumnType

        OracleRDBMSMetadataBuilder keyColumnType​(String sqlType)
                                  throws OracleException
        Sets the key column type. The value of sqlType must be one of "VARCHAR2", "NVARCHAR2", "NUMBER", or "RAW". If sqlType is null, the default value "VARCHAR2" will be used. Setting the key column type to "NUMBER" or "RAW" automatically removes the maximum size of the key column.
        Parameters:
        sqlType - the key column type. May be null
        Returns:
        a reference to this object
        Throws:
        OracleException - if sqlType is not one of the expected values.

      • keyColumnMaxLength

        OracleRDBMSMetadataBuilder keyColumnMaxLength​(int maxLength)
                                       throws OracleException
        Sets the maximum size of the key column. If maxLength is 0, then the maximum is unspecified and the default value of 255 will be used, if applicable. If the key column type is NUMBER or RAW and a maximum length is specified, an error will be raised when build() is called.
        Parameters:
        maxLength - the maximum size
        Returns:
        a reference to this object
        Throws:
        OracleException - if maxLength is negative
        See Also:
        keyColumnType(String)

      • keyColumnAssignmentMethod

        OracleRDBMSMetadataBuilder keyColumnAssignmentMethod​(String assignmentMethod)
                                              throws OracleException
        Sets the key column assignment method. The value of assignmentMethod must be one of "SEQUENCE", "GUID", "UUID", or "CLIENT". If assignmentMethod is null, the default value "UUID" will be used. If assignmentMethod is anything other than "SEQUENCE", the key column sequence name will be automatically removed. If the assignment method is "SEQUENCE" but no key column sequence name is specified, an error will be raised when build() is called.
        Parameters:
        assignmentMethod - the key column assignment method. May be null
        Returns:
        a reference to this object
        Throws:
        OracleException - if assignmentMethod is not one of the expected values
        See Also:
        keyColumnSequenceName(String)

      • keyColumnSequenceName

        OracleRDBMSMetadataBuilder keyColumnSequenceName​(String sequenceName)
        Sets the sequence name for sequence-based keys. If sequenceName is null, the sequence name is unspecified. Specifying a sequence name automatically changes the key column assignment method to "SEQUENCE".
        Parameters:
        sequenceName - the name of the sequence. May be null
        Returns:
        a reference to this object
        See Also:
        keyColumnAssignmentMethod(String)

      • creationTimeColumnName

        OracleRDBMSMetadataBuilder creationTimeColumnName​(String name)
        Sets the optional creation time column name. If name is null, no creation time column will be used. The default value is "CREATED_ON".
        Parameters:
        name - the name of the column. May be null
        Returns:
        a reference to this object

      • lastModifiedColumnName

        OracleRDBMSMetadataBuilder lastModifiedColumnName​(String name)
        Sets the optional last-modified timestamp column name. If name is null, no last-modified column will be used and the last-modified column index will automatically be removed. The default value is "LAST_MODIFIED".
        Parameters:
        name - the name of the column. May be null
        Returns:
        a reference to this object
        See Also:
        lastModifiedColumnIndex(String)

      • lastModifiedColumnIndex

        OracleRDBMSMetadataBuilder lastModifiedColumnIndex​(String index)
        Sets the last-modified column index name. If index is null, the index name is unspecified. If the last-modified index name is specified but the last-modified column name is not set, an error will be raised when build() is called.
        Parameters:
        index - the name of the index. May be null
        Returns:
        a reference to this object
        See Also:
        lastModifiedColumnName(String)

      • versionColumnName

        OracleRDBMSMetadataBuilder versionColumnName​(String name)
        Sets the version (ETag) column name. If name is null, the version column will not be used and the version column method will automatically set to "NONE". The default value is "VERSION".
        Parameters:
        name - the name of the column. May be null
        Returns:
        a reference to this object
        See Also:
        versionColumnMethod(String)

      • versionColumnMethod

        OracleRDBMSMetadataBuilder versionColumnMethod​(String method)
                                        throws OracleException
        Sets version column method. The value of method must be "SEQUENTIAL", "TIMESTAMP", "UUID", "SHA256", "MD5", or "NONE". If method is null, the default value "NONE" is used. If the version column method is not "NONE" and the version column name is not specified, an error will be raised when build() is called.
        Parameters:
        method - the version method. May be null
        Returns:
        a reference to this object
        Throws:
        OracleException - if method is not one of the expected values

      • mediaTypeColumnName

        OracleRDBMSMetadataBuilder mediaTypeColumnName​(String name)
        Sets the media type column name. If name is null, the media type column is unspecified and a media type column will not be used. If the content column type is not "BLOB" and the media type column is specified, an error will be raised when build() is called. By default, the media type column is unspecified.
        Parameters:
        name - the name of the media type column. May be null
        Returns:
        a reference to this object

      • readOnly

        OracleRDBMSMetadataBuilder readOnly​(boolean readOnly)
        Sets the read/write policy. The default value is false.
        Parameters:
        readOnly - when true, specifies the collection is read only
        Returns:
        a reference to this object

      • removeOptionalColumns

        OracleRDBMSMetadataBuilder removeOptionalColumns()
        Removes the optional metadata columns. This method is useful when creating a collection over an existing table where these columns may not exist.

        Calling this method is equivalent to the following: 

           this
    .creationTimeColumnName(null)
    .lastModifiedColumnName(null)
    .versionColumnName(null)
    .mediaTypeColumnName(null);
        Returns:
        a reference to this object