maven AutoConfig使用

AutoConfig的使用

建立AutoConfig目录结构

和Maven Filtering不同的是，AutoConfig是针对目标文件的配置工具。

因此AutoConfig关心的目录结构是目标文件的目录结构。

不同的build工具，创建同一目标目录结构所需要的源文件的目录结构会各有不同。

本文仅以maven标准目录结构为例，来说明源文件的目录结构编排。

 

WAR包的目录结构

下面以maven标准目录为例，说明项目源文件和目标文件的目录结构的对比：

 

/META-INF/autoconf目录用来存放AutoConfig的描述文件，以及可选的模板文件。

auto-config.xml是用来指导AutoConfig行为的关键描述文件。

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

该描述文件对应的maven项目源文件为：/src/main/webapp/META-INF/autoconf/auto-config.xml。

 

JAR包的目录结构

下面以maven标准目录为例，说明项目源文件和目标文件的目录结构的对比：

 

/META-INF/autoconf目录用来存放AutoConfig的描述文件，以及可选的模板文件。

auto-config.xml是用来指导AutoConfig行为的关键描述文件。

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

该描述文件对应的maven项目源文件为：/src/main/resources/META-INF/autoconf/auto-config.xml。

 

普通目录

AutoConfig也支持对普通文件目录进行配置。

 

默认情况下，AutoConfig在/conf目录中寻找AutoConfig的描述文件，以及可选的模板文件。

auto-config.xml是用来指导AutoConfig行为的关键描述文件。

 

建立auto-config.xml描述文件

AutoConfig系统的核心就是auto-config.xml描述文件。

该描述文件中包含两部分内容：

1、定义properties：properties的名称、描述、默认值、约束条件等信息。

2、指定包含placeholders的模板文件。

 

定义properties

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

<property

    name="..."

    [defaultValue="..."]

    [description="..."]

    [required="true|false"]

>

    <validator name="..." />

    <validator name="..." />

    ...

</property>

定义property时可用的参数

参数名说明

nameProperty名称。

defaultValue（可选）默认值。默认值中可包含对其它property的引用，如${petstore.work}/logs。

description（可选）对字段的描述，这个描述会显示给deployer，这对他理解该property非常重要。

required（可选）是否“必填”，默认为true。如果deployer未提供必填项的值，就会报错。

 

定义property的验证规则

 

生成配置文件的指令

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

<generate

    template="..."

    [destfile="..."]

    [charset="..."]

    [outputCharset="..."]

>

参数名说明

template需要配置的模板名。模板名为相对路径，相对于当前jar/war/ear包的根目录。

destfile（可选）目标文件。如不指定，表示目标文件和模板文件相同。

charset（可选）模板的字符集编码。XML文件不需要指定charset，因为AutoConfig可以自动取得XML文件的字符集编码；对其它文件必须指定charset。

outputCharset（可选）目标文件的输出字符集编码。如不指定，表示和模板charset相同。

 

建立模板文件

定义完auto-config.xml描述文件以后，就可以创建模板了。模板放在哪里呢？

假设在一个典型的WEB应用中，你的auto-config.xml中包含指定了如下模板：

 

那么，你可以把file1.xml、file2.xml、file3.xml放在下面的位置：

 

AutoConfig的寻找模板的逻辑是：

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

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

 

模板的写法

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

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

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

 

模板示例

...

<context-param>

    <param-name>loggingRoot</param-name>

    <param-value>${petstore.loggingRoot}</param-value>

</context-param>

<context-param>

    <param-name>loggingLevel</param-name>

    <param-value>${petstore.loggingLevel}</param-value>

</context-param>

...

${D}{runtime.placeholder}

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

使用不符合velocity语法的placeholders

例如

${my.property.2}

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

${my_property_2}