AEM プロジェクトの構造

この記事では、可変コンテンツおよび不変コンテンツの分割に従って AEM as a Cloud Service との互換性を保つために Adobe Experience Manager Maven プロジェクトに必要な変更点について説明します。また、依存関係は、競合しない決定論的デプロイメントを作成するために確立され、デプロイ可能な構造でパッケージ化されます。

AEM アプリケーションのデプロイメントは、単一の AEM パッケージで構成する必要があります。このパッケージには、コード、設定、補助的なベースラインコンテンツなど、アプリケーションが機能するのに必要なあらゆるもので構成されるサブパッケージが含まれている必要があります。

AEM では、コンテンツ ​と​ コード ​を分離する必要があります。つまり、単一のコンテンツパッケージを​ 両方/appsおよびランタイム書き込み可能な領域（たとえば、/content、/conf、/home、または /apps 以外の任意のもの）にデプロイすることは​ できません。代わりに、アプリケーションを AEM にデプロイするには、コードとコンテンツを別々のパッケージに分離する必要があります。

このドキュメントで概要を説明しているパッケージ構造は、ローカル開発デプロイメントと AEM as a Cloud Service デプロイメントの​ 両方 ​に対応しています。

リポジトリの可変領域と不変領域 mutable-vs-immutable

AEM の /apps 領域および /libs 領域は、不変 ​とみなされ、AEM の起動後（つまり実行時）に変更（作成、更新、削除）はできません。実行時に不変領域を変更しようとすると失敗します。

リポジトリ内のその他すべて（/content、/conf、/var、/etc、/oak:index、/system、/tmp）はすべて​ 可変 ​領域です。つまり、実行時に変更できます。

Oak インデックス oak-indexes

Oak インデックス（/oak:index）は、AEM as a Cloud Service のデプロイメントプロセスによって管理されます。これは、新しいインデックスが展開されて完全にインデックスが再作成されるまで、Cloud Manager は新しいコードイメージに切り替わる前に待機する必要があるからです。

このため、Oak インデックスは実行時に可変ですが、可変パッケージがインストールされる前にインストールできるように、コードとしてデプロイする必要があります。したがって、/oak:index 設定はコードパッケージの一部であり、以下に説明するコンテンツパッケージの一部ではありません。

推奨されるパッケージ構造 recommended-package-structure

この図は、推奨されるプロジェクト構造とパッケージデプロイメントアーティファクトの概要を示しています。

推奨されるアプリケーションデプロイメント構造は次のとおりです。

コードパッケージ／OSGi バンドル

コンテンツパッケージ

コンテナパッケージ

追加のアプリケーションパッケージ extra-application-packages

独自のコードとコンテンツパッケージで構成される他の AEM プロジェクトを AEM のデプロイメントで使用する場合は、そのコンテナパッケージをプロジェクトの all パッケージに埋め込む必要があります。

例えば、2 つのベンダーの AEM アプリケーションを含む AEM プロジェクトは、次のようになります。

パッケージタイプ package-types

パッケージは、宣言済みのパッケージタイプでマークされる必要があります。パッケージタイプは、パッケージの目的とデプロイメントを明確にするのに役立ちます。

詳しくは、Apache Jackrabbit FileVault - Package Maven プラグインのドキュメント、Apache Jackrabbit パッケージタイプ、以下の FileVault Maven 設定スニペット を参照してください。

Adobe Cloud Manager によるデプロイメント用のパッケージのマーク marking-packages-for-deployment-by-adoube-cloud-manager

デフォルトでは、Adobe Cloud Manager は Maven ビルドで生成されたすべてのパッケージを組み込みます。ただし、コンテナ（all）パッケージはすべてのコードパッケージおよびコンテンツパッケージを含んだ単一のデプロイメントアーティファクトなので、必ず、コンテナ（all）パッケージ​ のみ ​をデプロイします。これを確実に行うには、Maven ビルドで生成される他のパッケージを、<properties><cloudManagerTarget>none</cloudManageTarget></properties> という FileVault コンテンツパッケージ Maven プラグイン設定でマークする必要があります。

Repo Init repo-init

Repo Init は、フォルダーツリーなどの一般的なノード構造から、ユーザー、サービスユーザー、グループ、ACL 定義まで、JCR 構造を定義する手順（スクリプト）を提供します。

Repo Init の主なメリットは、スクリプトで定義されたすべてのアクションを実行する暗黙的な権限を持っていることです。また、このようなスクリプトはデプロイメントライフサイクルの初期段階で呼び出され、コードの実行時までにすべての必要な JCR 構造が確実に存在するようにします。

Repo Init スクリプト自体はスクリプトとして ui.config プロジェクト内に存在しますが、スクリプトは次の可変構造を定義するために使用でき、また使用する必要があります。

Repo Init スクリプトは、RepositoryInitializer OSGi ファクトリ設定の scripts エントリとして保存されます。したがって、実行モードで暗黙的にターゲットにされる可能性があり、AEM オーサーサービスと AEM パブリッシュサービスの Repo Init スクリプトの違い、または環境（開発、ステージング、実稼動）間での違いを許容します。

Repo Init OSGi の設定は、複数行をサポートするため .configOSGi 設定形式で書き込むのが最適です。これは、.cfg.jsonOSGi 設定の定義に使用するベストプラクティスの例外です。

ユーザーとグループを定義する場合、グループのみがアプリケーションの一部と見なされ、その機能に不可欠です。実行時に AEM で組織のユーザーとグループを引き続き定義します。例えば、カスタムワークフローが名前付きのグループに作業を割り当てる場合、AEM アプリケーションで Repo Init を使用してそのグループを定義します。ただし、グループ化が単に組織的なもの（「ウェンディのチーム」や「ショーンのチーム」など）の場合、実行時に AEM でこれらのグループが最も適切に定義され、管理されます。

Repo Init スクリプトの全語彙は、Apache Sling Repo Init ドキュメントで入手できます。

リポジトリー構造パッケージ repository-structure-package

コードパッケージでは、（あるコードパッケージが別のコードパッケージをオーバーライドしないように）正しい構造的依存関係を確保する <repositoryStructurePackage> を参照するように、FileVault Maven プラグインの設定を指定する必要があります。プロジェクト用に独自のリポジトリー構造パッケージを作成することができます。

コードパッケージ（<packageType>application</packageType> でマークされた任意のパッケージ）に​ のみ必要 ​です。

アプリケーション用のリポジトリー構造パッケージの作成方法については、リポジトリー構造パッケージの作成を参照してください。

なお、コンテンツパッケージ（<packageType>content</packageType>）には、このリポジトリ構造パッケージは必要​ ありません。

コンテナパッケージへのサブパッケージの埋め込み embeddeds

コンテンツパッケージまたはコードパッケージは、特別な「サイドカー」フォルダーに格納され、FileVault Maven プラグインの <embeddeds> 設定を使用して、AEM オーサーと AEM パブリッシュのどちらか一方または両方へのインストールの対象とすることができます。<subPackages> 設定は使用しないでください。

一般的な使用例は次のとおりです。

AEM オーサー、AEM パブリッシュまたはその両方をターゲットにするには、パッケージを次の形式で all コンテナパッケージ内の特別なフォルダー位置に埋め込みます。

/apps/<app-name>-packages/(content|application|container)/install(.author|.publish)?

このフォルダー構造の詳細は、次の通りです。

例えば、AEM オーサーおよびパブリッシュに固有のパッケージを含んだデプロイメントは、次のようになります。

コンテナパッケージのフィルター定義 container-package-filter-definition

コンテナパッケージにコードサブパッケージおよびコンテンツサブパッケージが埋め込まれるので、埋め込まれたターゲットパスをコンテナプロジェクトの filter.xml に追加する必要があります。これにより、組み込みパッケージがビルド時にコンテナパッケージに確実に含まれるようになります。

デプロイするサブパッケージを格納した第 2 レベルのフォルダーに対応する <filter root="/apps/<my-app>-packages"/> エントリを追加するだけです。

サードパーティパッケージの埋め込み embedding-3rd-party-packages

すべてのパッケージは、アドビのパブリック Maven アーティファクトリポジトリまたはアクセス可能で参照可能なサードパーティのパブリック Maven アーティファクトリポジトリを通じて必ず入手できます。

サードパーティパッケージが​ アドビのパブリック Maven アーティファクトリポジトリ ​にある場合は、それ以上の設定を行わなくても、Adobe Cloud Manager でアーティファクトを解決できます。

サードパーティパッケージが​ サードパーティのパブリック Maven アーティファクトリポジトリ ​にある場合は、このリポジトリをプロジェクトの pom.xml に登録し、上記の方法に従って埋め込む必要があります。

サードパーティのアプリケーション／コネクタは、その all パッケージをプロジェクトのコンテナ（all）パッケージのコンテナとして使用して埋め込む必要があります。

Maven の依存関係を追加する場合は、Maven の標準的な手法に従います。サードパーティアーティファクト（コードパッケージとコンテンツパッケージ）の埋め込みについては、上記のとおりです。

ui.apps パッケージと ui.content パッケージの依存関係 package-dependencies

パッケージの適切なインストールを確実に行うために、パッケージ間の依存関係を設定することをお勧めします。

一般的なルールとしては、可変コンテンツを格納したパッケージ（ui.content）は、可変コンテンツのレンダリングと使用をサポートする不変コード（ui.apps）に依存します。

この一般的なルールの例外として重要なのは、不変コードパッケージ（ui.apps など）に OSGi バンドル​ のみ ​含まれている場合です。この場合、AEM パッケージでは不変コードパッケージへの依存関係を宣言する必要はありません。その理由は、OSGi バンドル​ のみ ​が含まれる不変コードパッケージが、AEM パッケージマネージャーに登録されていないからです。そのため、依存する AEM パッケージは、依存関係が満たされず、インストールに失敗します。

コンテンツパッケージの依存関係の一般的なパターンは以下のとおりです。

デプロイメントパッケージ間のシンプルな依存関係 simple-deployment-package-dependencies

シンプルな依存関係は、可変コンテンツパッケージ ui.content が不変コードパッケージ ui.apps に依存するように設定する場合です。

デプロイメントパッケージ間の複雑な依存関係 complex-deploxment-package-dependencies

複雑なデプロイメントは、シンプルなケースをさらに拡張したもので、対応する可変コンテンツパッケージと不変コードパッケージの間に依存関係を設定します。必要に応じて、不変コードパッケージ間にも依存関係を設定できます。

ローカル開発とデプロイメント local-development-and-deployment

この記事で概要を説明しているプロジェクト構造および編成は、ローカル開発 AEM インスタンスに​ 完全に対応 ​しています。

POM XML スニペット pom-xml-snippets

上記のレコメンデーションに合わせて Maven プロジェクトに追加できる Maven pom.xml 設定スニペットを以下に示します。

パッケージタイプ xml-package-types

サブパッケージとしてデプロイされるコードパッケージとコンテンツパッケージでは、パッケージに含まれる内容に応じて、アプリケーション ​か​ コンテンツ ​のパッケージタイプを宣言する必要があります。

コンテナパッケージタイプ container-package-types

コンテナ all/pom.xml プロジェクトでは <packageType> を宣言​ しません。

コード（不変）パッケージタイプ immutable-package-types

コードパッケージでは、packageType を application に設定する必要があります。

ui.apps/pom.xml では、プラグイン宣言 filevault-package-maven-plugin のビルド設定ディレクティブ <packageType>application</packageType> でパッケージタイプを宣言します。

...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.jackrabbit</groupId>
      <artifactId>filevault-package-maven-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        <group>${project.groupId}</group>
        <name>my-app.ui.apps</name>
        <packageType>application</packageType>
        <accessControlHandling>merge</accessControlHandling>
        <properties>
          <cloudManagerTarget>none</cloudManagerTarget>
        </properties>
      </configuration>
    </plugin>
    ...

コンテンツ（可変）パッケージタイプ mutable-package-types

コンテンツパッケージでは、packageType を content に設定する必要があります。

ui.content/pom.xml では、プラグイン宣言 filevault-package-maven-plugin のビルド設定ディレクティブ <packageType>content</packageType> でパッケージタイプを宣言します。

...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.jackrabbit</groupId>
      <artifactId>filevault-package-maven-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        <group>${project.groupId}</group>
        <name>my-app.ui.content</name>
        <packageType>content</packageType>
        <accessControlHandling>merge</accessControlHandling>
        <properties>
          <cloudManagerTarget>none</cloudManagerTarget>
        </properties>
      </configuration>
    </plugin>
    ...

Adobe Cloud Manager によるデプロイメント用のパッケージのマーク cloud-manager-target

コンテナ（all）プロジェクトを​ 除き、パッケージを生成するすべてのプロジェクトでは、プラグイン宣言 filevault-package-maven-plugin の <properties> 設定に <cloudManagerTarget>none</cloudManagerTarget> を追加して、プロジェクトが Adobe Cloud Manager でデプロイ​ されない ​ようにします。コンテナ（all）パッケージは、Cloud Manager を通じてデプロイされる単一のパッケージでなければなりません。このパッケージに、必要なすべてのコードパッケージとコンテンツパッケージが埋め込まれます。

...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.jackrabbit</groupId>
      <artifactId>filevault-package-maven-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        ...
        <properties>
          <cloudManagerTarget>none</cloudManagerTarget>
        </properties>
      </configuration>
    </plugin>
    ...

Repo Init snippet-repo-init

Repo Init スクリプトを含む Repo Init スクリプトは、scripts プロパティを介して RepositoryInitializer OSGi ファクトリ設定で定義されます。OSGi 設定内で定義されるこれらのスクリプトは、通常の ../config.<runmode> フォルダーセマンティクスを使用して、実行モードで簡単に範囲指定できます。

スクリプトは通常だと複数行の宣言なので、JSON ベースの .cfg.json 形式よりも .config ファイルで定義するほうが簡単です。

/apps/my-app/config.author/org.apache.sling.jcr.repoinit.RepositoryInitializer-author.config

scripts=["
    create service user my-data-reader-service

    set ACL on /var/my-data
        allow jcr:read for my-data-reader-service
    end

    create path (sling:Folder) /conf/my-app/settings
"]

scripts OSGi プロパティには、Apache Sling の Repo Init 言語で定義されたディレクティブが含まれます。

リポジトリー構造パッケージ xml-repository-structure-package

ui.apps/pom.xml と、コードパッケージ（<packageType>application</packageType>）を宣言する他の任意の pom.xml で、次のリポジトリー構造パッケージ設定を FileVault Maven プラグインに追加します。プロジェクト用に独自のリポジトリー構造パッケージを作成することができます。

...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.jackrabbit</groupId>
      <artifactId>filevault-package-maven-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        ...
        <repositoryStructurePackages>
          <repositoryStructurePackage>
              <groupId>${project.groupId}</groupId>
              <artifactId>ui.apps.structure</artifactId>
              <version>${project.version}</version>
          </repositoryStructurePackage>
        </repositoryStructurePackages>
      </configuration>
    </plugin>
    ...

コンテナパッケージへのサブパッケージの埋め込み xml-embeddeds

all/pom.xml で、次の <embeddeds> ディレクティブをプラグイン宣言 filevault-package-maven-plugin に追加します。繰り返しになりますが、<subPackages> 設定を使用​ しないでください。その理由は、/apps/my-app-packages/<application|content|container>/install(.author|.publish)? ではなく /etc/packages のサブパッケージが含まれているからです。

...
<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>
      ...
      <embeddeds>

          <!-- Include the application's ui.apps and ui.content packages -->
          <!-- Ensure the artifactIds are correct -->

          <!-- OSGi Bundle Jar file that deploys to BOTH AEM Author and AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.core</artifactId>
              <type>jar</type>
              <target>/apps/my-app-packages/application/install</target>
          </embedded>

          <!-- Code package that deploys to BOTH AEM Author and AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.apps</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/application/install</target>
          </embedded>

           <!-- OSGi configuration code package that deploys to BOTH AEM Author and AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.config</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/application/install</target>
          </embedded>

          <!-- Code package that deploys ONLY to AEM Author -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.apps.author</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/application/install.author</target>
          </embedded>

          <!-- Content package that deploys to BOTH AEM Author and AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.content</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/content/install</target>
          </embedded>

          <!-- Content package that deploys ONLY to AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.content.publish-only</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/content/install.publish</target>
          </embedded>

          <!-- Include any other extra packages  -->
          <embedded>
              <groupId>com.vendor.x</groupId>
              <artifactId>vendor.plug-in.all</artifactId>
              <type>zip</type>
              <target>/apps/vendor-packages/container/install</target>
          </embedded>
      <embeddeds>
  </configuration>
</plugin>
...

コンテナパッケージのフィルター定義 xml-container-package-filters

all プロジェクトの filter.xml（all/src/main/content/jcr_root/META-INF/vault/definition/filter.xml）に、デプロイするサブパッケージを格納したすべての -packages フォルダーを​ 含めます。

<filter root="/apps/my-app-packages"/>

埋め込まれるターゲットで複数の /apps/*-packages が使用されている場合は、それらをすべてここに列挙する必要があります。

サードパーティ Maven リポジトリ xml-3rd-party-maven-repositories

サードパーティのパブリック Maven リポジトリで必要なものがあれば、それらのリポジトリディレクティブをリアクタープロジェクトの pom.xml に追加します。完全な <repository> 設定は、サードパーティリポジトリプロバイダーから入手できるはずです。

<repositories>
  ...
  <repository>
      <id>3rd-party-repository</id>
      <name>Public Third-Party Repository</name>
      <url>https://repo.3rdparty.example.com/...</url>
      <releases>
          <enabled>true</enabled>
          <updatePolicy>never</updatePolicy>
      </releases>
      <snapshots>
          <enabled>false</enabled>
      </snapshots>
  </repository>
  ...
</repositories>

ui.apps パッケージと ui.content パッケージの依存関係 xml-package-dependencies

ui.content/pom.xml で、次の <dependencies> ディレクティブをプラグイン宣言 filevault-package-maven-plugin に追加します。

...
<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>
      ...
      <dependencies>
        <!-- Declare the content package dependency in the ui.content/pom.xml on the ui.apps project -->
        <dependency>
            <groupId${project.groupId}</groupId>
            <artifactId>my-app.ui.apps</artifactId>
            <version>${project.version}</version>
        </dependency>
      </dependencies>
    ...
  </configuration>
</plugin>
...

コンテナプロジェクトのターゲットフォルダーのクリーンアップ xml-clean-container-package

all/pom.xml に、Maven のビルドの前にターゲットディレクトリをクリーンアップする maven-clean-plugin プラグインを追加します。

<plugins>
  ...
  <plugin>
    <artifactId>maven-clean-plugin</artifactId>
    <executions>
      <execution>
        <id>auto-clean</id>
        <!-- Run at the beginning of the build rather than the default, which is after the build is done -->
        <phase>initialize</phase>
        <goals>
          <goal>clean</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
  ...
</plugins>

その他のリソース additional-resources