| <!-- |
| 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>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><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> |
| |
| <p>Pumps the project version to the next minor version (increase minor and set path=0): |
| <blockquote><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></blockquote> |
| After running this target the version changed e.g. from 3.2.2 to 3.3.0. |
| </p> |
| |
| |
| </body> |
| </html> |
