maven-archetypeのススメ

archetypeとは

Maven2プロジェクトの雛形のことをarchetypeといいます。

$ mvn archetype:generate

とすると、デフォルトで利用できる41個のarchetypeのリストから選択してプロジェクトを生成することができます。
Maven2の使い方では、コマンドライン引数で指定することによってmaven-archetype-webappというarchetypeを使って簡単なプロジェクトを作成しました。

このarchetypeというプロジェクトの雛形に良く使うプラグインや依存ライブラリを設定してあるpom.xmlファイルや、他のリソースファイルなどをあらかじめ組み込んでおくことでプロジェクト開始時の初期設定の手間を軽減することができるようになります。

<packaging>maven-archetype</packaging>

それでは、実際にarchetypeを作ってみます。
archetypeプロジェクトの基本的なディレクトリ構造は以下のようになります。

+ sample-archetype
    + src
        + main
            + resources
                + archetype-resources
                    - pom.xml 
                + META-INF
                    + maven
                        - archetype-metadata.xml
    - pom.xml

ここで、src/main/resources/archetype-resources以下がこのarchetypeを使って生成するプロジェクトの雛形になります。
src/main/resources/archetype-resources/pom.xmlファイルに毎度面倒になる設定を記述しておき、src/main/resources/archetype-resources/src/以下に基本となるソースファイルや設定ファイルなどのリソースファイルを配置しておきます。

sample-archetype/pom.xml

<project>
	<modelVersion>4.0.0</modelVersion>
	<groupId>st.happy_camper.sample</groupId>
	<artifactId>sample-archetype</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>maven-archetype</packaging>
	<build>
		<extensions>
			<extension>
				<groupId>org.apache.maven.archetype</groupId>
				<artifactId>archetype-packaging</artifactId>
			</extension>
		</extensions>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-archetype-plugin</artifactId>
				<extensions>true</extensions>
			</plugin>
		</plugins>
	</build>
</project>

archetypeのpackage / install / deployは通常通りです。

$ mvn package
$ mvn install
$ mvn deploy

install / deployをするとローカルのarchetype-catalog.xmlファイルに登録され、

$ mvn archetype:generate

で表示されるarchetypeのリストに含まれるようになります。

archetype-metadata.xml

archetype-metadata.xmlファイルには、このarchetypeに含まれるファイルやプロパティなどについての情報を記述します。

src/main/resources/META-INF/maven/archetype-metadata.xml

<?xml version="1.0" encoding="UTF-8"?>
<archetype-descriptor name="sample-archetype">
  <fileSets>
    <fileSet filtered="true" packaged="true" encode="UTF-8">
      <directory>src/main/java</directory>
      <includes>
        <include>**/*.java</include>
      </includes>
    </fileSet>
  </fileSets>
</archetype-descriptor>

<fileSet>

このarchetypeに含まれるファイル情報について記述します。

• filtered属性
  
  プロジェクトを生成する際にVelocityテンプレートエンジンによりプロパティの埋め込みを行うかどうか。
  trueを指定するとテンプレート内に記述してある${groupId}/${artifactId}/${version}などの文字列をプロジェクト生成時の指定値に置き換えて生成する。
  
  デフォルトはfalse。
  
  
• packaged属性
  
  プロジェクトを生成するときにファイルを${package}で指定したパッケージに配置するかどうか。
  Javaソースファイルなどは${package}に配置しなければならないため、trueを指定する。
  その他のファイルも必要に応じてtrueを指定する。
  
  デフォルトはfalse。
  
  
• encoding属性
  
  ファイルの文字コードを指定する。
  
  デフォルトはUTF-8。
  
  
• <directory>タグ
  
  この<fileSet>タグの設定対象となるディレクトリを指定する。
  
  
• <includes>タグ
  
  このfileSetに含めるファイルを指定する。
  
  
• <excludes>タグ
  
  このfileSetから除外するファイルを指定する。
  

<fileSet>タグは並べて複数記述することができるので、ソースファイル、リソースファイルなどの特徴に合わせて設定していきます。

archetype:create-from-project

基本的な設定を施したプロジェクトがあれば、そこからarchetypeプロジェクトを生成することができます。

そのプロジェクトのルートディレクトリで、

$ mvn archetype:create-from-project

とすると、target/generated-sources/archetypeにarchetypeプロジェクトができます。
設定などを見直してpackage / install / deployを行えば新たなarchetypeとして利用できるようになります。

archetype-catalog.xml

たくさんのarchetypeを作成したら、archetype-catalog.xmlファイルを作成しておけばarchetypeのgroupId/artifactIdなどを覚えておかなくてもこのファイルを指定して登録されているarchetypeのリストから選択する形でプロジェクトを開始できるようになります。

archetype-catalog.xml

<?xml version="1.0" encoding="UTF-8"?>
<archetype-catalog>
  <archetypes>
    <archetype>
      <groupId>st.happy_camper.sample</groupId>
      <artifactId>sample-archetype</artifactId>
      <version>0.0.1-SNAPSHOT</version>
      <repository>http://maven.repository/maven2-snapshot</repository>
    </archetype>
  </archetypes>
</archetype-catalog>

<archetype>タグは並べて複数記述することができます。

このファイルを例えばhttp://maven.repository/archetype-catalog.xmlに置いたとしたら、

$ mvn archetype:generate -DarchetypeCatalog=http://maven.repository/archetype-catalog.xml

とすれば登録されているarchetypeがリストで表示され、選択することでプロジェクトを作成できます。