Maven Shade PluginのPropertiesTransformerの例

Maven Shade Pluginは、プロジェクトのビルドプロセス中に依存関係を結合することができる拡張機能です。このプラグインの目的は、アプリケーションのすべての依存関係とそのコードを含む単一のJARファイルを作成することです。

このプロセス内で、*.propertiesのような設定ファイルのマージが問題になることがあります。デフォルトでは、最後に見つかったファイルが結果のアーティファクト内でその場所を勝ち取ります。このプラグインは、そうした問題を解決し、リソースマージの振る舞いを制御するために、トランスフォーマーと呼ばれる設定を提供しています。

PropertiesTransformer変換

プラグイン自体は、複数の事前にインストールされたトランスフォーマーを提供しています。より複雑なものは、外部プロバイダーからインポートできます。バージョン3.2.2以降、開発者はorg.apache.maven.plugins.shade.resource.properties.PropertiesTransformerの実装も提供しています。プロパティの結合順序を変更したい場合、その名前は非常に有望に聞こえるかもしれません。アプリケーションが優先される（通常は上書きされる）プロパティをロードするようにしたい場合があります。

PropertiesTransformerを見て、サンプル設定（以下参照）を試すと、期待した結果を得るのが難しいかもしれません。プロパティの説明は少し表面的に思えるかもしれませんが、だからこそ、例でその振る舞いを見るのが最善です（バージョン3.4.1）。

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.4.1</version>
        <executions>
          <execution>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <transformers>
                <transformer implementation="org.apache.maven.plugins.shade.resource.properties.PropertiesTransformer">
                  <!-- required configuration -->
                  <resource>configuration/application.properties</resource>
                  <ordinalKey>ordinal</ordinalKey>
                  <!-- optional configuration -->
                  <alreadyMergedKey>already_merged</alreadyMergedKey>
                  <defaultOrdinal>0</defaultOrdinal>
                  <reverseOrder>false</reverseOrder>
                </transformer>
              </transformers>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

モジュールAとモジュールBにそれぞれ2つのconfiguration/application.propertiesファイルがあるとします。

#module-a configuration/application.properties
prop1=A
prop2=B

#module-b configuration/application.properties
prop2=C
prop3=D

maven-shade-pluginのshadeゴールとPropertiesTransformerが両方の依存関係を結合すると、デフォルトで次のconfiguration/application.propertiesファイルが生成されます。

# Merged by maven-shade-plugin (org.apache.maven.plugins.shade.resource.properties.PropertiesTransformer)
prop1=A
prop2=C
prop3=D

ordinalKeyとdefaultOrdinal

ファイルがマージされる順序は、ordinalKeyによって制御されます。これは、その値が数値順序であるプロパティの名前を指します。プロパティファイルにそのようなキーが含まれていない場合、その順序はdefaultOrdinal（欠落している場合は0）によって定義されます。モジュールAのファイルでデフォルトよりも高い順序を定義することで：

#module-a configuration/application.properties
prop1=A
prop2=B
ordinal=1

#module-b configuration/application.properties
prop2=C
prop3=D

出力では、モジュールAのプロパティprop2が得られ、事実上、逆の順序を達成します。さらに、トランスフォーマーは人工的なキーを削除します。

# Merged by maven-shade-plugin (org.apache.maven.plugins.shade.resource.properties.PropertiesTransformer)
prop1=A
prop2=B
prop3=D

alreadyMergedKey

alreadyMergedKeyは、ファイルの優先順位を示すboolean値型（例：true String）のプロパティ名を定義します。これにより、トランスフォーマーはこのファイルに他のファイルをマージしません。

#module-a configuration/application.properties
prop1=A
prop2=B
already_merged=true

#module-b configuration/application.properties
prop2=C
prop3=D

このようなプロパティの場合、モジュールAのプロパティのコピーが得られ、ここでもalready_merged合成キーが削除されます。

# Merged by maven-shade-plugin (org.apache.maven.plugins.shade.resource.properties.PropertiesTransformer)
prop1=A
prop2=B

複数のファイルでこのようなキーがtrue値で出現することは許可されておらず、エラーになります。

reverseOrder

reverseOrderオプションを使用して、ファイルの連結順序を逆にすることができます。残念ながら、この機能は同じ順序値を持つファイル間の順序を逆にすることはありません。つまり、<reverseOrder>true</reverseOrder>と2つのプロパティファイルに対して：

#module-a configuration/application.properties
prop1=A
prop2=B

#module-b configuration/application.properties
prop2=C
prop3=D

それでも（reverseOrderの値に関係なく）同じ結果が得られます。

# Merged by maven-shade-plugin (org.apache.maven.plugins.shade.resource.properties.PropertiesTransformer)
prop1=A
prop2=C
prop3=D

逆転は、ordinalKeyで順序を定義した後、かつ異なる順序のファイル間でのみ機能します。

まとめ

PropertiesTransformerは、プロパティファイルの基本的なマージを可能にします。ファイルは最初に java.util.Propertiesを使用してロードされることを知っておく価値があります。これは、同じファイル内の重複が最新の（一番下に近い）プロパティで上書きされることを意味します。

ファイルのマージ順序を決定したり、複数のファイルの中から優先ファイルを指定したりするには、人工的なキーを含める必要があります。残念ながら、同じまたはデフォルトの順序値を持つファイル間の順序を逆にすることはできません。

したがって、少し異なるマージ動作（例えば、人工的なキーを追加する必要がないなど）が必要な場合は、カスタムトランスフォーマーを備えた外部アドオンパックを探してください。 <dependencies></dependencies>タグを<plugin></plugin>内に使用することで、そのような依存関係を簡単に追加できます。単にプロパティを逆の順序で結合したい場合は、 org.kordamp.shade:maven-shade-ext-transformers:1.4.0をご覧ください。