mirror of
https://github.com/apache/ant.git
synced 2025-05-21 23:44:46 +00:00
c7ec6f659f
git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@904452 13f79535-47bb-0310-9956-ffa450edef68
228 lines
8.4 KiB
HTML
228 lines
8.4 KiB
HTML
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|
<title>PropertyFile Task</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1>PropertyFile</h1>
|
|
|
|
<hr>
|
|
<h2><a name="introduction">Introduction</a></h2>
|
|
<p>Ant provides an optional task for editing property files. This is
|
|
very useful when wanting to make unattended modifications to
|
|
configuration files for application servers and
|
|
applications. Currently, the task maintains a working property file
|
|
with the ability to add properties or make changes to existing
|
|
ones. Since Ant 1.8.0 comments and layout of the original properties
|
|
file are preserved.</p>
|
|
|
|
<hr>
|
|
<h2><a name="proptask">PropertyFile Task</a></h2>
|
|
<h3>Parameters</h3>
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
<tr>
|
|
<td width="12%" valign="top"><b>Attribute</b></td>
|
|
<td width="78%" valign="top"><b>Description</b></td>
|
|
<td width="10%" valign="top"><b>Required</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td width="12%" valign="top">file</td>
|
|
<td width="78%" valign="top">Location of the property file to be edited</td>
|
|
<td width="10%" valign="top">Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td width="12%" valign="top">comment</td>
|
|
<td width="78%" valign="top">Header for the file itself</td>
|
|
<td width="10%" valign="top">no</td>
|
|
</tr>
|
|
<tr>
|
|
<td width="12%" valign="top">jdkproperties</td>
|
|
<td width="78%" valign="top">Use java.lang.Properties, which will
|
|
loose comments and layout of file (default is 'false'). <em>since
|
|
Ant 1.8.0</em></td>
|
|
<td width="10%" valign="top">no</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The boolean attribute 'jdkproperties' is provided to recover the
|
|
previous behaviour of the task, in which the layout and any comments
|
|
in the properties file were lost by the task.</p>
|
|
|
|
<h3>Parameters specified as nested elements</h3>
|
|
<h4><a name="entryElement">Entry</a></h4>
|
|
<p>Use nested <code><entry></code>
|
|
elements to specify actual modifications to the property file itself.</p>
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
<tr>
|
|
<td valign="top"><b>Attribute</b></td>
|
|
<td valign="top"><b>Description</b></td>
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">key</td>
|
|
<td valign="top">Name of the property name/value pair</td>
|
|
<td valign="top" align="center">Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">value</td>
|
|
<td valign="top">Value to set (=), to add (+) or subtract (-)</td>
|
|
<td valign="top" align="center" rowspan="2">At least one must be specified, if <i>operation</i> is not <i>delete</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">default</td>
|
|
<td valign="top">Initial value to set for a property if it is not
|
|
already defined in the property file.<br>
|
|
For type date, an additional keyword is allowed: "now"</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">type</td>
|
|
<td valign="top">Regard the value as : int, date or string (default)</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">operation</td>
|
|
<td valign="top">One of the following operations:<br><br>
|
|
<b>for all datatypes:</b><ul>
|
|
<li>"del" : deletes an entry</li>
|
|
<li>"+" : adds a value to the existing value</li>
|
|
<li>"=" : sets a value instead of the existing value (default)</li>
|
|
</ul><br><b>for date and int only:</b><ul>
|
|
<li>"-" : subtracts a value from the existing value</li>
|
|
</ul>
|
|
</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">pattern</td>
|
|
<td valign="top">For int and date type only. If present, Values will
|
|
be parsed and formatted accordingly.</td>
|
|
<td valign="top" align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">unit</td>
|
|
<td valign="top">The unit of the value to be applied to date +/- operations.
|
|
Valid Values are:
|
|
<ul>
|
|
<li>millisecond</li>
|
|
<li>second</li>
|
|
<li>minute</li>
|
|
<li>hour</li>
|
|
<li>day (default)</li>
|
|
<li>week</li>
|
|
<li>month</li>
|
|
<li>year</li>
|
|
</ul>
|
|
This only applies to date types using a +/- operation.
|
|
</td>
|
|
<td align="center" valign="top">No</td>
|
|
</tr>
|
|
</table>
|
|
<p>The rules used when setting a property value are shown below. The
|
|
operation occurs <b>after</b> these rules are considered.</p>
|
|
|
|
<ul>
|
|
<li>If only value is specified, the property is set to it regardless of its
|
|
previous value.</li>
|
|
<li>If only default is specified and the property previously existed in the
|
|
property file, it is unchanged.</li>
|
|
<li>If only default is specified and the property did not exist in the
|
|
property file, the property is set to default.</li>
|
|
<li>If value and default are both specified and the property previously
|
|
existed in the property file, the property is set to value.</li>
|
|
<li>If value and default are both specified and the property did not exist in
|
|
the property file, the property is set to default.</li>
|
|
</ul>
|
|
<p> </p>
|
|
|
|
<h3>Examples</h3>
|
|
|
|
<p>The following changes the my.properties file. Assume my.properties look like:</p>
|
|
|
|
<pre># A string value
|
|
akey=original value
|
|
|
|
# The following is a counter, which will be incremented by 1 for
|
|
# each time the build is run.
|
|
anint=1</pre>
|
|
|
|
<p>After running, the file would now look like
|
|
</p>
|
|
<pre>#My properties
|
|
#Wed Aug 31 13:47:19 BST 2005
|
|
# A string value
|
|
akey=avalue
|
|
|
|
# The following is a counter, which will be incremented by 1 for
|
|
# each time the build is run.
|
|
anint=2
|
|
|
|
adate=2005/08/31 13\:47
|
|
|
|
formated.int=0014
|
|
|
|
formated.date=243 13\:47</pre>
|
|
<p>
|
|
The slashes conform to the expectations of the Properties class. The file will be stored in a manner so that each character is examined and escaped if necessary.
|
|
</p>
|
|
|
|
<p>
|
|
The layout and comment of the original file is preserved. New properties are added at the end of the file. Existing properties are overwritten in place.
|
|
</p>
|
|
|
|
<blockquote><pre><propertyfile
|
|
file="my.properties"
|
|
comment="My properties">
|
|
<entry key="akey" value="avalue"/>
|
|
<entry key="adate" type="date" value="now"/>
|
|
<entry key="anint" type="int" default="0" operation="+"/>
|
|
<entry key="formated.int" type="int" default="0013" operation="+" pattern="0000"/>
|
|
<entry key="formated.date" type="date" value="now" pattern="DDD HH:mm"/>
|
|
</propertyfile>
|
|
</pre></blockquote>
|
|
<p>
|
|
To produce dates relative from today :</p>
|
|
<blockquote><pre><propertyfile
|
|
file="my.properties"
|
|
comment="My properties">
|
|
<entry key="formated.date-1"
|
|
type="date" default="now" pattern="DDD"
|
|
operation="-" value="1"/>
|
|
<entry key="formated.tomorrow"
|
|
type="date" default="now" pattern="DDD"
|
|
operation="+" value="1"/>
|
|
</propertyfile>
|
|
</pre></blockquote>
|
|
|
|
<p>
|
|
Concatenation of strings :</p>
|
|
<blockquote><pre><propertyfile
|
|
file="my.properties"
|
|
comment="My properties">
|
|
<entry key="progress" default="" operation="+" value="."/>
|
|
</propertyfile>
|
|
</pre></blockquote>
|
|
<p>Each time called, a "." will be appended to "progress"
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|