source: other-projects/trunk/realistic-books/packages/AntInstaller/web/manual1.7.0/manual/CoreTasks/xmlproperty.html@ 19253

Last change on this file since 19253 was 19253, checked in by davidb, 15 years ago

Establishing a source code repository for Veronica's Realistic Book's software
File size: 9.4 KB
Line 
1<!--
2 Licensed to the Apache Software Foundation (ASF) under one or more
3 contributor license agreements. See the NOTICE file distributed with
4 this work for additional information regarding copyright ownership.
5 The ASF licenses this file to You under the Apache License, Version 2.0
6 (the "License"); you may not use this file except in compliance with
7 the License. You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17<html>
18<head>
19<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
20<title>XmlProperty Task</title>
21</head>
22
23<body>
24
25<h2><a name="xmlproperty">XmlProperty</a></h2>
26<h3>Description</h3>
27<p>
28Loads property values from a well-formed xml file. There are no other restrictions
29than "well-formed". You can choose the layout you want. For example this XML property file:
30<pre>
31 &lt;root&gt;
32 &lt;properties&gt;
33 &lt;foo&gt;bar&lt;/foo&gt;
34 &lt;/properties&gt;
35 &lt;/root&gt;
36</pre>
37is roughly equivalent to this Java property file:
38<pre>
39 root.properties.foo = bar
40</pre>
41
42<p>
43By default, this load
44does <em>no</em> processing of the input. In particular, unlike the
45<a href="property.html">Property task</a>, property references
46(i.e., <samp>${foo}</samp>) are not resolved.
47<p>
48
49<h3><a name="semanticAttributes">Semantic Attributes</a></h3>
50
51Input processing can be enabled by using the <b>semanticAttributes</b>
52attribute. If this attribute is set to <i>true</i> (its default is
53<i>false</i>), the following processing occurs as the input XML file
54is loaded:
55<ul>
56 <li>Property references are resolved.</li>
57 <li>The following attriubtes are treated differently:
58 <ul>
59 <li><b>id</b>: The property is associated with the given id value.</li>
60 <li><b>location</b>: The property is treated as a file location</li>
61 <li><b>refid</b>: The property is set to the value of the
62 referenced property.</li>
63 <li><b>value</b>: The property is set to the value indicated.</li>
64 </ul>
65 </li>
66 <li><a href="../using.html#path">Path-like Structures</a> can be defined
67 by use of the following attributes:
68 <ul>
69 <li><b>pathid</b>: The given id is used to identify a path. The
70 nested XML tag name is ignored. Child elements can be used
71 (XML tag names are ignored) to identify elements of the path.</li>
72 </ul>
73 </li>
74</ul>
75<p>
76For example, with semantic attribute processing enabled, this XML property
77file:
78<pre>
79 &lt;root&gt;
80 &lt;properties&gt;
81 &lt;foo location="bar"/&gt;
82 &lt;quux&gt;${root.properties.foo}&lt;/quux&gt;
83 &lt;/properties&gt;
84 &lt;/root&gt;
85</pre>
86is roughly equivalent to the following fragments in a build.xml file:
87<pre>
88 &lt;property name="root.properties.foo" location="bar"/&gt;
89 &lt;property name="root.properties.quux" value="${root.properties.foo}"/&gt;
90</pre>
91
92</p>
93
94<h3>Parameters</h3>
95<table border="1" cellpadding="2" cellspacing="0">
96 <tr>
97 <td valign="top"><b>Attribute</b></td>
98 <td valign="top"><b>Description</b></td>
99 <td align="center" valign="top"><b>Required</b></td>
100 </tr>
101 <tr>
102 <td valign="top">file</td>
103 <td valign="top">The XML file to parse.</td>
104 <td valign="top" align="center">Yes, or a nested resource collection.</td>
105 </tr>
106 <tr>
107 <td valign="top">prefix</td>
108 <td valign="top">The prefix to prepend to each property</td>
109 <td valign="top" align="center">No</td>
110 </tr>
111 <tr>
112 <td valign="top">keepRoot</td>
113 <td valign="top">Keep the xml root tag as the
114 first value in the property name.</td>
115 <td valign="top" align="center">No, default is <i>true</i>.</td>
116 </tr>
117 <tr>
118 <td valign="top">validate</td>
119 <td valign="top">Validate the input file (e.g. by a DTD). Otherwise the XML must only be well-formed.</td>
120 <td valign="top" align="center">No, default is <i>false</i>.</td>
121 </tr>
122 <tr>
123 <td valign="top">collapseAttributes</td>
124 <td valign="top">Treat attributes as nested elements.</td>
125 <td valign="top" align="center">No, default is <i>false</i>.</td>
126 </tr>
127 <tr>
128 <td valign="top">semanticAttributes</td>
129 <td valign="top">Enable special handling of certain attribute names.
130 See the <a href="#semanticAttributes">Semantic Attributes</a>
131 section for more information.</td>
132 <td valign="top" align="center">No, default is <i>false</i>.</td>
133 </tr>
134 <tr>
135 <td valign="top">includeSemanticAttribute</td>
136 <td valign="top">Include the semantic attribute name
137 as part of the property name. Ignored if
138 <i>semanticAttributes</i> is not set to <i>true</i>.
139 See the <a href="#semanticAttributes">Semantic Attributes</a>
140 section for more information.</td>
141 <td valign="top" align="center">No, default is <i>false</i>.</td>
142 </tr>
143 <tr>
144 <td valign="top">rootDirectory</td>
145 <td valign="top">The directory to use for resolving file references. Ignored
146 if <i>semanticAttributes</i> is not set to <i>true</i>.</td>
147 <td valign="top" align="center">No, default is <i>${basedir}</i>.</td>
148 </tr>
149</table>
150
151<h3><a name="nested">Nested Elements</a></h3>
152<h4>xmlcatalog</h4>
153<p>The <a href="../CoreTypes/xmlcatalog.html"><tt>&lt;xmlcatalog&gt;</tt></a>
154element is used to perform entity resolution.</p>
155
156<h4>any <a href="../CoreTypes/resources.html">resource</a> or single element
157resource collection</h4>
158
159<p>The specified resource will be used as input.</p>
160
161<a name="examples">
162<h3>Examples</h3>
163</a>
164
165<h4>Non-semantic Attributes</h4>
166
167<p>Here is an example xml file that does not have any semantic attributes.</p>
168
169<pre>
170 &lt;root-tag myattr="true"&gt;
171 &lt;inner-tag someattr="val"&gt;Text&lt;/inner-tag&gt;
172 &lt;a2&gt;&lt;a3&gt;&lt;a4&gt;false&lt;/a4&gt;&lt;/a3&gt;&lt;/a2&gt;
173 &lt;/root-tag&gt;
174</pre>
175
176<h5>default loading</h5>
177<p>This entry in a build file:
178<pre> &lt;xmlproperty file="somefile.xml"/&gt;</pre>
179is equivalent to the following properties:
180<pre>
181 root-tag(myattr)=true
182 root-tag.inner-tag=Text
183 root-tag.inner-tag(someattr)=val
184 root-tag.a2.a3.a4=false
185</pre>
186
187<h5>collapseAttributes=false</h5>
188<p>This entry in a build file:
189<pre> &lt;xmlproperty file="somefile.xml" collapseAttributes="true"/&gt;</pre>
190is equivalent to the following properties:
191<pre>
192 root-tag.myattr=true
193 root-tag.inner-tag=Text
194 root-tag.inner-tag.someatt=val
195 root-tag.a2.a3.a4=false
196</pre>
197
198<h5>keepRoot=false</h5>
199<p>This entry in a build file:
200<pre> &lt;xmlproperty file="somefile.xml" keepRoot="false"/&gt;</pre>
201is equivalent to the following properties:
202<pre>
203 inner-tag=Text
204 inner-tag(someattr)=val
205 a2.a3.a4=false
206</pre>
207
208<h4>Semantic Attributes</h4>
209
210<p>Here is an example xml file that has semantic attributes.</p>
211<pre>
212 &lt;root-tag&gt;
213 &lt;version value="0.0.1"/&gt;
214 &lt;build folder="build"&gt;
215 &lt;classes id="build.classes" location="${build.folder}/classes"/&gt;
216 &lt;reference refid="build.classes"/&gt;
217 &lt;/build&gt;
218 &lt;compile&gt;
219 &lt;classpath pathid="compile.classpath"&gt;
220 &lt;pathelement location="${build.classes}"/&gt;
221 &lt;/classpath&gt;
222 &lt;/compile&gt;
223 &lt;run-time&gt;
224 &lt;jars&gt;*.jar&lt;/jars&gt;
225 &lt;classpath pathid="run-time.classpath"&gt;
226 &lt;path refid="compile.classpath"/&gt;
227 &lt;pathelement path="${run-time.jars}"/&gt;
228 &lt;/classpath&gt;
229 &lt;/run-time&gt;
230 &lt;/root-tag&gt;
231</pre>
232
233<h5>default loading (semanticAttributes=true)</h5>
234<p>This entry in a build file:
235<pre> &lt;xmlproperty file="somefile.xml"
236 semanticAttributes="true"/&gt;</pre>
237is equivalent to the following entries in a build file:
238<pre>
239 &lt;property name="version" value="0.0.1"/&gt;
240 &lt;property name="build.folder" value="build"/&gt;
241 &lt;property name="build.classes" location="${build.folder}/classes" id="build.classes"/&gt;
242 &lt;property name="build.reference" refid="build.classes"/&gt;
243
244 &lt;property name="run-time.jars" value="*.jar/&gt;
245
246 &lt;classpath id="compile.classpath"&gt;
247 &lt;pathelement location="${build.classes}"/&gt;
248 &lt;/classpath&gt;
249
250 &lt;classpath id="run-time.classpath"&gt;
251 &lt;path refid="compile.classpath"/&gt;
252 &lt;pathelement path="${run-time.jars}"/&gt;
253 &lt;/classpath&gt;
254</pre>
255
256<h5>includeSemanticAttribute="true"</h5>
257<p>This entry in a build file:
258<pre> &lt;xmlproperty file="somefile.xml"
259 semanticAttributes="true"
260 includeSemanticAttribute="true"/&gt;
261</pre>
262is equivalent to the following entries in a build file:
263<pre>
264 &lt;property name="version.value" value="0.0.1"/&gt;
265 &lt;property name="build.folder" value="build"/&gt;
266 &lt;property name="build.classes.location" location="${build.folder}/classes"/&gt;
267 &lt;property name="build.reference.refid" refid="build.location"/&gt;
268
269 &lt;property name="run-time.jars" value="*.jar/&gt;
270
271 &lt;classpath id="compile.classpath"&gt;
272 &lt;pathelement location="${build.classes}"/&gt;
273 &lt;/classpath&gt;
274
275 &lt;classpath id="run-time.classpath"&gt;
276 &lt;path refid="compile.classpath"/&gt;
277 &lt;pathelement path="${run-time.jars}"/&gt;
278 &lt;/classpath&gt;
279</pre>
280
281
282
283</body>
284</html>
Note: See TracBrowser for help on using the repository browser.