231 DBMS_XMLSCHEMA
DBMS_XMLSCHEMA
package provides procedures to manage XML schemas.
It is created by script dbmsxsch.sql
during Oracle database installation.
This chapter contains the following topics:
See Also:
231.1 DBMS_XMLSCHEMA Overview
The DBMS_XMLSCHEMA
package uses subprograms to manage XML schemas.
These subprograms provide the following XML schema management::
-
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
231.2 DBMS_XMLSCHEMA Security Model
Owned by XDB
, the DBMS_XMLSCHEMA
package must be created by SYS
or XDB
. The EXECUTE
privilege is granted to PUBLIC
. Subprograms in this package are executed using the privileges of the current user.
231.3 DBMS_XMLSCHEMA Constants
The DBMS_XMLSCHEMA
package defines several constants to use when specifying parameter values.
These constants are shown in following tables.
Table 231-1 DBMS_XMLSCHEMA Constants - Delete Option
Constant | Type | Value | Description |
---|---|---|---|
|
|
|
Deletion of an XML schema fails if there are any tables or XML schemas that depend on it |
|
|
|
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. |
|
|
|
Deletion of an XML schema also drops all SQL types and default tables associated with it. SQL types are dropped only if |
|
|
|
This option is similar to |
Table 231-2 DBMS_XMLSCHEMA Constants - Enable Hierarchy
Constant | Type | Value | Description |
---|---|---|---|
|
|
|
The |
|
|
|
The |
|
|
|
The |
Table 231-3 DBMS_XMLSCHEMA Constants - Register CSID
Constant | Type | Value | Description |
---|---|---|---|
|
|
|
If a schema is registered for metadata use (using the value |
|
|
|
If user wishes to not specify the character set of the input schema document when invoking |
231.4 Views
This table lists the views used by the DBMS_XMLSCHEMA
package
The columns of these views are described in detail in the Oracle Database Reference
Table 231-4 Summary of Views used by DBMS_XMLSCHEMA
Schema | Description |
---|---|
All registered XML Schemas owned by the user |
|
All registered XML Schemas usable by the current user |
|
All registered XML Schemas in the database |
|
All |
|
All |
|
All |
|
All |
|
All |
|
All |
|
All |
|
All |
|
All |
|
All |
|
All |
|
All |
231.5 DBMS_XMLSCHEMA Operational Notes
There are guidelines for using in-place XML schema evolution.
Before you perform an in-place XML-schema evolution, you should follow these preparatory steps:
-
Back up all existing data (instance documents) for the XML schema that will be evolved.
-
Perform a dry run using trace only, that is, without actually evolving the XML schema or updating any instance documents, to produce a trace of the update operations that would be performed during evolution. To do this, set the flag parameter value to only
INPLACE_TRACE
. Do not also useINPLACE_EVOLVE
. After performing the dry run, examine the trace file, verifying that the listed DDL operations are in fact those that you intend.
231.6 Summary of DBMS_XMLSCHEMA Subprograms
This table lists the DBMS_XMLSCHEMA
subprograms and briefly describes them.
Table 231-5 DBMS_XMLSCHEMA Package Subprograms
Method | Description |
---|---|
Used to re-compile an already registered XML schema. This is useful for bringing a schema in an invalid state to a valid state. |
|
Evolves registered schemas so that existing XML instances remain valid |
|
Removes the schema from the database |
|
Evolves registered schemas by propagating schema changes to object types and tables |
|
Removes the XML schema |
|
Registers the specified schema for use by Oracle. This schema can then be used to store documents conforming to this. |
|
Registers an XML schema specified by a URI name |
231.6.1 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 231-6 COMPILESCHEMA Procedure Parameters
Parameter | Description |
---|---|
|
URL identifying the schema |
231.6.2 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 parallelDegree IN PLS_INTEGER := 0, options IN PLS_INTEGER := 0);
Parameters
Table 231-7 COPYEVOLVE Procedure Parameters
Parameter | Description |
---|---|
|
|
|
|
|
|
|
Default is |
|
Specifies the name of the table mapping permanent to temporary tables during the evolution process. Valid columns are:
|
|
Default is If
|
|
Default is If |
|
|
|
Specifies the degree of parallelism to be used in a |
|
Currently, the only supported option is |
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.
231.6.3 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 231-8 DELETESCHEMA Procedure Parameters
Parameter | Description |
---|---|
|
URL identifying the schema to be deleted |
|
Delete options:
|
Exceptions
Table 231-9 DELETESCHEMA Procedure Exceptions
Exception | Description |
---|---|
|
Invalid resource handle or path name |
231.6.4 INPLACEEVOLVE Procedure
This procedure evolves registered schemas by propagating schema changes to object types and tables.
Syntax
DBMS_XMLSCHEMA.INPLACEEVOLVE( schemaURL IN VARCHAR2, diffXML IN XMLType, flags IN NUMBER);
Parameters
Table 231-10 INPLACEEVOLVE Procedure Parameters
Parameter | Description |
---|---|
|
URL of the schema to evolve |
|
Changes to be applied to the schema. This is an XML document conforming to the |
|
The following bits may be set in this parameter to control the behavior of this procedure:
That is, each of the bits constructs the new XML schema, validates it, and determines the steps needed to evolve the disk structures underlying the instance documents. In addition:
|
Exceptions
The procedure raises exceptions in the following cases:
-
An error will be raised for invalid
XPATH
expressions and forXDIFF
documents that do not conform to the xdiff schema. -
Path expressions that are syntactically correct but result in an invalid node in the schema document will result in an error.
-
If the schema change makes the schema an ill-formed XML document or an invalid XML schema, this will raise an error.
-
Any errors resulting from
CREATE
TYPE
,ALTER
TYPE
and like commands will generate error messages.
Usage Notes
-
Users are required to backup all their data before attempting in-place evolution, as there is no rollback with this operation.
-
A user must register their new XML schema with the database using the REGISTERSCHEMA Procedures and the REGISTERURI Procedure at a schema URL that is different from that of the one to be evolved. If the new schema registers successfully and is usable, only then should the user attempt to evolve the existing schema to the new schema by means of this subprogram. If the registration of the new schema is successful, then the user must delete this schema (and all its dependent objects) before attempting to evolve the schema at the old schema URL.
231.6.5 PURGESCHEMA Procedure
This procedure removes the XML schema.
See Also:
"XMLSCHEMA Storage and Query: Advanced" chapter of the Oracle XML DB Developer's Guide
Syntax
DBMS_XMLSCHEMA.PURGESCHEMA( schemaid IN RAW);
Parameters
Table 231-11 PURGESCHEMA Procedure Parameters
Parameter | Description |
---|---|
|
ID of the schema to be purged |
Usage Notes
-
The schema should have been originally registered for binary encoding and should have been deleted in the
HIDE
mode. -
Once a schema has been deleted in
HIDE
mode, it continues to exist in the XML DB dictionary and is used for decoding already encoded documents. The user invokes this interface when there are no stored instances encoded with this schema. -
Once the schema is purged, any space used by that schema will be reclaimed and documents encoded using the schema will raise an error if an attempt is made to decode them.
-
The Schema ID can be obtained from the catalog views.
231.6.6 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.
Note:
As of Oracle Database 11g Release 2 (11.2) the genbean
parameter is deprecated. Oracle recommends that you do not use this parameter in new applications. Support for this feature is for backward compatibility only.
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 231-12 REGSITERSCHEMA Procedure Parameters
Parameter | Description |
---|---|
|
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 |
|
A valid XML schema document |
|
Is this a local or global schema?
You need write privileges on the directory to be able to register a schema as global. |
|
Determines whether the schema compiler generates object types. By default, |
|
Determines whether the schema compiler generates Java beans. By default, |
|
Determines whether the schema compiler generates default tables. By default, |
|
If this parameter is set to |
|
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. |
|
Identifies the character set of the input schema document. If this value is |
|
|
|
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
|
231.6.7 REGISTERURI Procedure
This procedure registers an XML Schema specified by a URI name.
Note:
As of Oracle Database 11g Release 2 (11.2) the genbean
parameter is deprecated. Oracle recommends that you do not use this parameter in new applications. Support for this feature is for backward compatibility only.
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 231-13 REGISTERURI Procedure Parameters
Parameter | Description |
---|---|
|
Uniquely identifies the schema document. Can be used inside |
|
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 |
|
Determines whether this is a local or global schema. By default, all schemas are registered as local schemas, under |
|
Determines whether the compiler generate object types. By default, |
|
Determines whether the compiler generate Java beans. By default, |
|
Determines whether the compiler generate default tables. |
|
|
|
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. |
|
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
|