AutoConfig工具使用

下载安装Auto工具包：

• http://code.taobao.org/mvn/repository/com/alibaba/citrus/tool/antx-autoconfig/1.0.9/antx-autoconfig-1.0.9.tgz
• http://code.taobao.org/mvn/repository/com/alibaba/citrus/tool/antx-autoexpand/1.0.9/antx-autoexpand-1.0.9.tgz

tar zxvf autoconfig-1.0.9.tgz
tar zxvf autoexpand-1.0.9.tgz
cp autoconfig /usr/local/bin
cp autoexpand /usr/local/bin
------------------------------------------------------------------------------------------------------

引：<filter>${user.home}/antx.properties</filter>
用指定的properties文件（${user.home}/antx.properties）中的值，替换上述文件行中的placeholders(占位符)

AutoConfig不需要提取源码，也不需要重新build，即可改变目标文件中所有配置文件中placeholders的值，并对placeholder及其值进行检查。

AutoConfig Features：

名称	描述
两种用法	既可独立使用（支持Windows和Unix-like平台）。 也可以作为maven插件来使用。
对目标文件而不是源文件进行配置	可对同一个目标文件反复配置。 配置时不依赖于项目源文件。 支持嵌套包文件，例如：ear包含war，war又包含jar。 高性能，特别对于嵌套的包文件。
验证和编辑properties	自动发现保存于war包、jar包、ear包中的properties定义。 验证properties的正确性。 交互式编辑properties。 当配置文件中出现未定义的placeholders时，提示报错。

	/META-INF/autoconf目录用来存放AutoConfig的描述文件，以及可选的模板文件。
	auto-config.xml是用来指导AutoConfig行为的关键描述文件

 创建war和jar包的AutoConfig机制，关键在于创建war或jar目标包中的/META-INF/autoconf/auto-config.xml描述文件

-------------------------------------------------------------------------------------------------------------

AutoConfig描述文件示例:

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <group>

        <property name="petstore.work"
                    description="应用程序的工作目录" />

        <property name="petstore.loggingRoot" 
                    defaultValue="${petstore.work}/logs"
                    description="日志文件目录" /> 

        <property name="petstore.upload"
                    defaultValue="${petstore.work}/upload"
                    description="上传文件的目录" />

        <property name="petstore.loggingLevel"
                    defaultValue="warn"
                    description="日志文件级别"> 

            <validator name="choice"
                         choice="trace, debug, info, warn, error" /> 

        </property>

    </group>
    <script>
        <generate template="WEB-INF/web.xml" /> 

        <generate template="WEB-INF/common/resources.xml" />
    </script>
</config>

	定义properties
	定义property的验证规则（可选）
	生成配置文件的指令。

定义一个property的完整格式如下：

例如下定义一个property

<property
    name="..."
    [defaultValue="..."]
    [description="..."]
    [required="true|false"]
>
    <validator name="..." />
    <validator name="..." />
    ...
</property>

可用的property参数包括：

定义property时可用的参数如下:

参数名	说明
name	Property名称。
defaultValue（可选）	默认值。默认值中可包含对其它property的引用，如${petstore.work}/logs
description（可选）	对字段的描述，这个描述会显示给deployer，这对他理解该property非常重要。
required（可选）	是否“必填”，默认为true。如果deployer未提供必填项的值，就会报错。

 

 

定义property的验证规则

目前，有以下几种验证器：

可用的property验证规则如下

验证规则	说明
<validator name="boolean" />	Property值必须为true或false。
<validator name="choice" choice="trace, debug, info, warn, error" />	Property值必须为choice所定义的值之一。
<validator name="email" />	Property值必须为合法的email格式。
<validator name="fileExist" [file="WEB-INF/web.xml"] />	Property值必须为某个存在的文件或目录。 如果指定了file，那就意味着property值所指的目录下，必须存在file所指的文件或子目录。
<validator name="hostExist" />	Property值必须为合法的IP地址，或者可以解析得到的域名。
<validator name="keyword" />	Property值必须为字母、数字、下划线的组合。
<validator name="number" />	Property值必须为数字的组合。
<validator name="regexp" regexp="..." [mode="exact|prefix|contain"] />	Property值必须符合regexp所指的正则表达式。 其中，mode为匹配的方法： 完全匹配exact 前缀匹配prefix 包含contain 如未指定mode，默认mode为contain。
<validator name="url" [checkHostExist="false"] [protocols="http, https"] [endsWithSlash="true"] />	Property值必须是合法URL。 假如指定了checkHostExist=true，那么还会检查域名或IP的正确性； 假如指定了protocols，那么URL的协议必须为其中之一； 假如指定了endsWithSlash=true，那么URL必须以/结尾。

 

生成配置文件的指令

描述文件中，每个<generate>标签指定了一个包含placeholders的配置文件模板，具体格式为：

生成配置文件的指令：

<generate
    template="..."
    [destfile="..."]
    [charset="..."]
    [outputCharset="..."]
>

下面是参数的说明：

生成配置文件的指令参数：

参数名	说明
template	需要配置的模板名。 模板名为相对路径，相对于当前jar/war/ear包的根目录。
destfile（可选）	目标文件。 如不指定，表示目标文件和模板文件名相同，但是默认生成路径为包下的根目录，即Base URL目录
charset（可选）	模板的字符集编码。 XML文件不需要指定charset，因为AutoConfig可以自动取得XML文件的字符集编码； 对其它文件必须指定charset。
outputCharset（可选）	目标文件的输出字符集编码。 如不指定，表示和模板charset相同。

 

-------------------------------------------------------------------------------------------------------------

 

建立模板文件：

在auto-config.xml中定义了模板的位置后，把模板文件放在指定的位置。

AutoConfig的寻找模板的逻辑是：

• 如果在auto-config.xml所在的目录下发现模板文件，就使用它；

• 否则在包的根目录中查找模板文件；如果两处均未找到，则报错。

书写模板是很简单的事，你只要：

• 把需要配置的点替换成placeholder：“${property.name}”。当然，你得确保property.name被定义在auto-config.xml中。

• 假如模板中包含不希望被替换的运行时的placeholder“${...}”，需要更改成“${D}{...}” 。

此外，AutoConfig模板其实是由Velocity模板引擎来渲染的。因此，所有的placeholder必须能够通过velocity的语法。

使用不符合velocity语法的placeholders

例如，下面的placeholder被velocity看作非法：

${my.property.2}

解决的办法是，改写成如下样式：

${my_property_2}
----------------------------------------------------------------------------------------------------------

Autoconfig工具的使用

最简单的AutoConfig命令

autoconfig petstore.war        无论petstore.war是一个zip包还是目录，AutoConfig都会正确地生成其中的配置文件

AutoConfig会生成一个日志文件，就在auto-config.xml所在的目录下，名字为：auto-config.xml.log。

默认情况下，AutoConfig会按下列顺序查找user properties：

1. 当前目录 ./antx.properties

2. 当前用户HOME目录/antx.properties

你可以指定一个自己的properties文件，用下面的命令：

   autoconfig ... –u my.props

你可以指定另一个输出文件或目录，这样，原来的文件或目录就不会被修改:

   autoconfig petstore.war –o petstore-configured.war

一般不需要特别指定charset，除非AutoConfig自动识别系统编码出错，导致显示乱码。运行AutoConfig独立可执行程序
 autoconfig ... -c GBK

如果auto-config.xml描述文件中已定义了该”Property name“，而antx.properties文件中未指定相应”Property name“值，
则执行autoconfig时会提示如下图所示要求更新antx.properties配置文件内容。选择使用默认值或是手动更新指定值，使用默认值的话逐项选择Next后再选Yes保存即可。



假如发现模板中某个placeholder，并未在auto-config.xml中定义，就会出现以下错误：



摘自http://webx.taobao.org/docs/autoconfig.html