| <!DOCTYPE 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 |
| |
| https://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 lang="en"> |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>PropertyFile Task</title> |
| </head> |
| |
| <body> |
| |
| <h1>PropertyFile</h1> |
| <hr/> |
| <h2 id="introduction">Introduction</h2> |
| <p>Apache 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. <em>Since Ant 1.8.0</em> comments and layout of the |
| original properties file are preserved.</p> |
| |
| <p><em>Since Ant 1.8.2</em> the linefeed-style of the original file will be preserved as well, as |
| long as style used to be consistent. In general, linefeeds of the updated file will be the same as |
| the first linefeed found when reading it.</p> |
| |
| <hr/> |
| |
| <h2 id="proptask">PropertyFile Task</h2> |
| <h3>Parameters</h3> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>file</td> |
| <td>Location of the property file to be edited</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>comment</td> |
| <td>Header for the file itself</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>jdkproperties</td> |
| <td>Use <code>java.lang.Properties</code>, which will lose comments and layout of file. <em>since |
| Ant 1.8.0</em></td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| </table> |
| |
| <p>The boolean attribute <var>jdkproperties</var> 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 id="entryElement">Entry</h4> |
| <p>Use nested <code><entry></code> elements to specify actual modifications to the property |
| file itself.</p> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>key</td> |
| <td>Name of the property name/value pair</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>value</td> |
| <td>Value to set (<q>=</q>), to add (<q>+</q>) or subtract (<q>-</q>)</td> |
| <td rowspan="2">At least one must be specified, if <var>operation</var> is not <q>del</q></td> |
| </tr> |
| <tr> |
| <td>default</td> |
| <td class="left">Initial value to set for a property if it is not already defined in the |
| property file.<br/>For type <var>date</var>, an additional keyword is |
| allowed: <q>now</q></td></tr> |
| <tr> |
| <td>type</td> |
| <td>Regard the value as: <q>int</q>, <q>date</q> or <q>string</q> (default)</td> |
| <td>No; defaults to <q>string</q></td> |
| </tr> |
| <tr> |
| <td>operation</td> |
| <td>One of the following operations:<br/> |
| <strong>for all datatypes:</strong> |
| <ul> |
| <li><q>del</q> : deletes an entry</li> |
| <li><q>+</q> : adds a value to the existing value</li> |
| <li><q>=</q> : sets a value instead of the existing value (default)</li> |
| </ul> |
| <strong>for <var>date</var> and <var>int</var> only:</strong> |
| <ul> |
| <li><q>-</q> : subtracts a value from the existing value</li> |
| </ul> |
| </td> |
| <td>No; defaults to <q>=</q></td> |
| </tr> |
| <tr> |
| <td>pattern</td> |
| <td>For <var>int</var> and <var>date</var> type only. If present, values will be parsed and |
| formatted accordingly.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>unit</td> |
| <td>The unit of the value to be applied to <var>date</var> <q>+</q>/<q>-</q> operations. Valid |
| Values are: |
| <ul> |
| <li><q>millisecond</q></li> |
| <li><q>second</q></li> |
| <li><q>minute</q></li> |
| <li><q>hour</q></li> |
| <li><q>day</q> (default)</li> |
| <li><q>week</q></li> |
| <li><q>month</q></li> |
| <li><q>year</q></li> |
| </ul> |
| This only applies to <var>date</var> types using a <q>+</q>/<q>-</q> operation. |
| </td> |
| <td>No; defaults to <q>day</q></td> |
| </tr> |
| </table> |
| <p>The rules used when setting a property value are shown below. The operation |
| occurs <strong>after</strong> these rules are considered.</p> |
| |
| <ul> |
| <li>If only <var>value</var> is specified, the property is set to it regardless of its previous |
| value.</li> |
| <li>If only <var>default</var> is specified and the property previously existed in the property |
| file, it is unchanged.</li> |
| <li>If only <var>default</var> is specified and the property did not exist in the property file, |
| the property is set to <var>default</var>.</li> |
| <li>If <var>value</var> and <var>default</var> are both specified and the property previously |
| existed in the property file, the property is set to <var>value</var>.</li> |
| <li>If <var>value</var> and <var>default</var> are both specified and the property did not exist |
| in the property file, the property is set to <var>default</var>.</li> |
| </ul> |
| |
| <h3>Examples</h3> |
| |
| <p>The following changes the <samp>my.properties</samp> file. Assume <samp>my.properties</samp> |
| looks 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> |
| |
| <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> |
| <p>To produce dates relative from today:</p> |
| <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> |
| |
| <p>Concatenation of strings:</p> |
| <pre> |
| <propertyfile file="my.properties" |
| comment="My properties"> |
| <entrykey="progress" default="" operation="+" value="."/> |
| </propertyfile></pre> |
| <p>Each time called, a <q>.</q> will be appended to <code>progress</code></p> |
| |
| <p>Pumps the project version to the next minor version (increase minor and |
| set <code>patch=0</code>):</p> |
| <pre> |
| <target name="nextMinorVersion"> |
| <property name="header" |
| value="##Generated file - do not modify!"/> |
| <propertyfile file="version.properties" comment="${header}"> |
| <entry key="product.build.major" type="int" value="3"/> |
| <entry key="product.build.minor" type="int" operation="+"/> |
| <entry key="product.build.patch" type="int" value="0"/> |
| <entry key="product.build.date" type="date" value="now"/> |
| </propertyfile> |
| </target></pre> |
| <p>After running this target the version changed e.g. from 3.2.2 to 3.3.0.</p> |
| |
| </body> |
| </html> |