This chapter describes how you can update your XML schema after you have registered it with Oracle XML DB. XML schema evolution is the process of updating your registered XML schema.
This chapter contains these topics:
Oracle XML DB supports the W3C XML Schema recommendation. XML instance documents that conform to an XML schema can be stored and retrieved using SQL and protocols such as FTP, HTTP(S), and WebDAV. In addition to specifying the structure of XML documents, XML schemas determine the mapping between XML and object-relational storage.
Oracle XML DB supports XML schema evolution by providing PL/SQL procedure copyEvolve
as part of PL/SQL package DBMS_XMLSCHEMA
. Procedure copyEvolve
copies existing instance documents to temporary XMLType
tables to back them up, drops the old version of the XML schema (which also deletes the associated instance documents), registers the new version, and copies the backed-up instance documents to new XMLType
tables.
With procedure copyEvolve
you can evolve your registered XML schema in such a way that existing XML instance documents continue to be valid. If you do not care about the existing documents, you can simply drop the XMLType
tables that are dependent on the XML schema, delete the old XML schema, and register the new XML schema at the same URL.
The following are the limitations of procedure DBMS_XMLSCHEMA.copyEvolve
:
Indexes, triggers, constraints, RLS policies and other metadata related to the XMLType
tables that are dependent on the schemas that are evolved, will not be preserved. These must be re-created after evolution.
If top-level element names are being changed, there are more steps to be followed after procedure copyEvolve
completes executing. See the section on "Top-Level Element Name Changes" for more details.
Data copy-based evolution cannot be used if there is a table with an object-type column that has an XMLType
attribute that is dependent on any of the schemas to be evolved. For example, consider a table TAB1 that is created in the following way:
CREATE TYPE t1 AS OBJECT (n NUMBER, x XMLType); CREATE TABLE tab1 (e NUMBER, o t1) XMLType COLUMN o.x XMLSchema "s1.xsd" ELEMENT "Employee";
The example assumes that an XML schema with a top-level element Employee
has been registered under URL s1.xsd
. It is not possible to evolve this XML schema since table TAB1
with column O
with XMLType
attribute X
is dependent on this XML schema.
Here are some guidelines for using procedure DBMS_XMLSCHEMA.copyEvolve
:
First, identify the XML schemas that are dependent on the XML schema that is to be evolved. You can acquire the URLs of the dependent XML schemas using the following query, where schema_to_be_evolved
is the schema to be evolved, and owner_of_schema_to_be_evolved
is its owner (database user).
SELECT dxs.SCHEMA_URL FROM DBA_DEPENDENCIES dd, DBA_XML_SCHEMAS dxs WHERE dd.REFERENCED_NAME = (SELECT INT_OBJNAME FROM DBA_XML_SCHEMAS WHERE SCHEMA_URL = schema_to_be_evolved AND OWNER = schema_to_be_evolved) AND dxs.OWNER = owner_of_schema_to_be_evolved AND dxs.INT_OBJNAME = dd.NAME;
In many cases, no changes may be necessary in the dependent XML schemas. But if the dependent XML schemas need to be changed, you must also prepare new versions of those XML schemas.
If the existing instance documents do not conform to the new XML schema, you must provide an XSL style sheet that, when applied to an instance document, will transform it to conform to the new schema. This needs to be done for each XML schema identified in Step 1. The transformation must handle documents that conform to all top-level elements in the new XML schema.
Call procedure DBMS_XMLSCHEMA.copyEvolve
, specifying the XML schema URLs, new schemas, and transformations.
Procedure DBMS_XMLSCHEMA.copyEvolve
assumes that top-level elements have not been dropped and that their names have not been changed in the new XML schemas. If there are such changes in your new XML schemas, you can call procedure copyEvolve
with the generateTables
parameter set to FALSE and the preserveOldDocs
parameter set to TRUE. In this way new tables are generated and the temporary tables holding the old documents are not dropped at the end of the procedure. You can then store the old documents in whatever form is appropriate and drop the temporary tables. See "Procedure DBMS_XMLSCHEMA.COPYEVOLVE: Parameters and Errors" for more details on the using these parameters.
Ensure that the XML schema and its dependents are not used by any concurrent session during the XML schema evolution process. If other concurrent sessions have shared locks on this schema at the beginning of the evolution process, then procedure DBMS_XMLSCHEMA.copyEvolve
waits for these sessions to release the locks so that it can acquire an exclusive lock. However this lock is released immediately to allow the rest of the process to continue.
Procedure DBMS_XMLSCHEMA.copyEvolve()
either completely succeeds or raises an error, in which case it attempts to rollback as much of the operation as possible. Evolving a schema involves many database DDL statements. When an error occurs, compensating DDL statements are executed to undo the effect of all steps executed to that point. If the old tables/schemas have been dropped they are re-created but any table/column/storage properties and auxiliary structures associated with the tables/columns like indexes, triggers, constraints, and RLS policies are lost.
In certain cases you cannot rollback the operation. For example, if table creation fails due to reasons not related to the new schema, such as, from insufficient privileges, there is no way to rollback. The temporary tables are not deleted even if preserveOldDocs
is false, so that the data can be recovered. If the mapTabName
parameter is null, the mapping table name is XDB$MAPTAB
followed by a sequence number. The exact table name can be found using a query such as:
SELECT TABLE_NAME FROM USER_TABLES WHERE TABLE_NAME LIKE 'XDB$MAPTAB%';
Schema evolution may involve dropping/creating types. Hence you need type-related privileges such as DROP TYPE
, CREATE TYPE
, and ALTER TYPE
.
You need privileges to delete and register the XML schemas involved in the evolution. You need all privileges on XMLType
tables that conform to the schemas being evolved. For XMLType
columns, the ALTER TABLE
privilege is needed on corresponding tables. If there are schema-based XMLType
tables or columns in other database schemas, you need privileges such as the following:
CREATE ANY TABLE
CREATE ANY INDEX
SELECT ANY TABLE
UPDATE ANY TABLE
INSERT ANY TABLE
DELETE ANY TABLE
DROP ANY TABLE
ALTER ANY TABLE
DROP ANY INDEX
To avoid having to grant all these privileges to the schema owner, Oracle recommends that the evolution be performed by a DBA if there are XML schema-based XMLType
table or columns in other users' database schemas.
Example 8-1 shows a partial listing of a revised version of the purchase-order XML schema of Example 3-8. See Example D-2 for the complete revised schema listing. Text that is in bold face here is new or significantly different from that in the original schema (Example 3-8).
Example 8-1 Revised Purchase-Order XML Schema
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xdb="http://xmlns.oracle.com/xdb" version="1.0"> <xs:element name="PurchaseOrder" type="PurchaseOrderType" xdb:defaultTable="PURCHASEORDER" xdb:columnProps= "CONSTRAINT purchaseorder_pkey PRIMARY KEY (XMLDATA.reference), CONSTRAINT valid_email_address FOREIGN KEY (XMLDATA.userid) REFERENCES hr.employees (EMAIL)" xdb:tableProps= "VARRAY XMLDATA.ACTIONS.ACTION STORE AS TABLE ACTION_TABLE ((CONSTRAINT action_pkey PRIMARY KEY (NESTED_TABLE_ID, SYS_NC_ARRAY_INDEX$))) VARRAY XMLDATA.LINEITEMS.LINEITEM STORE AS TABLE LINEITEM_TABLE ((constraint LINEITEM_PKEY primary key (NESTED_TABLE_ID, SYS_NC_ARRAY_INDEX$))) lob (XMLDATA.NOTES) STORE AS (ENABLE STORAGE IN ROW STORAGE(INITIAL 4K NEXT 32K))"/> <xs:complexType name="PurchaseOrderType" xdb:SQLType="PURCHASEORDER_T"> <xs:sequence> <xs:element name="Actions" type="ActionsType" xdb:SQLName="ACTIONS"/> <xs:element name="Reject" type="RejectionType" minOccurs="0" xdb:SQLName="REJECTION"/> <xs:element name="Requestor" type="RequestorType" xdb:SQLName="REQUESTOR"/> <xs:element name="User" type="UserType" xdb:SQLName="USERID"/> <xs:element name="CostCenter" type="CostCenterType" xdb:SQLName="COST_CENTER"/> <xs:element name="BillingAddress" type="AddressType" minOccurs="0" xdb:SQLName="BILLING_ADDRESS"/> <xs:element name="ShippingInstructions" type="ShippingInstructionsType" xdb:SQLName="SHIPPING_INSTRUCTIONS"/> <xs:element name="SpecialInstructions" type="SpecialInstructionsType" xdb:SQLName="SPECIAL_INSTRUCTIONS"/> <xs:element name="LineItems" type="LineItemsType" xdb:SQLName="LINEITEMS"/> <xs:element name="Notes" type="NotesType" minOccurs="0" xdb:SQLType="CLOB" xdb:SQLName="NOTES"/> </xs:sequence> <xs:attribute name="Reference" type="ReferenceType" use="required" xdb:SQLName="REFERENCE"/> <xs:attribute name="DateCreated" type="xs:dateTime" use="required" xdb:SQLType="TIMESTAMP WITH TIME ZONE"/> </xs:complexType> <xs:complexType name="LineItemsType" xdb:SQLType="LINEITEMS_T"> <xs:sequence> <xs:element name="LineItem" type="LineItemType" maxOccurs="unbounded" xdb:SQLName="LINEITEM" xdb:SQLCollType="LINEITEM_V"/> </xs:sequence> </xs:complexType> <xs:complexType name="LineItemType" xdb:SQLType="LINEITEM_T"> <xs:sequence> <xs:element name="Part" type="PartType" xdb:SQLName="PART"/> <xs:element name="Quantity" type="quantityType"/> </xs:sequence> <xs:attribute name="ItemNumber" type="xs:integer" xdb:SQLName="ITEMNUMBER" xdb:SQLType="NUMBER"/> </xs:complexType> <xs:complexType name="PartType" xdb:SQLType="PART_T"> <xs:simpleContent> <xs:extension base="UPCCodeType"> <xs:attribute name="Description" type="DescriptionType" use="required" xdb:SQLName="DESCRIPTION"/> <xs:attribute name="UnitCost" type="moneyType" use="required"/> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:simpleType name="ReferenceType"> <xs:restriction base="xs:string"> <xs:minLength value="18"/> <xs:maxLength value="30"/> </xs:restriction> </xs:simpleType> . . . <xs:complexType name="RejectionType" xdb:SQLType="REJECTION_T"> <xs:all> <xs:element name="User" type="UserType" minOccurs="0" xdb:SQLName="REJECTED_BY"/> <xs:element name="Date" type="DateType" minOccurs="0" xdb:SQLName="DATE_REJECTED"/> <xs:element name="Comments" type="CommentsType" minOccurs="0" xdb:SQLName="REASON_REJECTED"/> </xs:all> </xs:complexType> <xs:complexType name="ShippingInstructionsType" xdb:SQLType="SHIPPING_INSTRUCTIONS_T"> <xs:sequence> <xs:element name="name" type="NameType" minOccurs="0" xdb:SQLName="SHIP_TO_NAME"/> <xs:choice> <xs:element name="address" type="AddressType" minOccurs="0"/> <xs:element name="fullAddress" type="FullAddressType" minOccurs="0" xdb:SQLName="SHIP_TO_ADDRESS"/> </xs:choice> <xs:element name="telephone" type="TelephoneType" minOccurs="0" xdb:SQLName="SHIP_TO_PHONE"/> </xs:sequence> </xs:complexType> . . . <xs:simpleType name="NameType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="20"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="FullAddressType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="256"/> </xs:restriction> </xs:simpleType> . . . <xs:simpleType name="DescriptionType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="256"/> </xs:restriction> </xs:simpleType> <xs:complexType name="AddressType" xdb:SQLType="ADDRESS_T"> <xs:sequence> <xs:element name="StreetLine1" type="StreetType"/> <xs:element name="StreetLine2" type="StreetType" minOccurs="0"/> <xs:element name="City" type="CityType"/> <xs:choice> <xs:sequence> <xs:element name="State" type="StateType"/> <xs:element name="ZipCode" type="ZipCodeType"/> </xs:sequence> <xs:sequence> <xs:element name="Province" type="ProvinceType"/> <xs:element name="PostCode" type="PostCodeType"/> </xs:sequence> <xs:sequence> <xs:element name="County" type="CountyType"/> <xs:element name="Postcode" type="PostCodeType"/> </xs:sequence> </xs:choice> <xs:element name="Country" type="CountryType"/> </xs:sequence> </xs:complexType> <xs:simpleType name="StreetType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="128"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="CityType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="64"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="StateType"> <xs:restriction base="xs:string"> <xs:minLength value="2"/> <xs:maxLength value="2"/> <xs:enumeration value="AK"/> <xs:enumeration value="AL"/> <xs:enumeration value="AR"/> . . . -- A value for each US state abbreviation <xs:enumeration value="WY"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="ZipCodeType"> <xs:restriction base="xs:string"> <xs:pattern value="\d{5}"/> <xs:pattern value="\d{5}-\d{4}"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="CountryType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="64"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="CountyType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="32"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="PostCodeType"> <xs:restriction base="xs:string"> <xs:minLength value="1"/> <xs:maxLength value="12"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="ProvinceType"> <xs:restriction base="xs:string"> <xs:minLength value="2"/> <xs:maxLength value="2"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="NotesType"> <xs:restriction base="xs:string"> <xs:maxLength value="32767"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="UPCCodeType"> <xs:restriction base="xs:string"> <xs:minLength value="11"/> <xs:maxLength value="14"/> <xs:pattern value="\d{11}"/> <xs:pattern value="\d{12}"/> <xs:pattern value="\d{13}"/> <xs:pattern value="\d{14}"/> </xs:restriction> </xs:simpleType> </xs:schema>
Note:
As always:SQL is case-insensitive, but names in SQL code are implicitly uppercase, unless you enclose them in double-quotes.
XML is case-sensitive. You must refer to SQL names in XML code using the correct case: uppercase SQL names must be written as uppercase.
For example, if you create a table named my_table
in SQL without using double-quotes, then you must refer to it in XML as "MY_TABLE
".
After you modify a registered XML schema, you must also update any existing XML instance documents that used the old version of the schema. You do this by applying an XSLT style sheet to each of the instance documents. The style sheet represents the difference between the old and new schemas.
Example 8-2 is a style sheet, in file evolvePurchaseOrder.xsl
, that transforms existing purchase-order documents that use the old schema, so they will use the new schema instead.
Example 8-2 evolvePurchaseOrder.xsl: Style Sheet to Update Instance Documents
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <xsl:output method="xml" encoding="UTF-8"/> <xsl:template match="/PurchaseOrder"> <PurchaseOrder> <xsl:attribute name="xsi:noNamespaceSchemaLocation"> http://localhost:8080/source/schemas/poSource/xsd/purchaseOrder.xsd </xsl:attribute> <xsl:for-each select="Reference"> <xsl:attribute name="Reference"> <xsl:value-of select="."/> </xsl:attribute> </xsl:for-each> <xsl:variable name="V264_394" select="'2004-01-01T12:00:00.000000-08:00'"/> <xsl:attribute name="DateCreated"> <xsl:value-of select="$V264_394"/> </xsl:attribute> <xsl:for-each select="Actions"> <Actions> <xsl:for-each select="Action"> <Action> <xsl:for-each select="User"> <User> <xsl:value-of select="."/> </User> </xsl:for-each> <xsl:for-each select="Date"> <Date> <xsl:value-of select="."/> </Date> </xsl:for-each> </Action> </xsl:for-each> </Actions> </xsl:for-each> <xsl:for-each select="Reject"> <Reject> <xsl:for-each select="User"> <User> <xsl:value-of select="."/> </User> </xsl:for-each> <xsl:for-each select="Date"> <Date> <xsl:value-of select="."/> </Date> </xsl:for-each> <xsl:for-each select="Comments"> <Comments> <xsl:value-of select="."/> </Comments> </xsl:for-each> </Reject> </xsl:for-each> <xsl:for-each select="Requestor"> <Requestor> <xsl:value-of select="."/> </Requestor> </xsl:for-each> <xsl:for-each select="User"> <User> <xsl:value-of select="."/> </User> </xsl:for-each> <xsl:for-each select="CostCenter"> <CostCenter> <xsl:value-of select="."/> </CostCenter> </xsl:for-each> <ShippingInstructions> <xsl:for-each select="ShippingInstructions"> <xsl:for-each select="name"> <name> <xsl:value-of select="."/> </name> </xsl:for-each> </xsl:for-each> <xsl:for-each select="ShippingInstructions"> <xsl:for-each select="address"> <fullAddress> <xsl:value-of select="."/> </fullAddress> </xsl:for-each> </xsl:for-each> <xsl:for-each select="ShippingInstructions"> <xsl:for-each select="telephone"> <telephone> <xsl:value-of select="."/> </telephone> </xsl:for-each> </xsl:for-each> </ShippingInstructions> <xsl:for-each select="SpecialInstructions"> <SpecialInstructions> <xsl:value-of select="."/> </SpecialInstructions> </xsl:for-each> <xsl:for-each select="LineItems"> <LineItems> <xsl:for-each select="LineItem"> <xsl:variable name="V22" select="."/> <LineItem> <xsl:for-each select="@ItemNumber"> <xsl:attribute name="ItemNumber"> <xsl:value-of select="."/> </xsl:attribute> </xsl:for-each> <xsl:for-each select="$V22/Part"> <xsl:variable name="V24" select="."/> <xsl:for-each select="@Id"> <Part> <xsl:for-each select="$V22/Description"> <xsl:attribute name="Description"> <xsl:value-of select="."/> </xsl:attribute> </xsl:for-each> <xsl:for-each select="$V24/@UnitPrice"> <xsl:attribute name="UnitCost"> <xsl:value-of select="."/> </xsl:attribute> </xsl:for-each> <xsl:value-of select="."/> </Part> </xsl:for-each> </xsl:for-each> <xsl:for-each select="$V22/Part"> <xsl:for-each select="@Quantity"> <Quantity> <xsl:value-of select="."/> </Quantity> </xsl:for-each> </xsl:for-each> </LineItem> </xsl:for-each> </LineItems> </xsl:for-each> </PurchaseOrder> </xsl:template> </xsl:stylesheet>
Here is the signature of procedure DBMS_XMLSCHEMA.copyEvolve
:
procedure copyEvolve(schemaURLs IN XDB$STRING_LIST_T, newSchemas IN XMLSequenceType, transforms IN XMLSequenceType := NULL, preserveOldDocs IN BOOLEAN := FALSE, mapTabName IN VARCHAR2 := NULL, generateTables IN BOOLEAN := TRUE, force IN BOOLEAN := FALSE, schemaOwners IN XDB$STRING_LIST_T := NULL);
Table 8-1 describes the individual parameters. Table 8-2 describes the errors associated with the procedure.
Table 8-1 Parameters of Procedure DBMS_XMLSCHEMA.COPYEVOLVE
Parameter | Description |
---|---|
|
Varray of URLs of XML schemas to be evolved (varray of |
|
Varray of new XML schema documents ( |
|
Varray of XSL documents ( |
|
If this is TRUE the temporary tables holding old data are not dropped at the end of schema evolution. See also "Using Procedure DBMS_XMLSCHEMA.COPYEVOLVE". |
|
Specifies the name of table that maps old |
|
By default this parameter is TRUE; if this is FALSE, |
|
If this is TRUE errors during the registration of new schemas are ignored. If there are circular dependencies among the schemas, set this flag to TRUE to ensure that each schema is stored even though there may be errors in registration. |
|
Varray of names of schema owners. Specify these in exactly the same order as the corresponding URLs. |
Table 8-2 Errors Associated with Procedure DBMS_XMLSCHEMA.COPYEVOLVE
Error Number and Message | Cause | Action |
---|---|---|
30942 XML Schema Evolution error for schema '<schema_url>' table "<owner_name>.<table_name>" column '<column_name>' |
The given |
Based on the schema, table, and column information in this error and the more specific error that follows, take corrective action. |
30943 XML Schema '<schema_url>' is dependent on XML schema '<schema_url>' |
Not all dependent XML schemas were specified or the schemas were not specified in dependency order, that is, if schema S1 is dependent on schema S, S must appear before S1. |
Include the previously unspecified schema in the list of schemas or correct the order in which the schemas are specified. Then retry the operation. |
30944 Error during rollback for XML schema '<schema_url>' table "<owner_name>.<table_name>" column '<column_name>' |
The given |
Based on the schema, table, and column information in this error and the more specific error that follows, take corrective action. |
30945 Could not create mapping table '<table_name>' |
A mapping table could not be created during XML schema evolution. See also the more specific error that follows this. |
Ensure that a table with the given name does not exist and retry the operation. |
30946 XML Schema Evolution warning: temporary tables not cleaned up |
An error occurred after the schema was evolved while cleaning up temporary tables. The schema evolution was successful. |
If you need to remove the temporary tables, use the mapping table to get the temporary table names and drop them. |
Example 8-3 Loading Revised XML Schema and XSL Style Sheet
This example loads the revised XML schema and the evolution XSL style sheet into the Oracle XML DB repository.
DECLARE res BOOLEAN; BEGIN res := DBMS_XDB.createResource( -- Load revised XML schema '/source/schemas/poSource/revisedPurchaseOrder.xsd', bfilename('XMLDIR', 'revisedPurchaseOrder.xsd'), nls_charset_id('AL32UTF8')); res := DBMS_XDB.createResource( -- Load revised XSL style sheet '/source/schemas/poSource/evolvePurchaseOrder.xsl', bfilename('XMLDIR', 'evolvePurchaseOrder.xsl'), nls_charset_id('AL32UTF8')); END;/
Example 8-4 shows how to use procedure DBMS_XMLSCHEMA.copyEvolve
to evolve the purchase-order XML schema.
Example 8-4 Using DBMS_XMLSCHEMA.COPYEVOLVE to Update an XML Schema
This example evolves XML schema purchaseOrder.xsd
to revisedPurchaseOrder.xsd
using XSL style sheet evolvePurchaseOrder.xsl
.
BEGIN DBMS_XMLSCHEMA.copyEvolve( xdb$string_list_t('http://localhost:8080/source/schemas/poSource/xsd/purchaseOrder.xsd'), XMLSequenceType(XDBURIType('/source/schemas/poSource/revisedPurchaseOrder.xsd').getXML()), XMLSequenceType(XDBURIType('/source/schemas/poSource/evolvePurchaseOrder.xsl').getXML())); END;
SELECT extract(object_value, '/PurchaseOrder/LineItems/LineItem[1]') LINE_ITEM FROM purchaseorder WHERE existsNode(object_value, '/PurchaseOrder[@Reference="SBELL-2003030912333601PDT"]') = 1 / LINE_ITEM ------------------------------------------------------------------------------ <LineItem ItemNumber="1"> <Part Description="A Night to Remember" UnitCost="39.95">715515009058</Part> <Quantity>2</Quantity> </LineItem>
The same query would have produced the following result before the schema evolution:
LINE_ITEM ---------------------------------------------------------- <LineItem ItemNumber="1"> <Description>A Night to Remember</Description> <Part Id="715515009058" UnitPrice="39.95" Quantity="2"/> </LineItem>
Procedure DBMS_XMLSCHEMA.copyEvolve
is used to evolve registered XML schemas in such a way that existing XML instances continue to remain valid.
Caution:
Before executing procedureDBMS_XMLSCHEMA.copyEvolve
, always back up all registered XML schemas and all XML documents that conform to XML schemas. Procedure copyEvolve
deletes all documents that conform to registered XML schemas.First, procedure copyEvolve
copies the data in schema-based XMLType
tables and columns to temporary tables. It then drops the tables and columns and deletes the old XML schemas. After registering the new XML schemas, it creates XMLType
tables and columns and populates them with data (unless the genTables
parameter is false
) but it does not create any auxiliary structures such as indexes, constraints, triggers, and row-level security (RLS) policies. Procedure copyEvolve
creates the tables and columns as follows:
It creates default tables while registering the new schemas.
It creates nondefault tables by a statement of the following form:
CREATE TABLE <TABLE_NAME> OF XMLType OID '<OID>' XMLSCHEMA <SCHEMA_URL> ELEMENT <ELEMENT_NAME>
where <OID>
is the original OID of the table, before it was dropped.
It adds XMLType
columns using a statement of the following form:
ALTER TABLE <Table_Name> ADD (<Column_Name> XMLType) XMLType column <Column_Name> xmlschema <Schema_Url> ELEMENT <Element_Name>
When a new schema is registered, types or beans are generated if the registration of the corresponding old schema had generated types or beans. If an XML schema was global before the evolution it will be global after the evolution. Similarly if an XML schema was local before the evolution it will be local (owned by the same user) after the evolution.You have the option to preserve the temporary tables that contain the old documents by passing true
for the preserveOldDocs
parameter. In this case, procedure copyEvolve
does not drop the temporary tables at the end. All temporary tables are created in the database schema of the current user. For XMLType
tables the temp table will have the following columns:
Table 8-3 XML Schema Evolution: XMLType Table Temporary Table Columns
Name | Type | Comment |
---|---|---|
|
|
XML doc from old table in |
|
|
|
|
|
This column is present only if old table is hierarchy enabled. |
|
|
This column is present only if old table is hierarchy enabled. |
For XMLType
columns the temp table will have the following columns:
Table 8-4 XML Schema Evolution: XMLType Column Temporary Table Columns
Name | Type | Comment |
---|---|---|
|
|
XML document from old column in |
|
|
|
Procedure copyEvolve
stores information about the mapping from the old table or column name to the corresponding temporary table name in a separate table specified by the mapTabName
parameter. If preserveOldDocs
is true
, the mapTabName
parameter must not be NULL
, and it must not be the name of any existing table in the current database schema. Each row in the mapping table has information about one of the old tables/columns. Table 8-5 shows the mapping table columns.
Table 8-5 Procedure copyEvolve Mapping Table
Column Name | Column Type | Comment |
---|---|---|
|
|
URL of schema to which this table/column conforms. |
|
|
Owner of the schema. |
|
|
Element to which this table/column conforms. |
|
|
Qualified Name of table (<owner_name>.<table_name>). |
|
|
|
|
|
Name of column (this will be null for |
|
|
Name of temporary table which holds the data for this table/column. |
You can also avoid generating any tables or columns after registering the new XML schema, by using false
as the genTables
parameter. If genTables
is false
, the preserveOldDocs
parameter must be true
and the mapTabName
parameter must not be NULL
. This ensures that the data in the old tables is not lost. This is useful if you do not want the tables to be created by the procedure, as described in section "Procedure DBMS_XMLSCHEMA.COPYEVOLVE: Parameters and Errors".
By default it is assumed that all XML schemas are owned by the current user. If this is not true, you must specify the owner of each XML schema in the schemaOwners
parameter.