129 DBMS_XMLSCHEMA

DBMS_XMLSCHEMA package provides procedures to manage XML schemas. It is created by script dbmsxsch.sql during Oracle database installation.

See Also:

Oracle XML DB Developer's Guide

This chapter contains the following topics:

Using DBMS_XMLSCHEMA
- Overview
- Constants
- Views
Summary of DBMS_XMLSCHEMA Subprograms

Using DBMS_XMLSCHEMA

This section contains topics which relate to using the DBMS_XMLSCHEMA package.

Overview
Constants
Views

Overview

This package provides subprograms to

Register an XML schema
Delete a previously registered XML schema
Re-compile a previously registered XML schema
Generate an XML schema
Evolves an XML schema

Constants

The DBMS_XMLSCHEMA package uses the constants shown in following tables.

DBMS_XMLSCHEMA Constants - Delete Option
DBMS_XMLSCHEMA Constants - Enable Hierarchy
DBMS_XMLSCHEMA Constants - Register CSID

Table 129-1 DBMS_XMLSCHEMA Constants - Delete Option

Constant	Type	Value	Description
`DELETE_RESTRICT`	`NUMBER`	`1`	Deletion of an XML schema fails if there are any tables or XML schemas that depend on it
`DELETE_INVALIDATE`	`NUMBER`	`2`	Deletion of an XML schema does not fail if there are tables or XML schemas that depend on it. All dependent tables and schemas are invalidated.
`DELETE_CASCADE`	`NUMBER`	`3`	Deletion of an XML schema also drops all SQL types and default tables associated with it. SQL types are dropped only if `gentypes` argument was set to `TRUE` during registration of the XML schema. However, deletion of the XML schema fails if there are any instance documents conforming to the schema or any dependent XML schemas.
`DELETE_CASCADE_FORCE`	`NUMBER`	`4`	This option is similar to `DELETE_CASCADE` except that it does not check for any stored instance documents conforming to the schema or any dependent XML schemas. Also, it ignores any errors.

Table 129-2 DBMS_XMLSCHEMA Constants - Enable Hierarchy

Constant	Type	Value	Description
`ENABLE_HIERARCHY_NONE`	`PLS_INTEGER`	`1`	The `ENABLE_HIERARCHY` procedure of the `DBMS_XDBZ` package will not be called on any tables created while registering that schema
`ENABLE_HIERARCHY_CONTENTS`	`PLS_INTEGER`	`2`	The `ENABLE_HIERARCHY` procedure of the `DBMS_XDBZ` package will be called for all tables created during schema registration with `hierarchy_type` as `DBMS_XDBZ`.`ENABLE_CONTENTS`
`ENABLE_HIERARCHY_RESMETADATA`	`PLS_INTEGER`	`3`	The `ENABLE_HIERARCHY` procedure of the `DBMS_XDBZ` package will be called on all tables created during schema registration with `hierarchy_type` as `DBMS_XDBZ`.`ENABLE_RESMETADATA`. Users should pass in `DBMS_XMLSCHEMA`.`ENABLE_RESMETADATA` for schemas they intend to use as resource metadata tables.

Table 129-3 DBMS_XMLSCHEMA Constants - Register CSID

Constant	Type	Value	Description
`REGISTER_NODOCID`	`NUMBER`	`1`	If a schema is registered for metadata use (using the value `ENABLE_HIER_RESMETADATA` for parameter enablehierarchy during registration), a column named `DOCID` is added to all tables created during schema registration. This constant can be used in the options argument of `REGISTERSCHEMA` to prevent the creation of this column if the user wishes to optimize on storage
`REGISTER_CSID_NULL`	`NUMBER`	`-1`	If user wishes to not specify the character set of the input schema document when invoking `REGISTERSCHEMA`, this value can be used for the csid parameter

Views

The DBMS_XMLSCHEMA package uses the views shown in Table 129-4. The columns of these views are described in detail in the Oracle Database Reference.

Table 129-4 Summary of Views used by DBMS_XMLSCHEMA

Schema	Description
`USER_XML_SCHEMAS`	All registered XML Schemas owned by the user
`ALL_XML_SCHEMAS`	All registered XML Schemas usable by the current user
`DBA_XML_SCHEMAS`	All registered XML Schemas in the database
`DBA_XML_TABLES`	All `XMLType` tables in the system
`USER_XML_TABLES`	All `XMLType` tables owned by the current user
`ALL_XML_TABLES`	All `XMLType` tables usable by the current user
`DBA_XML_TAB_COLS`	All `XMLType` table columns in the system
`USER_XML_TAB_COLS`	All `XMLType` table columns in tables owned by the current user
`ALL_XML_TAB_COLS`	All `XMLType` table columns in tables usable by the current user
`DBA_XML_VIEWS`	All `XMLType` views in the system
`USER_XML_VIEWS`	All `XMlType` views owned by the current user
`ALL_XML_VIEWS`	All `XMLType` views usable by the current user
`DBA_XML_VIEW_COLS`	All `XMLType` view columns in the system
`USER_XML_VIEW_COLS`	All `XMLType` view columns in views owned by the current user
`ALL_XML_VIEW_COLS`	All `XMLType` view columns in views usable by the current user

Summary of DBMS_XMLSCHEMA Subprograms

Table 129-5 DBMS_XMLSCHEMA Package Subprograms

Method	Description
COMPILESCHEMA Procedure	Used to re-compile an already registered XML schema. This is useful for bringing a schema in an invalid state to a valid state.
COPYEVOLVE Procedure	Evolves registered schemas so that existing XML instances remain valid
DELETESCHEMA Procedure	Removes the schema from the database
GENERATEBEAN Procedure	Generates the Java bean code corresponding to a registered XML schema
GENERATESCHEMA Function	Generates an XML schema from an oracle type name
GENERATESCHEMAS Function	Generates several XML schemas from an oracle type name
REGISTERSCHEMA Procedures	Registers the specified schema for use by Oracle. This schema can then be used to store documents conforming to this.
REGISTERURI Procedure	Registers an XML schema specified by a URI name

COMPILESCHEMA Procedure

This procedure can be used to re-compile an already registered XML schema. This is useful for bringing a schema in an invalid state to a valid state. Can result in a ORA-31001 exception: invalid resource handle or path name.

Syntax

DBMS_XMLSCHEMA.COMPILESCHEMA(
   schemaurl IN VARCHAR2);

Parameters

Table 129-6 COMPILESCHEMA Procedure Parameters

Parameter	Description
`schemaurl`	URL identifying the schema

COPYEVOLVE Procedure

This procedure evolves registered schemas so that existing XML instances remain valid.

This procedure is accomplished in according to the following basic scenario (alternative actions are controlled by the procedure's parameters):

copies data in schema based XMLType tables to temporary table storage
drops old tables
deletes old schemas
registers new schemas
creates new XMLType tables
Populates new tables with data in temporary storage; auxiliary structures (constraints, triggers, indexes, and others) are not preserved

drops temporary tables

See Also:

"Schema Evolution" chapter of the Oracle XML DB Developer's Guide for examples on how to evolve existing schemas
Oracle Database Error Messages for information on exceptions specific to schema evolution, ORA-30142 through ORA-30946.

Syntax

DBMS_XMLSCHEMA.COPYEVOLVE(
   schemaurls       IN  XDB$STRUBG_LIST_T,
   newschemas       IN  XMLSequenceType,
   transforms       IN  XMLSequenceType :=NULL,
   preserveolddocs  IN  BOOLEAN :=FALSE,
   maptablename     IN  VARCHAR2 :=NULL,
   generatetables   IN  BOOLEAN :=TRUE,
   force            IN  BOOLEAN :=FALSE,
   schemaowners     IN  XDB$STRING_LIST_T :=NULL);

Parameters

Table 129-7 COPYEVOLVE Procedure Parameters

Parameter	Description
`schemaurls`	`VARRAY` of URLs of all schemas to be evolved. Should include the dependent schemas. Unless the `FORCE` parameter is `TRUE`, URLs should be in the order of dependency.
`newschemas`	`VARRAY` of new schema documents. Should be specified in same order as the corresponding URLs.
`transforms`	`VARRAY` of transforming XSL documents to be applied to schema-based documents. Should be specified in same order as the corresponding URLs. Optional if no transformations are required.
`preserveolddocs`	Default is `FALSE`, and temporary tables with old data are dropped. If `TRUE`, these table are still available after schema evolution is complete.
`maptabname`	Specifies the name of the table mapping permanent to temporary tables during the evolution process. Valid columns are: `SCHEMA_URL` - `VARCHAR2(700)` - URL of schema to which this table conforms `SCHEMA_OWNER` -`VARCHAR2(30)` - Owner of the schema `ELEMENT_NAME` - `VARCHAR2(256)`- Element to which this table conforms `TAB_NAME` - `VARCHAR2(65)` - Qualified table name: `<owner_name>.<table_name>` `COL_NAME` - `VARCHAR2(4000)` - Name of the column (`NULL` for `XMLType` tables) `TEMP_TABNAME` - `VARCHAR2(30)` - Name of temporary tables which holds data for this table.
`generatetables`	Default is `TRUE`, and new tables will be generated. If `FALSE`: new tables will not be generated after registration of new schemas `preserveolddocs` must be `TRUE` `maptablename` must be non-`NULL`
`force`	Default is `FALSE`. If `TRUE`, ignores errors generated during schema evolution. Used when there are circular dependencies among schemas to ensure that all schemas are stored despite possible errors in registration.
`schemaowners`	`VARRAY` of names of schema owners. Should be specified in same order as the corresponding URLs. Default is NULL, assuming that all schemas are owned by the current user.

Usage Notes

You should back up all schemas and documents prior to invocation because COPYEVOLVE Procedure deletes all conforming documents prior to implementing the schema evolution.

DELETESCHEMA Procedure

This procedure deletes the XML Schema specified by the URL.

Syntax

DBMS_XMLSCHEMA.DELETESCHEMA(
   schemaurl      IN  VARCHAR2,
   delete_option  IN  PLS_INTEGER := DELETE_RESTRICT);

See Also:

"XMLSCHEMA Storage and Query: Basic" chapter of the Oracle XML DB Developer's Guide

Parameters

Table 129-8 DELETESCHEMA Procedure Parameters

Parameter	Description
`schemaurl`	URL identifying the schema to be deleted

Exceptions

Table 129-9 DELETESCHEMA Procedure Exceptions

Exception	Description
`ORA-31001`	Invalid resource handle or path name

GENERATEBEAN Procedure

This procedure can be used to generate the Java bean code corresponding to a registered XML schema.

Syntax

DBMS_XMLSCHEMA.GENERATEBEAN(
   schemaurl  IN  VARCHAR2);

Parameters

Table 129-10 GENERATEBEAN Procedure Parameters

Parameter	Description
`schemaurl`	Name identifying a registered XML schema

Exceptions

Table 129-11 GENERATEBEAN Procedure Exceptions

Exception	Description
`ORA-31001`	Invalid resource handle or path name

Usage Notes

Note that there is also an option to generate the beans as part of the registration procedure itself (see the genbean parameter of the REGISTERSCHEMA Procedures).

GENERATESCHEMA Function

This function generates XML schema(s) from an Oracle type name. It inlines all in one schema (XMLType).

See Also:

"XMLSCHEMA Storage and Query: Advanced" chapter of the Oracle XML DB Developer's Guide

Syntax

DBMS_XMLSCHEMA.GENERATESCHEMA( 
   schemaname    IN  VARCHAR2,
   typename      IN  VARCHAR2,
   elementname   IN  VARCHAR2 := NULL,
   recurse       IN  BOOLEAN  := TRUE,
   annotate      IN  BOOLEAN  := TRUE,
   embedcoll     IN  BOOLEAN  := TRUE) 
RETURN SYS.XMLTYPE;

Parameters

Table 129-12 GENERATESCHEMA Function Parameters

Parameter	Description
`schemaname`	Name of the database schema containing the type
`typename`	Name of the Oracle type
`elementname`	The name of the top level element in the XML Schema. Defaults to `typename`.
`recurse`	Whether or not to also generate schema for all types referred to by the type specified
`annotate`	Whether or not to put the SQL annotations in the XML Schema
`embedcoll`	Determines whether the collections should be embedded in the type which refers to them, or create a `complextype`. Cannot be `FALSE` if annotations are turned on

Exceptions

Table 129-13 GENERATESCHEMA Procedure Exceptions

Exception	Description
`ORA-31001`	Invalid resource handle or path name

GENERATESCHEMAS Function

This function generates XML schema(s) from an Oracle type name. It returns a collection of XMLTypes, one XML Schema document for each database schema.

See Also:

"XMLSCHEMA Storage and Query: Advanced" chapter of the Oracle XML DB Developer's Guide

Syntax

DBMS_XMLSCHEMA.GENERATESCHEMAS( 
   schemaname   IN  VARCHAR2,
   typename     IN  VARCHAR2,
   elementname  IN  VARCHAR2 := NULL,
   schemaurl    IN  VARCHAR2 := NULL,
   annotate     IN  BOOLEAN := TRUE,
   embedcoll    IN  BOOLEAN := TRUE ) 
 RETURN SYS.XMLTYPE;

Parameters

Table 129-14 GENERATESCHEMAS Procedure Parameters

Parameter	Description
`schemaname`	Name of the database schema containing the type
`typename`	Name of the Oracle type
`elementname`	The name of the top level element in the XML Schema defaults to `typeName`
`schemaurl`	Specifies base URL where schemas will be stored, needed by top level schema for import statement
`annotate`	Whether or not to put the SQL annotations in the XML Schema
`embedcoll`	Determines whether the collections be embedded in the type which refers to them, or create a `complextype`. Cannot be `FALSE` if annotations are turned on

Exceptions

Table 129-15 GENERATESCHEMAS Procedure Exceptions

Exception	Description
`ORA-31001`	Invalid resource handle or path name

REGISTERSCHEMA Procedures

This procedure registers the specified schema for use by the database. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definition.

See Also:

"XMLSCHEMA Storage and Query: Basic" chapter of the Oracle XML DB Developer's Guide

Syntax

Registers a schema specified as a VARCHAR2:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
    schemaurl        IN  VARCHAR2,
    schemadoc        IN  VARCHAR2,
    local            IN  BOOLEAN := TRUE,
    gentypes         IN  BOOLEAN := TRUE,
    genbean          IN  BOOLEAN := FALSE,
    gentables        IN  BOOLEAN := TRUE,
    force            IN  BOOLEAN := FALSE,
    owner            IN  VARCHAR2 := NULL,
    enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
    options          IN  PLS_INTEGER := 0);

Registers the schema specified as a BFILE. The contents of the schema document must be in the database character set:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2,
   schemadoc        IN  BFILE,
   local            IN  BOOLEAN := TRUE,
   gentypes         IN  BOOLEAN := TRUE,
   genbean          IN  BOOLEAN := FALSE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);

Registers the schema specified as a BFILE and identifies the character set id of the schema document:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  BFILE, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := TRUE,
   gentables        IN  BOOLEAN := TRUE,
   force            IN  BOOLEAN := TRUE,
   owner            IN  VARCHAR2 := '',
   csid             IN  NUMBER,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);

Registers the schema specified as a BLOB. The contents of the schema document must be in the database character set:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  BLOB, 
   local            IN  BOOLEAN := TRUE, 
   genTypes         IN  BOOLEAN := TRUE, 
   genBean          IN  BOOLEAN := FASLE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);

Registers the schema specified as a BLOB and identifies the character set id of the schema document:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  BLOB, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := TRUE,
   gentables        IN  BOOLEAN := TRUE,
   force            IN  BOOLEAN := TRUE,
   owner            IN  VARCHAR2 := '',
   csid             IN  NUMBER,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);

Registers the schema specified as a CLOB

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  CLOB, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := FALSE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   options          IN  PLS_INTEGER := 0);

Registers the schema specified as an XMLTYPE.

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  SYS.XMLTYPE, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := FALSE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);

Registers the schema specified as a BLOB. The contents of the schema document must be in the database character set:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  SYS.URIType, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := FALSE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);

Parameters

Table 129-16 REGSITERSCHEMA Procedure Parameters

Parameter	Description
`schemaurl`	URL that uniquely identifies the schema document. This value is used to derive the path name of the schema document within the database hierarchy. Can be used inside `schemalocation` attribute of XML Schema import element.
`schemadoc`	A valid XML schema document
`local`	Is this a local or global schema? By default, all schemas are registered as local schemas, under `/sys/schemas/<username>/...` If a schema is registered as global, it is added under `/sys/schemas/PUBLIC/...` You need write privileges on the directory to be able to register a schema as global.
`gentypes`	Determines whether the schema compiler generates object types. By default, `TRUE.`
`genbean`	Determines whether the schema compiler generates Java beans. By default, `FALSE`.
`gentables`	Determines whether the schema compiler generates default tables. By default, `TRUE`
`force`	If this parameter is set to `TRUE`, the schema registration will not raise errors. Instead, it creates an invalid XML schema object in case of any errors. By default, the value of this parameter is `FALSE`.
`owner`	This parameter specifies the name of the database user owning the XML schema object. By default, the user registering the schema owns the XML schema object. This parameter can be used to register a XML schema to be owned by a different database user.
`csid`	Identifies the character set of the input schema document. If this value is `0`, the schema document's encoding is determined by the current rule for "text/xml" MIME type.
`enablehierarchy`	`ENABLE_HIERARCHY_NONE` - enable hierarchy will not be called on any tables created while registering that schema `ENABLE_HIERARCHY_CONTENTS` - enable hierarchy will be called for all tables created during schema registration with `hierarchy_type` as `DBMS_XDBZ`.`ENABLE_CONTENTS`. This is the default. `ENABLE_HIERARCHY_RESMETADATA` - enable hierarchy will be called on all tables created during schema registration with `hierarchy_type` as `DBMS_XDBZ`.`ENABLE_RESMETADATA`. Users should pass in `DBMS_XMLSCHEMA`.`ENABLE_RESMETADATA` for schemas they intend to use as resource metadata tables.
`options`	Additional options to specify how the schema should be registered. The various options are represented as bits of an integer and the options parameter should be constructed by doing a `BITOR` of the desired bits. Possible bits: `REGISTER_NODOCID` - this will suppress the creation of the `DOCID` column for out of line tables. This is a storage optimization which might be desirable when we do not need to join back to the document table (for example if we do not care about rewriting certain queries that could be rewritten by making use of the `DOCID` column)

REGISTERURI Procedure

This procedure registers an XML Schema specified by a URI name.

Syntax

DBMS_XMLSCHEMA.REGISTERURI(
   schemaurl      IN  VARCHAR2,
   schemadocuri   IN  VARCHAR2,
   local          IN  BOOLEAN := TRUE,
   gentypes       IN  BOOLEAN := TRUE,
   genbean        IN  BOOLEAN := FALSE,
   gentables      IN  BOOLEAN := TRUE,
   force          IN  BOOLEAN := FALSE,
   owner          IN  VARCHAR2 := NULL, 
   options          IN  PLS_INTEGER := 0);

Parameters

Table 129-17 REGISTERURI Procedure Parameters

Parameter	Description
`schemaurl`	Uniquely identifies the schema document. Can be used inside `schemaLocation` attribute of XML Schema import element.
`schemadocuri`	Pathname (URI) corresponding to the physical location of the schema document. The URI path could be based on HTTP, FTP, DB or Oracle XML DB protocols. This function constructs a `URIType` instance using the `urifactory` - and invokes the REGISTERSCHEMA Procedures function.
`local`	Determines whether this is a local or global schema. By default, all schemas are registered as local schemas, under `/sys/schemas/ <username>/...` If a schema is registered as global, it is added under `/sys/schemas/PUBLIC/...` The user needs write privileges on the directory to register a global schema.
`gentypes`	Determines whether the compiler generate object types. By default, `TRUE`.
`genbean`	Determines whether the compiler generate Java beans. By default, `FALSE`.
`gentables`	Determines whether the compiler generate default tables. `TRUE` by default.
`force`	`TRUE:` schema registration will not raise errors. Instead, it creates an invalid XML schema object in case of any errors. By default, the value of this parameter is `FALSE`.
`owner`	This parameter specifies the name of the database user owning the XML schema object. By default, the user registering the schema owns the XML schema object. This parameter can be used to register a XML schema to be owned by a different database user.
`options`	Additional options to specify how the schema should be registered. The various options are represented as bits of an integer and the options parameter should be constructed by doing a `BITOR` of the desired bits. Possible bits: `REGISTER_NODOCID` - this will suppress the creation of the `DOCID` column for out of line tables. This is a storage optimization which might be desirable when we do not need to join back to the document table (for example if we do not care about rewriting certain queries that could be rewritten by making use of the `DOCID` column)