File: XMLReplace.xml

package info (click to toggle)
virtuoso-opensource 7.2.5.1%2Bdfsg1-0.3
  • links: PTS, VCS
  • area: main
  • in suites: bookworm
  • size: 285,240 kB
  • sloc: ansic: 641,220; sql: 490,413; xml: 269,570; java: 83,893; javascript: 79,900; cpp: 36,927; sh: 31,653; cs: 25,702; php: 12,690; yacc: 10,227; lex: 7,601; makefile: 7,129; jsp: 4,523; awk: 1,697; perl: 1,013; ruby: 1,003; python: 326
file content (184 lines) | stat: -rw-r--r-- 10,726 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
<?xml version="1.0" encoding="ISO-8859-1" ?> <!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<refentry id="fn_XMLReplace">
<refmeta>
<refentrytitle>XMLReplace</refentrytitle>
<refmiscinfo>xml</refmiscinfo>
</refmeta>
<refnamediv>
<refname>XMLReplace</refname>
<refpurpose>Modify a given XML document by replacing some nodes.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_XMLReplace">
<funcprototype id="fproto_XMLReplace">
<funcdef>any <function>XMLReplace</function></funcdef>
<paramdef>inout <parameter>source</parameter> any</paramdef>
<paramdef>in <parameter>location1</parameter> any</paramdef>
<paramdef>in <parameter>replacement1</parameter> any</paramdef>
<paramdef>in <parameter>location2</parameter> any</paramdef>
<paramdef>in <parameter>replacement2</parameter> any</paramdef>
<paramdef>in <parameter>...</parameter></paramdef>
<paramdef>in <parameter>locationN</parameter> any</paramdef>
<paramdef>in <parameter>replacementN</parameter> any</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_XMLReplace">
<title>Description</title>
<para>The function takes of the XML document referenced by
<parameter>source</parameter> XML tree entity and modifies it by replacing nodes specified by
<parameter>location1</parameter>, <parameter>location2</parameter>, ..., <parameter>locationN</parameter> with
values specified by <parameter>replacement1</parameter>, <parameter>replacement2</parameter>, ...,<parameter>replacementN</parameter>.
At the end of function call, the <parameter>source</parameter> points to the root of a modified entity.
</para>
<para>The <parameter>source</parameter> parameter should be an XML tree entity whose document is not locked (see
<link linkend="xmldom">Changing XML Entities in DOM Style</link> for details).
</para>
<para>Every <parameter>replacementI</parameter> may be an XML tree entity, a NULL or a value of some other type that will be converted to varchar before use.
</para>
<para>For simplicity, consider the case when there is only one <parameter>location1</parameter> XML entity and only one
<parameter>replacement1</parameter>. If the <parameter>location1</parameter> is an XML entity that is not in the source document
then no modifications is made in <parameter>source</parameter>. If <parameter>replacement1</parameter> is an entity that 
is in the source document then a temporary &quot;cut&quot; of <parameter>replacement1</parameter> is created, like
<link linkend="xpf_xml_cut"><function>xml_cut</function></link> is called).
</para>
<para>
If the <parameter>location1</parameter> is an attribute entity then the value of the attribute is changed.
If <parameter>replacement1</parameter> is NULL then the attribute is removed at all, otherwise its value is set to the string value of
the <parameter>replacement1</parameter>.
</para>
<para>
If the <parameter>location1</parameter> is not an attribute entity but a entity then <parameter>location1</parameter> is replaced with the value of <parameter>replacement1</parameter>.
The method of  replacement depends on the type of the replacement value.
If <parameter>replacement1</parameter> is NULL then the <parameter>location1</parameter> node is simply removed from the result; if the node is the root or a
single child of the root then function immediately returns NULL (because XML document can not be totally empty),
otherwise the parent of the <parameter>location1</parameter> will simply have one child less.
If <parameter>replacement1</parameter> is an non-empty string then <parameter>location1</parameter> is
replaced with a new text node whose string value is equal to <parameter>replacement1</parameter>.
If <parameter>replacement1</parameter> is an empty string then the effect is exactly the same as in case of NULL because the string value of a text node can not be empty.
If <parameter>replacement1</parameter> is an XML entity that is a root entity of some document then the highlighted node is replaced with a sequence of copies of all children of that root.
If <parameter>replacement1</parameter> is an XML entity of some other sort (XML element, text, comment etc.) then the that is not a root entity of some document then the highlighted node is replaced with a sequence of copies of all children of that root.
</para>
<para>
After changing the <parameter>source</parameter>, some normalization may happen. The modified document may contain adjacent text nodes; every sequence of such nodes
is replaced with one text node whose string value is a concatenation of string values of that nodes. E.g. if the <parameter>location1</parameter> is an element &lt;a/&gt;
that resides between two text nodes &quot;text1&quot; and &quot;text2&quot; and it is removed (by replacing with NULL) then these text nodes become neighbors;
normalization will replace them with a single text node &quot;text1text2&quot;
</para>
<para>
Now consider the case of more than one replacement made in one function call. If more than one pair of location and replacement is given then
the function first finds all locations, then it performs all replacements, then it performs an normalization.
It is very important to understand that the order of making replacements has nothing to do with the order of pairs of parameters in the function call.
If some location node is an ancestor of some other location node then the effect of the replacement of the descendant location node is void:
the descendant is replaced first; then the ancestor is replaced as a whole, no matter if some of its descendants are modified.
The order of parameters in the function call
is used to resolve ambiguity If two locations are equal: the last pair of parameters will have a higher priority.
</para>
<para>
If the <parameter>source</parameter> is an instance of XMLType then its inner XML document is changed and &quot;is validated&quot; flag is reset to
0 indicating that there is no warranty that the modified version of document matches the declared schema even if the original document matched.
</para>
</refsect1>
<refsect1 id="params_XMLReplace">
<title>Parameters</title>
<refsect2>
<title>source</title>
<para>A source XML tree entity. It is an error to pass persistent XML entity as an argument.</para>
</refsect2>
<refsect2>
<title>locationI</title>
<para>An XML entity that points to the node to replace. For compatibility with other implementations, it can be NULL, a pair of arguments is silently ignored in this case.</para>
</refsect2>
<refsect2>
<title>replacementI</title>
<para>A replacement value for XML node pointed by <parameter>locationI</parameter>; it may be NULL or XML tree entity or a string or anything else but not an persistent XML entity.</para>
</refsect2>
</refsect1>
<refsect1 id="ret_XMLReplace">
<title>Return Types</title>
<para>The function returns NULL.</para>
</refsect1>
<refsect1 id="examples_XMLReplace">
<title>Examples</title>
<example id="ex_XMLReplace_1">
<title>XMLReplace in a Virtuoso/PL procedure</title>
<para>The sample procedure contains two calls of <function>XMLReplace</function>.
First call replaces element 'c' with a copy of element 'replacement'.
Second call demonstrates two replacements in parallel: elements titled 'c1' and 'c3' are replaced with text nodes.
</para>
<screen>
<![CDATA[
create procedure XMLReplace_demo ()
{
  declare DESCRIPTION varchar(42);
  declare XMLENTITY, ent, ent2, ent_to_corrupt any;
  result_names (DESCRIPTION, XMLENTITY);
  ent := xtree_doc('<a><b><q/>-<c>Hello</c>-</b></a>');
  result ('EXAMPLE 1', 'A simple replacement of one element with other');
  result ('The document to modify:', ent);
  ent_to_corrupt := xquery_eval ('//c', ent);
  result ('Node to be replaced:', ent_to_corrupt);
  XMLReplace (ent, ent_to_corrupt, xtree_doc('<replacement/>'));
  result ('The document after modification:', ent);
  result ('Node to be replaced is outdated:', ent_to_corrupt);
  result ('...e.g. it'' not a descendant of its root:', xpath_eval('/', ent_to_corrupt));
  result ('EXAMPLE 2', 'Two replacements in parallel');
  ent2 := xtree_doc('<a><b><c1>Hello1</c1><c2>Hello2</c2><c3>Hello3</c3></b></a>');
  result ('The document to modify:', ent2);
  XMLReplace (ent2, xquery_eval('//c1', ent2), 'world1', xquery_eval('//c3', ent2), 'world3');
  result ('The document after modification:', ent2);
}


Done. -- 00000 msec.

XMLReplace_demo()
DESCRIPTION                                XMLENTITY
VARCHAR                                    VARCHAR
_______________________________________________________________________________

EXAMPLE 1                                  A simple replacement of one element with other
The document to modify:                    <a><b><q />-<c>Hello</c>-</b></a>
Node to be replaced:                       <c>Hello</c>
The document after modification:           <a><b><q />-<replacement />-</b></a>
Node to be replaced is outdated:           <c>Hello</c>
...e.g. it' not a descendant of its root:  <a><b><q />-<replacement />-</b></a>
EXAMPLE 2                                  Two replacements in parallel
The document to modify:                    <a><b><c1>Hello1</c1><c2>Hello2</c2><c3>Hello3</c3></b></a>
The document after modification:           <a><b>world1<c2>Hello2</c2>world3</b></a>

9 Rows. -- 00000 msec.]]>
</screen>
</example>
</refsect1>
<refsect1 id="seealso_XMLReplace">
<title>See Also</title>
<para><link linkend="fn_XMLUpdate"><function>XMLUpdate</function></link></para>
<para><link linkend="fn_XMLAddAttribute"><function>XMLAddAttribute</function></link></para>
<para><link linkend="fn_XMLAppendChildren"><function>XMLAppendChildren</function></link></para>
<para><link linkend="fn_XMLInsertBefore"><function>XMLInsertBefore</function></link></para>
<para><link linkend="fn_XMLInsertAfter"><function>XMLInsertAfter</function></link></para>
<para><link linkend="fn_xslt"><function>xslt</function></link></para>
</refsect1>
</refentry>