1 Mavenを使用したアプリケーション・ビルドの自動化

Oracle Fusion Middleware (FMW)アプリケーション開発者は通常、アプリケーションの開発中にOracle JDeveloper、Eclipse IDE、JetBrains IntelliJ IDEAなどの統合開発環境(IDE)を使用します。アプリケーションの品質を確保するために、業界のベスト・プラクティスでは、継続的インテグレーション(CI)システムを使用してアプリケーション変更の構築とテストを自動化することが提案されています。

この場合は通常、CIシステムがアプリケーション・バイナリを生成できるように、アプリケーションのビルドを自動化する必要があります。Apache Mavenは、Javaベース・アプリケーションの最も一般的なビルド・ツールの1つです。そのため、アプリケーション中心のほとんどのFMW製品では、Mavenを使用したアプリケーション・ビルドの自動化をサポートするMavenプラグイン、原型およびプロジェクト・オブジェクト・モデル(POM)が提供されます。

このリリースのOracle FMWアーティファクトは、Oracle MavenリポジトリなどのパブリックMavenリポジトリに公開されません。Mavenを使用してFMWアプリケーションをビルドする前に、Mavenリポジトリに必要なOracle FMWアーティファクトを移入する必要があります。

Mavenのインストールと構成

Mavenの使用を開始するには、https://maven.apache.orgからMavenディストリビューションをダウンロードしてインストールします。Mavenを使用するには、JDKおよびMavenインストール・ディレクトリを指すように次の環境変数を設定し、PATHに追加します。

Linuxの場合:
export JAVA_HOME=/usr/lib/jvm/jdk-17
export M2_HOME=/usr/lib/apache-maven
export PATH=${M2_HOME}/bin:${JAVA_HOME}/bin:${PATH}
macOSの場合:
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
export M2_HOME=/opt/apache-maven
export PATH=${M2_HOME}/bin:${JAVA_HOME}/bin:${PATH}
Windowsの場合:
set "JAVA_HOME=c:\java\jdk-17"
set "M2_HOME=c:\apache-maven"
set "PATH=%M2_HOME%\bin;%JAVA_HOME%\bin;%PATH%"
次のコマンドを実行して環境が適切に構成されていることを確認し、MavenとJavaの両方で必要なバージョンを確実に取得します。
mvn -v
Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /scratch/maven/apache-maven-3.9.9
Java version: 17.0.9.0.3, vendor: Oracle Corporation, runtime: /scratch/java/jdk-17.0.9.0.3
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "5.4.17-2136.308.9.el8uek.x86_64", arch: "amd64", family: "unix"

Maven設定のカスタマイズ

Mavenは、設定ファイルを使用して、お使いの環境で適切に動作するようにMavenをカスタマイズします。通常は、次の状況でsettings.xmlファイルを作成します。
  • インターネットへの接続にプロキシ・サーバーを使用する必要がある。
  • 組織で、内部のMavenリポジトリ・マネージャを使用する必要がある。
  • 組織のMavenリポジトリ・マネージャにアーティファクトをデプロイする必要がある。

Mavenを初めて使用する場合、通常Maven設定ファイルはありません。Maven設定ファイルsettings.xmlは、通常はホーム・ディレクトリ内の.m2ディレクトリに保持されます。Mavenが他の場所を指し示すようにする場合は、Mavenマニュアルを参照してください。

次に、設定ファイルの例を示します。
<settings
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
  xmlns="http://maven.apache.org/SETTINGS/1.1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <servers>
    <server>
      <id>artifactory</id>
      <username>fred</username>
      <password>gV4akMViBM4vVWxG4F9GTu</password>
    </server>
  </servers>

  <proxies>
    <proxy>
      <id>myproxy</id>
      <protocol>http</protocol>
      <host>myproxy.mycompany.com</host>
      <port>80</port>
      <nonProxyHosts>*.mycompany.com</nonProxyHosts>
      <active>true</active>
    </proxy>
  </proxies>

  <mirrors>
    <mirror>
      <id>repo1</id>
      <name>repo1</name>
      <url>https://artifactory.mycompany.com/artifactory/repo1</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>
この例では、使用する可能性がある3つの共通構成の設定を示しています。
  • Proxy: インターネット上のMavenリポジトリにアクセスするために必要なHTTPプロキシ・サーバーについて、Mavenと通信できます。
  • Servers: Mavenリポジトリの資格証明についてMavenと通信できるため、リポジトリにアクセスするたびにこれらを入力する必要がなくなります。
  • Mirrors: Mavenの中央リポジトリに対して直接アクセスを試みるかわりに、組織のMavenリポジトリ・マネージャをMavenの中央リポジトリのミラー(キャッシュ)として使用するようにMavenに通知します。

Maven設定ファイルは、このドキュメントの範囲を超える他の状況で使用できます。いくつかの構成はsettings.xmlまたはプロジェクトのpom.xmlファイルのいずれかに配置できますが、プロジェクト固有のすべての設定をpom.xmlに配置し、プロジェクト間構成の場合はsettings.xmlのままにすることをお薦めします。詳細は、https://maven.apache.org/settings.htmlを参照してください。

Mavenリポジトリへの移入

組織のMavenリポジトリ・マネージャを使用するか、$HOME/.m2/repositoryにデフォルトで配置されているローカルMavenリポジトリを使用するかに関係なく、Mavenを使用してFMWアプリケーションのビルドを試行する前に、Oracle FMWアーティファクトを移入する必要があります。

Oracleには、Oracle HomeからMavenリポジトリを移入できるOracle Maven同期プラグインが用意されています。Fusion Middleware製品をインストールする場合、Oracle Maven同期プラグインで検出できるように、Maven原型、プラグインおよびPOMが製品にインストールされます。

この項では、次の項目について説明します。

Maven同期プラグインの概要

Oracle Fusion Middlewareには、Oracle Maven同期プラグインが用意されており、これによってリポジトリの設定プロセスが簡略化され、特定の環境にインストールされるパッチを知る必要性が完全に排除されます。このプラグインを使用すると、指定のOracleホームからMavenリポジトリに移入できます。Oracleホームにパッチを適用した後、このプラグインを実行して、MavenリポジトリがOracleホームと一致するようにします。これにより、その特定の環境のすべてのアーティファクトについて、ビルドで正しいバージョンを使用していることが確実になります。

Oracle Maven同期プラグインは、Oracle WebLogic Server、Oracle CoherenceおよびOracle JDeveloperのインストールに含まれています。プラグインを使用するには、Oracleホームの場所とMavenリポジトリの場所を指定する必要があります。Mavenリポジトリは、ファイル・システムのパスまたはURLのいずれかを使用して指定できます。プラグインはOracleホーム内のすべてのMavenアーティファクトを調べて、すべてのアーティファクトが指定したMavenリポジトリにインストールされていること、およびバージョンが完全に一致していることを確認します。これは、バージョン番号とファイルがバイナリ・レベルで完全に同一であることを意味し、すべてのパッチ適用済ファイルがMavenリポジトリ内に正確に反映されます。

Oracleホームにはplugins/mavenディレクトリがあり、ここには様々なビルド操作を実行するための、Oracle提供アーティファクト用のMaven POM、プロジェクトを作成するための原型、およびOracle提供のMavenプラグインが含まれています。

Oracle Maven同期プラグインのインストール

Oracle Maven同期プラグインの使用を開始する前に、これをMavenリポジトリにインストールする必要があります。コンピュータ上のローカル・リポジトリにインストールするか、共有内部リポジトリがある場合は、組織のMavenリポジトリ・マネージャにデプロイします。

プラグインはOracle WebLogic Serverホームにあり、2つのファイルで構成されています。
  • プラグインについて記述するMavenプロジェクト・オブジェクト・モデル(POM)ファイル。次の場所にあります。
    ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/14.1.2/oracle-maven-sync-14.1.2.pom
  • プラグインを含むJARファイル。次の場所にあります。
    ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/14.1.2/oracle-maven-sync-14.1.2.jar
プラグインをインストールおよびデプロイします。
  1. ローカルMavenリポジトリにプラグインをインストールするには、ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/14.1.2ディレクトリから次のコマンドを実行します。
    mvn install:install-file -DpomFile=oracle-maven-sync-14.1.2.pom -Dfile=oracle-maven-sync-14.1.2.jar
  2. プラグインをデプロイするには、次の方法のいずれかを使用します。
    • 共有内部リポジトリにプラグインをデプロイする最も簡単な方法として、Mavenリポジトリ・マネージャによって提供されるWebユーザー・インタフェースを使用して、リポジトリにJARおよびPOMファイルをアップロードします。

    • 代替方法としては、デプロイ・プラグインを使用しますが、これは、ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/14.1.2ディレクトリから次のようなコマンドを使用することで実行できます。

      mvn deploy:deploy-file -DpomFile=oracle-maven-sync-14.1.2.pom -Dfile=oraclemaven-sync-14.1.2.jar -Durl=http://servername/artifactory/repositories/internal -DrepositoryId=internal

      デプロイ・プラグインを使用するには、Mavenのsettings.xmlファイルでリポジトリを定義し、さらに匿名の公開が許可されていない場合には、資格証明を定義する必要があります。このコマンドの詳細は、Mavenのドキュメント(http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html)を参照してください。

使用する際に完全座標を指定しなくて済むようにOracle Maven Synchronizationプラグインに短い名前を使用するには、Mavenのsettings.xmlに次のようにエントリを追加します。
<pluginGroups>
    <pluginGroup>com.oracle.maven</pluginGroup>
</pluginGroups>

これにより、oracle-syncという名前を使用してプラグインを参照できます。

Oracle Maven同期プラグインの実行

Oracle Maven同期プラグインは、リポジトリに移入するために使用する単一pushゴールをサポートします。

使用方法およびパラメータの説明を取得するには、次のコマンドを実行してhelp:describeゴールを呼び出します。
mvn help:describe -Dplugin=com.oracle.maven:oracle-maven-sync -Ddetail

この出力には、プラグインのpushゴールで使用可能なパラメータが示されています。表1-1に、パラメータを示します。

表1-1 pushゴールのパラメータと説明

パラメータ 説明

dryRun

プラグインでリポジトリへのアーティファクトの公開を試行するかどうかを制御するパラメータ。

これをtrueに設定すると、pushゴールによってすべてのPOMファイルが検索され、falseに設定されている場合に実行される内容の詳細が出力されます。ただし、アーティファクトは公開されず、システムも変更されません。

failOnError

このプロパティをfalseに設定すると、プラグインで1つのリソースの処理に失敗しても、それ以外のすべてのリソースの処理が続行されます。失敗は警告としてログに記録されますが、処理は正常に完了します。

このプロパティをtrueに設定すると、最初の問題が発生するとすぐにプラグインがエラーで終了します。これはデフォルトです。

oracleHome

Mavenリポジトリへの移入元にするOracleホームへのパス。

overwriteParent

このプロパティをtrueに設定すると、oracle-commonの祖先がターゲット・リポジトリに存在していれば、プラグインはoracle-commonの祖先でPOMアーティファクトを上書きします。デフォルト値のfalseはカスタマイズPOMコンテンツが自動的に上書きされることを防ぎます。プラグイン実行中にそのようなPOMに遭遇した場合、failOnErrorフラグ値に応じてエラーが発生し処理されます。変更を持ち越すには、既存のPOMを保存し、overwriteParent=trueでpushゴールを実行して、新しくプッシュされたPOMに手動で変更を転送します。

pushDuplicates

このプロパティをtrueに設定すると、プラグインは重複した場所をすべてプッシュします。つまり、別々のMaven座標(GAV)を持つ複数のPOMが同じ場所のパスに割り当てられている場合、プラグインはそれらすべてを宛先リポジトリにプッシュします。

retryFailedDeploymentCount

失敗したデプロイメントが中断および失敗する前に再試行される回数を制御するために使用するパラメータ。0から10の範囲外の値を指定した場合、0から10の範囲内の最も近い値にプルされます。0に設定すると、再試行はありません。

リモート・サーバーにデプロイされるアーティファクトにPOMとバイナリ・ファイルの両方がある場合、POMのデプロイとバイナリ・ファイルのデプロイの間に再試行回数がリセットされます。

ローカル・リポジトリにプッシュするとき、このパラメータは無視されます。

serverId

Mavenのsettings.xmlファイルに含まれるサーバー・エントリのID。これは、リモート・リポジトリにデプロイする場合にのみ必要です。settings.xmlファイルは、URL、ユーザー名、パスワードなどのリモート・アーティファクト・リポジトリのデプロイメント情報を提供する必要があります。

アーティファクトの置換

一部のMavenリポジトリ・マネージャには、リポジトリ内の既存アーティファクトの置換を可能にするかどうかを制御する設定があります。Mavenリポジトリ・マネージャにこのような設定がある場合は、Oracle Maven同期プラグインでリポジトリ内のアーティファクトを更新できるように、正しく設定されていることを確認する必要があります。この設定を変更する方法については、Mavenリポジトリ・マネージャのドキュメントを参照してください。

Mavenリポジトリへの移入

リポジトリに移入するには、pushゴールを使用する必要があります。表1-1に示すパラメータをコマンド行またはPOMファイルで指定します。

この項では、次の項目について説明します。

pushゴールの実行について
pushゴールを実行すると、次の処理が行われます。
  • 指定されたOracleホームを確認し、そのOracleホームに含まれるすべてのMavenアーティファクトの一覧を作成します。これは、ORACLE_HOME/oracle_common/plugins/maven依存性ディレクトリおよびそのサブディレクトリでPOMファイルを再帰的に検索し、ORACLE_HOMEに存在するPRODUCT_HOMEごとにORACLE_HOME/PRODUCT_HOME/plugins/mavenディレクトリおよびそのサブディレクトリで再帰的に検索することで実行します。
  • 各POMファイルで参照されているJARファイルがOracleホームで使用可能かどうかを確認します。
  • JARファイルのSHA1チェックサムを計算します。
  • 指定されたリポジトリに対するJARファイル、POMファイルおよびSHA1ファイルの公開を試行します。
次のタイプのMavenアーティファクトがリポジトリにインストールされます。
  • Oracleによって提供されている次のようなMavenの依存性
    • クライアントAPIクラス
    • wlstなどのコンパイル、パッケージ化およびデプロイメント・ユーティリティ
    • アプリケーションへの組込みが必要なコンポーネントJAR
    • t3およびJAX-WSクライアント・ランタイムなどのクライアント側のランタイム・クラス
  • コンパイル、パッケージ化およびデプロイメントを処理するOracle提供のMavenプラグイン
  • プロジェクト・テンプレートを提供するOracle提供のMaven原型
ローカル・リポジトリへの移入
ローカル・リポジトリに移入する場合は、コマンド行でoracleHomeを指定する必要があります。例:
mvn com.oracle.maven:oracle-maven-sync:push -DoracleHome=path_to_oracleHome

settings.xmlファイルのlocalRepository要素は、ローカルMavenリポジトリの場所を示します。settings.xmlからlocalRepository要素を取り除くと、デフォルトの場所は${HOME}/.m2/repositoryディレクトリ内になります。

localRepository値をオーバーライドする場合は、Mavenオプションとしてコマンドラインにオーバーライドの場所を指定する必要があります。例:
mvn com.oracle.maven:oracle-maven-sync:push
-DoracleHome=path_to_oracleHome -Dmaven.repo.local=alternate_path
POMファイルのパラメータを指定するには、次のようなプラグイン・エントリを追加する必要があります。
<plugin>
    <groupId>com.oracle.maven</groupId>
    <artifactId>oracle-maven-sync</artifactId>
    <version>14.1.2-0-0</version>
    <configuration>
        <oracleHome>path_to_oracleHome</oracleHome>
    </configuration>
</plugin>
プラグインを追加した後、次のコマンドでMavenを実行します。
mvn com.oracle.maven:oracle-maven-sync:push
リモート・リポジトリへの移入

リモート・リポジトリに移入する場合は、コマンドライン・インタフェースまたはプラグイン構成でserverIdおよびoracleHomeを指定する必要があります。また、プラグインに指定したserverIdと一致するようにsettings.xmlファイルのリポジトリ構成を指定する必要があります。デプロイメントに認証が必要な場合は、Mavenのsettings.xmlファイルにもserverエントリを追加する必要があります。

例:
mvn com.oracle.maven:oracle-maven-sync:push -DoracleHome=path_to_oracleHome -DserverId=internal
対応する認証詳細付きMaven settings.xmlファイルは、次のようになります。
...
<profiles>
  <profile>
    <id>default</id>
    <repositories>
      <repository>
        <id>internal</id>
        <name>Team Internal Repository</name>
        <url>http://some.host/maven/repo/internal</url>
        <layout>default</layout>
        <releases>
          <enabled>true</enabled>
          <updatePolicy>always</updatePolicy>
          <checksumPolicy>warn</checksumPolicy>
        </releases>
        <snapshots>
          <enabled>true</enabled>
          <updatePolicy>never</updatePolicy>
          <checksumPolicy>fail</checksumPolicy>
        </snapshots>
      </repository>
    </repositories>
  </profile>
</profiles>
...
<server>
  <id>internal</id>
  <username>username</username>
  <password>password</password>
</server>
...
<activeProfiles>
  <activeProfile>default</activeProfile>
</activeProfiles>

プロファイルにターゲット・リポジトリを定義し、前述の例に示すactiveProfilesタグを使用して、そのプロファイルをアクティブ化する必要があります。

注意:

serverセクションに、暗号化されたパスワードを指定する必要があります。サーバー・パスワードの暗号化方法の詳細は、https://maven.apache.org/guides/mini/guide-encryption.html#How_to_encrypt_server_passwordsを参照してください。

POMファイルのパラメータを指定するには、次のようなプラグイン・エントリを追加する必要があります。
<plugin>
  <groupId>com.oracle.maven</groupId>
  <artifactId>oracle-maven-sync</artifactId>
  <version>14.1.2-0-0</version>
  <configuration>
    <serverId>internal</serverId>
    <oracleHome>path_to_oracleHome</oracleHome>
  </configuration>
</plugin>
プラグインを追加した後、次のコマンドでMavenを実行します。
mvn com.oracle.maven:oracle-maven-sync:push

リポジトリに移入した後、リポジトリ・マネージャ上で索引の更新または原型カタログの更新などのいくつかの操作を実行することもできます。そのような操作が必要または推奨されているかを確認するには、リポジトリ・マネージャのドキュメントを参照してください。

既存Mavenリポジトリでのpushゴールの実行

すでにOracleアーティファクトが入っているMavenリポジトリに対してpushゴールを実行すると、Oracle Maven同期プラグインはリポジトリに既存の親POMがあることを検出します。独自の設定を追加するなど変更されている場合があるため、このような親POMは上書きされません。かわりに、警告メッセージが出力されます。親POMを上書きするには、pushゴールに追加パラメータ-DoverwriteParent=trueを指定する必要があります。

パッチ適用の予備知識

パッチ適用は、システムを軽微な変更で更新する操作で、通常はソフトウェアが本番環境に移された後に認識された不具合を修正します。Oracle Fusion Middlewareでは、OPatchユーティリティを使用して、Oracleホームにインストールされているソフトウェアへのパッチ適用を管理します。OPatchを使用してパッチを適用しても、インストールされているソフトウェアのバージョン番号は変更されません。

Mavenでは、リリース済のソフトウェアが変更されないことを前提としたパッチ適用に対し、様々なアプローチを使用します。パッチが必要な場合、新しいバージョン番号を持つ新しいバージョンのアーティファクトが作成され、パッチとして配布されます。

Mavenを使用してOracle Fusion Middleware環境でアプリケーションを開発する場合には、この違いによって問題が発生します。Oracle Fusion Middleware では、この問題に対応するためのメカニズムを提供しています。

パッチ適用に対するOracleのアプローチ

Oracle Fusion Middleware (14.1.1など)を本番環境にリリースした後で問題が見つかった場合、この問題を修正するための個別パッチが作成されます。たとえば、14.1.1と14.1.2などの2つのリリースの間にこれらのパッチが多くリリースされます。これらのパッチをすべて適用する、またはこれらのパッチのいずれも適用しないなど、多数のパッチの組合せを適用できます。

このアプローチにより、柔軟性がとても高まります。必要なパッチのみを適用して、他のパッチは無視することができます。ただし、Mavenを使用している場合には、問題が発生する可能性があります。ビルド・システムで使用しているアーティファクトのバージョンがターゲット環境で使用されているバージョンと正確に同じである(パッチ適用済の可能性もある)ことを確認してください。

テスト、QA、SIT、本番などの多数の環境が存在する場合には複雑さが増し、それぞれに異なるバージョン(またはパッチ)がインストールされる可能性があります。

このような状況では、ターゲットにする環境ごとに1つのMavenリポジトリを設定することをお薦めします。たとえば、Mavenテスト・リポジトリには、テスト環境にインストールされているバージョンおよびパッチと一致するアーティファクトを格納し、Maven QAリポジトリには、QA環境にインストールされているバージョンおよびパッチと一致するアーティファクトを格納するというように設定します。

パッチ適用後のOracle Maven同期プラグインのpushゴールの実行

Oracleホームにパッチを適用した後、このプラグインを実行して、MavenリポジトリがOracleホームと一致するようにします。これにより、その特定の環境のすべてのアーティファクトについて、ビルドで正しいバージョンを使用していることになります。Oracle Maven同期プラグインの実行を参照してください。

原型カタログに関する考慮事項

Oracle Maven同期プラグインのプッシュ・ゴールを実行することによって、Mavenリポジトリに新しいMaven原型がインストールされる場合があります。原型の索引を再ビルドするためにコマンドの実行が必要になることがあります。一部のMavenリポジトリ・マネージャではこれを自動的に行います。

ローカル原型カタログを再ビルドするには、次のようなコマンドを実行します。
mvn archetype:crawl -Dcatalog=$HOME/.m2/archetype-catalog.xml