118
DBMS_XMLSCHEMA

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

This chapter contains the following topics:

Constants of DBMS_XMLSCHEMA

Table 118-1 Constants of DBMS_XMLSCHEMA

Constant	Description
DELETE_RESTRICT	CONSTANT NUMBER := 1;
DELETE_INVALIDATE	CONSTANT NUMBER := 2;
DELETE_CASCADE	CONSTANT NUMBER := 3;
DELETE_CASCADE_FORCE	CONSTANT NUMBER := 4;

Summary of DBMS_XMLSCHEMA Subprograms

Table 118-2 DBMS_XMLSCHEMA Package Subprograms

Method	Description
`COMPILESCHEMA`	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`	Evolves registered schemas so that existing XML instances remain valid.
`DELETESCHEMA`	Removes the schema from the database.
`GENERATEBEAN`	Generates the Java bean code corresponding to a registered XML schema
`GENERATESCHEMA`	Generates an XML schema from an oracle type name.
`GENERATESCHEMAS`	Generates several XML schemas from an oracle type name.
`REGISTERSCHEMA`	Registers the specified schema for use by Oracle. This schema can then be used to store documents conforming to this.
`REGISTERURI`	Registers an XMLSchema specified by a URI name.

COMPILESCHEMA

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

PROCEDURE compileSchema(
   SCHEMAURL IN VARCHAR2);

Parameter	IN / OUT	Description
SCHEMAURL	(IN)	URL identifying the schema.

COPYEVOLVE

Evolves registered schemas so that existing XML instances remain valid. You should back up all schemas and documents prior to invocation because COPYEVOLVE deletes all conforming documents prior to implementing the schema evolution.

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

PROCEDURE 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);

Parameter	IN / OUT	Description
schemaURLs	(IN)	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	(IN)	Varray of new schema documents. Should be specified in same order as the corresponding URLs.
transforms	(IN)	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	(IN)	Default is `FALSE`, and temporary tables with old data are dropped. If `TRUE`, these table are still available after schema evolution is complete.
mapTabName	(IN)	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	(IN)	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	(IN)	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	(IN)	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.

DELETESCHEMA

Deletes the XML Schema specified by the URL. Can result in a ORA-31001 exception: invalid resource handle or path name.

Syntax

PROCEDURE deleteSchema(
   SCHEMAURL IN VARCHAR2,
   delete_option IN pls_integer := DELETE_RESTRICT);

Parameter IN / OUT Description

Parameter	IN / OUT	Description
SCHEMAURL	(IN)	URL identifying the schema to be deleted.
delete_option	(IN)	Option for deleting schema. Valid values are: DELETE_RESTRICT - Schema deletion fails if there are any tables or schemas that depend on this schema. DELETE_INVALIDATE - Schema deletion does not fail if there are any dependencies. Instead, it simply invalidates all dependent objects. DELETE_CASCADE - Schema deletion will also drop all default SQL types and default tables. The deletion fails if there are any stored instances conforming to this schema. DELETE_CASCADE_FORCE - Similar to `DELETE_CASCADE`, except that it does not check for any stored instances conforming to this schema. Also ignores any errors.

SCHEMAURL

(IN)

URL identifying the schema to be deleted.

delete_option

(IN)

Option for deleting schema. Valid values are:

DELETE_RESTRICT - Schema deletion fails if there are any tables or schemas that depend on this schema.
DELETE_INVALIDATE - Schema deletion does not fail if there are any dependencies. Instead, it simply invalidates all dependent objects.
DELETE_CASCADE - Schema deletion will also drop all default SQL types and default tables. The deletion fails if there are any stored instances conforming to this schema.
DELETE_CASCADE_FORCE - Similar to DELETE_CASCADE, except that it does not check for any stored instances conforming to this schema. Also ignores any errors.

GENERATEBEAN

This procedure can be used to generate the Java bean code corresponding to a registered XML schema. Note that there is also an option to generate the beans as part of the registration procedure itself. Can result in a ORA-31001 exception: invalid resource handle or path name.

Syntax

PROCEDURE generateBean(
   SCHEMAURL IN VARCHAR2);

Parameter	IN / OUT	Description
SCHEMAURL	(IN)	Name identifying a registered XML schema.

GENERATESCHEMA

These functions generate XML schema(s) from an Oracle type name. Inlines all in one schema (XMLType). Can result in a ORA-31001 exception: invalid resource handle or path name.

Syntax

function 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;

Parameter	IN / OUT	Description
schemaName	(IN)	Name of the database schema containing the type.
typeName	(IN)	Name of the Oracle type.
elementName	(IN)	The name of the top level element in the XML Schema defaults to `typeName`.
recurse	(IN)	Whether or not to also generate schema for all types referred to by the type specified.
annotate	(IN)	Whether or not to put the SQL annotations in the XML Schema.
embedColl	(IN)	Should the collections be embedded in the type which refers to them, or create a `complexType`? Cannot be `FALSE` if annotations are turned on.

GENERATESCHEMAS

These functions generate XML schema(s) from an Oracle type name. Returns a collection of XMLTypes, one XML Schema document for each database schema. Can result in a ORA-31001 exception: invalid resource handle or path name.

Syntax

function generateSchema( 
   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;

Parameter	IN / OUT	Description
schemaName	(IN)	Name of the database schema containing the type.
typeName	(IN)	Name of the Oracle type.
elementName	(IN)	The name of the top level element in the XML Schema defaults to `typeName`.
schemaURL	(IN)	Specifies base URL where schemas will be stored, needed by top level schema for import statement.
annotate	(IN)	Whether or not to put the SQL annotations in the XML Schema.
embedColl	(IN)	Should the collections be embedded in the type which refers to them, or create a `complexType`? Cannot be `FALSE` if annotations are turned on.

REGISTERSCHEMA

Registers the specified schema for use by the database.

Syntax	Description
PROCEDURE 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);	Registers a schema specified as a `VARCHAR2`.
PROCEDURE 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);	Registers the schema specified as a `BFILE`. The contents of the schema document must be in the database character set.
PROCEDURE 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);	Registers the schema specified as a `BFILE` and identifies the character set id of the schema document.
PROCEDURE 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);	Registers the schema specified as a `BLOB`. The contents of the schema document must be in the database character set.
PROCEDURE 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);	Registers the schema specified as a `BLOB` and identifies the character set id of the schema document.
PROCEDURE registerSchema( SCHEMAURL IN VARCHAR2, schemaDoc IN CLOB, local IN BOOLEAN := TRUE, genTypes IN BOOLEAN := TRUE, genBean IN BOOLEAN := FASLE, force IN BOOLEAN := FALSE, owner IN VARCHAR2 := null);	Registers the schema specified as a `CLOB`.
PROCEDURE 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);	Registers the schema specified as an `XMLType`.
PROCEDURE 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);	Registers the schema specified as a `URIType`.

Parameter	IN / OUT	Description
SCHEMAURL	(IN)	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	(IN)	A valid XML schema document.
local	(IN)	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	(IN)	Should the schema compiler generate object types? By default, `TRUE.`
genBean	(IN)	Should the schema compiler generate Java beans? By default, `FALSE`.
genTables	(IN)	Should the schema compiler generate default tables? By default, `TRUE`
force	(IN)	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	(IN)	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	(IN)	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.

REGISTERURI

Registers an XML Schema specified by a URI name.

Syntax

PROCEDURE 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);

Parameter	IN / OUT	Description
SCHEMAURL	(IN)	Uniquely identifies the schema document. Can be used inside `schemaLocation` attribute of XML Schema import element.
schemaDocURI	(IN)	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` function.
local	(IN)	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/...` The user needs write privileges on the directory to register a global schema.
genTypes	(IN)	Should the compiler generate object types? By default, `TRUE`.
genbean	(IN)	Should the compiler generate Java beans? By default, `FALSE`.
genTables	(IN)	Should the compiler generate default tables? `TRUE` by default.
force	(IN)	`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	(IN)	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.

Catalog Views of the DBMS_XMLSCHEMA

Table 118-3 Summary of Catalog View Schemas

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.

USER_XML_SCHEMAS

Lists all schemas (local and global) belonging to the current user.

Column	Datatype	Description
SCHEMA_URL	VARCHAR2	URL of XML schema
LOCAL	VARCHAR2	Local schema (YES/NO)
SCHEMA	XMLTYPE	XML Schema document

ALL_XML_SCHEMAS

Lists all local schemas belonging to the current user and all global schemas.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning XML schema
SCHEMA_URL	VARCHAR2	URL of XML schema
LOCAL	VARCHAR2	Local schema (YES/NO)
SCHEMA	XMLTYPE	XML Schema document

DBA_XML_SCHEMAS

Lists all registered local and global schemas in the system.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning XML schema
SCHEMA_URL	VARCHAR2	URL of XML schema
LOCAL	VARCHAR2	Local schema (YES/NO)
SCHEMA	XMLTYPE	XML Schema document

DBA_XML_TABLES

Lists all XMLType tables in the system.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning table
TABLE_NAME	VARCHAR2	Name of `XMLType` table
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element
STORAGE_TYPE	VARCHAR2	Storage type: `CLOB` / `OBJECT-RELATIONAL`

USER_XML_TABLES

Lists all local XMLType tables belonging to the current user.

Column	Datatype	Description
TABLE_NAME	VARCHAR2	Name of `XMLType` table
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element
STORAGE_TYPE	VARCHAR2	Storage type: CLOB / `OBJECT-RELATIONAL`

ALL_XML_TABLES

Lists all local XMLType tables belonging to the current user and all global tables visible to the current user.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning table
TABLE_NAME	VARCHAR2	Name of `XMLType` table
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element
STORAGE_TYPE	VARCHAR2	Storage type: `CLOB` / `OBJECT-RELATIONAL`

DBA_XML_TAB_COLS

Lists all XMLType columns in the system.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning table
TABLE_NAME	VARCHAR2	Name of table
COLUMN_NAME	VARCHAR2	Name of `XMLType` column
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element
STORAGE_TYPE	VARCHAR2	Storage type: `CLOB` / `OBJECT-RELATIONAL`

USER_XML_TAB_COLS

Lists all XMLType columns in tables belonging to the current user.

Column	Datatype	Description
TABLE_NAME	VARCHAR2	Name of table
COLUMN_NAME	VARCHAR2	Name of `XMLType` column
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element
STORAGE_TYPE	VARCHAR2	Storage type: `CLOB` / `OBJECT-RELATIONAL`

ALL_XML_TAB_COLS

Lists all XMLType columns in tables belonging to the current user and all global tables visible to the current user.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning table
TABLE_NAME	VARCHAR2	Name of table
COLUMN_NAME	VARCHAR2	Name of `XMLType` column
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element
STORAGE_TYPE	VARCHAR2	Storage type: `CLOB` / `OBJECT-RELATIONAL`

DBA_XML_VIEWS

Lists all XMLType views in the system.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning view
VIEW_NAME	VARCHAR2	Name of `XMLType` view
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element

USER_XML_VIEWS

Lists all local XMLType views belonging to the current user.

Column	Datatype	Description
VIEW_NAME	VARCHAR2	Name of `XMLType` view
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element

ALL_XML_VIEWS

Lists all local XMLType views belonging to the current user and all global views visible to the current user.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning view
VIEW_NAME	VARCHAR2	Name of `XMLType` view
XMLSCHEMA	VARCHAR2	XML Schema URL
ELEMENT_NAME	VARCHAR2	XML Schema element

DBA_XML_VIEW_COLS

Lists all XMLType columns in the system.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning view.
VIEW_NAME	VARCHAR2	Name of view.
COLUMN_NAME	VARCHAR2	Name of `XMLType` column.
XMLSCHEMA	VARCHAR2	XML Schema URL.
ELEMENT_NAME	VARCHAR2	XML Schema element.

USER_XML_VIEW_COLS

Lists all XMLType columns in views belonging to the current user.

Column	Datatype	Description
VIEW_NAME	VARCHAR2	Name of view.
COLUMN_NAME	VARCHAR2	Name of `XMLType` column.
XMLSCHEMA	VARCHAR2	XML Schema URL.
ELEMENT_NAME	VARCHAR2	XML Schema element.

ALL_XML_VIEW_COLS

Lists all XMLType columns in views belonging to the current user and all global views visible to the current user.

Column	Datatype	Description
OWNER	VARCHAR2	Database user owning view.
VIEW_NAME	VARCHAR2	Name of view.
COLUMN_NAME	VARCHAR2	Name of `XMLType` column.
XMLSCHEMA	VARCHAR2	XML Schema URL.
ELEMENT_NAME	VARCHAR2	XML Schema element.

118 DBMS_XMLSCHEMA

Constants of DBMS_XMLSCHEMA

Table 118-1 Constants of DBMS_XMLSCHEMA

Summary of DBMS_XMLSCHEMA Subprograms

Table 118-2 DBMS_XMLSCHEMA Package Subprograms

COMPILESCHEMA

Syntax

COPYEVOLVE

Syntax

DELETESCHEMA

Syntax

GENERATEBEAN

Syntax

GENERATESCHEMA

Syntax

GENERATESCHEMAS

Syntax

REGISTERSCHEMA

REGISTERURI

Syntax

Catalog Views of the DBMS_XMLSCHEMA

Table 118-3 Summary of Catalog View Schemas

USER_XML_SCHEMAS

ALL_XML_SCHEMAS

DBA_XML_SCHEMAS

DBA_XML_TABLES

USER_XML_TABLES

ALL_XML_TABLES

DBA_XML_TAB_COLS

USER_XML_TAB_COLS

ALL_XML_TAB_COLS

DBA_XML_VIEWS

USER_XML_VIEWS

ALL_XML_VIEWS

DBA_XML_VIEW_COLS

USER_XML_VIEW_COLS

ALL_XML_VIEW_COLS

118
DBMS_XMLSCHEMA