Estructura del proyecto AEM

Este artículo describe los cambios necesarios para que los proyectos de Adobe Experience Manager Maven sean compatibles con AEM as a Cloud Service, asegurándose de que respetan la división del contenido mutable e inmutable. Además, las dependencias se establecen para crear implementaciones determinísticas y no conflictivas, y se empaquetan en una estructura implementable.

AEM AEM Las implementaciones de aplicaciones de la aplicación deben estar compuestas por un solo paquete de la aplicación A su vez, este paquete debe contener subpaquetes que incluyan todo lo necesario para que la aplicación funcione, incluido el código, la configuración y cualquier contenido de línea de base de soporte.

AEM La requiere una separación de content y code, lo que significa que un paquete de contenido único no puede implementarse en ambas /apps y áreas de tiempo de ejecución (por ejemplo, /content, /conf, /home o cualquier cosa que no sea /apps) del repositorio. En su lugar, la aplicación debe separar el código y el contenido en paquetes discretos para su implementación en AEM.

La estructura del paquete descrita en este documento es compatible tanto con las implementaciones de desarrollo local, como con las implementaciones de AEM Cloud Service.

Áreas mutables e inmutables del repositorio mutable-vs-immutable

AEM AEM Las áreas /apps y /libs de la se consideran inmutables porque no se pueden cambiar (crear, actualizar, eliminar) después de iniciarse la ejecución (es decir, durante el tiempo de ejecución). Cualquier intento de cambiar un área inmutable durante la ejecución falla.

Todo lo demás en el repositorio, /content, /conf, /var, /etc, /oak:index, /system, /tmp, etc., son áreas mutables, lo que significa que se pueden cambiar durante la ejecución.

Índices Oak oak-indexes

El proceso de implementación de AEM as a Cloud Service administra los índices Oak (/oak:index). El motivo es que Cloud Manager debe esperar hasta que se implemente cualquier nuevo índice y volver a indexar completamente antes de cambiar a la nueva imagen de código.

Por este motivo, aunque los índices Oak son mutables en tiempo de ejecución, deben implementarse como código para que se puedan instalar antes de instalar cualquier paquete mutable. Por lo tanto, las configuraciones de /oak:index forman parte del paquete de código y no del paquete de contenido como se describe a continuación.

Estructura del paquete recomendado recommended-package-structure

Este diagrama proporciona información general sobre la estructura del proyecto recomendada y los artefactos de implementación de paquetes.

La estructura de implementación de la aplicación recomendada es la siguiente:

Paquetes de código/paquetes OSGi

Paquetes de contenido

Paquetes de contenedor

Paquetes de aplicaciones adicionales extra-application-packages

AEM AEM Si la implementación utiliza otros proyectos de, que a su vez constan de sus propios paquetes de contenido y código, los paquetes de contenedor deben incrustarse en el paquete all del proyecto.

AEM AEM Por ejemplo, un proyecto de que incluya dos aplicaciones de proveedor puede tener un aspecto similar al siguiente:

Tipos de paquetes package-types

Los paquetes deben marcarse con el tipo de paquete declarado. Los tipos de paquete ayudan a aclarar el propósito y la implementación de un paquete.

Para obtener más información, consulte Documentación del complemento Apache Jackrabbit FileVault - Package Maven, Tipos de paquetes Apache Jackrabbit y el fragmento de configuración de FileVault Maven a continuación.

Marcado de paquetes para su implementación mediante Adobe Cloud Manager marking-packages-for-deployment-by-adoube-cloud-manager

De forma predeterminada, Adobe Cloud Manager obtiene todos los paquetes producidos por la compilación de Maven. Sin embargo, dado que el paquete de contenedor (all) es el único artefacto de implementación que contiene todos los paquetes de contenido y código, debe asegurarse de que solo el paquete de contenedor (all) esté implementado. Para garantizar esto, otros paquetes que genera la compilación de Maven deben marcarse con la configuración del complemento Maven del paquete de contenido de FileVault <properties><cloudManagerTarget>none</cloudManageTarget></properties>.

Inicio de repo repo-init

Repo Init proporciona instrucciones, o scripts, que definen estructuras JCR, que van desde estructuras de nodos comunes como árboles de carpetas, hasta usuarios, usuarios de servicio, grupos y definición de ACL.

Las ventajas clave de Repo Init son que tienen permisos implícitos para realizar todas las acciones definidas por sus scripts. Además, estos scripts se invocan al principio del ciclo vital de la implementación, lo que garantiza que todas las estructuras JCR necesarias existan antes de que se ejecute el código.

Aunque los scripts de inicio de repo se ejecutan en el proyecto ui.config como scripts, se pueden y deben usar para definir las siguientes estructuras mutables:

Los scripts de inicio de repo se almacenan como scripts entradas de RepositoryInitializer configuraciones de fábrica de OSGi. AEM AEM De este modo, se pueden dirigir implícitamente al modo de ejecución, lo que permite diferencias entre los scripts de inicio de repo de Author y los de Publish Services, o incluso entre entornos (Dev, Stage y Prod).

Las configuraciones OSGi de inicio de repositorio se escriben mejor en el formato de configuración OSGi .config, ya que admiten varias líneas, lo que es una excepción a las prácticas recomendadas de usar .cfg.json para definir las configuraciones OSGi.

Al definir Usuarios y Grupos, solo los grupos se consideran parte de la aplicación y parte integral de su función. AEM Aún puede definir Usuarios y grupos de organización durante la ejecución de la aplicación de en el tiempo de ejecución de la. AEM Por ejemplo, si un flujo de trabajo personalizado asigna trabajo a un grupo con nombre, defina ese grupo mediante Repo Init en la aplicación de la. AEM Sin embargo, si la Agrupación es meramente organizativa, como "Equipo de Wendy" y "Equipo de Sean", estos grupos se definen y administran mejor durante la ejecución en el tiempo de ejecución de la.

El vocabulario completo para los scripts de inicio de repo está disponible en la documentación de inicio de repo de Apache Sling.

Paquete de estructura de repositorio repository-structure-package

Los paquetes de código requieren configurar la configuración del complemento FileVault Maven para hacer referencia a un <repositoryStructurePackage> que exige la corrección de las dependencias estructurales (para garantizar que un paquete de código no se instale sobre otro). Puede crear su propio paquete de estructura de repositorio para su proyecto.

Solo se requiere para los paquetes de código, es decir, cualquier paquete marcado con <packageType>application</packageType>.

Para aprender a crear un paquete de estructura de repositorio para su aplicación, vea Desarrollar un paquete de estructura de repositorio.

Los paquetes de contenido (<packageType>content</packageType>) no requieren este paquete de estructura de repositorio.

Incrustación de subpaquetes en el paquete de contenedor embeddeds

AEM AEM Los paquetes de contenido o código se colocan en una carpeta "side-car" especial y se pueden dirigir para su instalación en las versiones de autor, publicación o ambas, utilizando la configuración <embeddeds> del complemento Maven de FileVault. No utilice la configuración <subPackages>.

Los casos de uso comunes incluyen:

AEM AEM Para segmentar a los autores de la, a los editores de la publicación o a ambos, el paquete está incrustado en el paquete contenedor de all en una ubicación de carpeta especial, con el siguiente formato:

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

Desglose de esta estructura de carpetas:

AEM Por ejemplo, una implementación que contenga paquetes específicos de autor y publicación de la aplicación puede tener el siguiente aspecto:

Definición del filtro del paquete del contenedor container-package-filter-definition

Debido a la incrustación de los subpaquetes de código y contenido en el paquete contenedor, las rutas de destino incrustadas deben agregarse a filter.xml del proyecto contenedor. Al hacerlo, se garantiza que los paquetes incrustados se incluyan en el paquete contenedor cuando se creen.

Simplemente agregue las <filter root="/apps/<my-app>-packages"/> entradas para cualquier carpeta de segundo nivel que contenga subpaquetes para implementar.

Incrustación de paquetes de terceros embedding-3rd-party-packages

Todos los paquetes deben estar disponibles a través del repositorio público de artefactos Maven del Adobe o un repositorio de artefactos Maven público y referenciable de terceros al que se pueda acceder.

Si los paquetes de terceros están en el repositorio público de artefactos Maven de Adobe, no se necesita ninguna configuración adicional para que Cloud Manager de Adobe resuelva los artefactos.

Si los paquetes de terceros están en un repositorio público de artefactos Maven de terceros, este repositorio debe estar registrado en el pom.xml del proyecto e incrustado según el método descrito anteriormente.

Los conectores/aplicaciones de terceros deben incrustarse usando su paquete all como contenedor en el paquete de contenedor (all) de su proyecto.

La adición de dependencias Maven sigue las prácticas estándar de Maven y la incrustación de artefactos de terceros (paquetes de contenido y código) se ha descrito anteriormente.

Dependencias de paquete entre ui.apps de ui.content paquetes package-dependencies

Para garantizar la correcta instalación de los paquetes, se recomienda establecer dependencias entre paquetes.

La regla general es que los paquetes que contienen contenido mutable (ui.content) deben depender del código inmutable (ui.apps) que admite la representación y el uso del contenido mutable.

Una excepción notable a esta regla general es si el paquete de código inmutable (ui.apps o cualquier otro), solo contiene paquetes OSGi. AEM Si es así, ningún paquete de debe declarar una dependencia en él. AEM El motivo es que los paquetes de código inmutable que solo contienen paquetes OSGi, no están registrados con Administrador de paquetes y no se han registrado con el paquete OSGi. AEM Por lo tanto, cualquier paquete de que dependa de él tiene una dependencia no satisfecha y no se puede instalar.

Los patrones comunes para las dependencias de paquetes de contenido son:

Dependencias del paquete de implementación simple simple-deployment-package-dependencies

El caso simple establece el paquete de contenido mutable ui.content para que dependa del paquete de código inmutable ui.apps.

Dependencias del paquete de implementación compleja complex-deploxment-package-dependencies

Las implementaciones complejas amplían el caso simple y establecen dependencias entre el contenido mutable correspondiente y los paquetes de código inmutable. Según sea necesario, también se pueden establecer dependencias entre paquetes de código inmutable.

Desarrollo e implementación locales local-development-and-deployment

AEM Las estructuras y la organización del proyecto descritas en este artículo son totalmente compatibles instancias de desarrollo local de la aplicación de desarrollo de.

Fragmentos XML de POM pom-xml-snippets

Los siguientes son fragmentos de configuración de Maven pom.xml que se pueden agregar a proyectos Maven para alinearlos con las recomendaciones anteriores.

Tipos de paquetes xml-package-types

Los paquetes de código y contenido, que se implementan como subpaquetes, deben declarar un tipo de paquete de application o content, según lo que contengan.

Tipos de paquetes de contenedores container-package-types

El contenedor all/pom.xml del proyecto no declara un <packageType>.

Tipos de paquetes de código (inmutables) immutable-package-types

Los paquetes de código deben establecer su packageType en application.

En ui.apps/pom.xml, las directivas de configuración de compilación de <packageType>application</packageType> de la declaración del complemento filevault-package-maven-plugin declaran su tipo de paquete.

...
<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>
    ...

Tipos de paquetes de contenido (mutable) mutable-package-types

Los paquetes de contenido deben establecer su packageType en content.

En ui.content/pom.xml, la directiva de configuración de compilación <packageType>content</packageType> de la declaración del complemento filevault-package-maven-plugin declara su tipo de paquete.

...
<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>
    ...

Marcado de paquetes para la implementación de Adobe Cloud Manager cloud-manager-target

En todos los proyectos que generan un paquete, excepto en el proyecto de contenedor (all), agregue <cloudManagerTarget>none</cloudManagerTarget> a la configuración de la declaración del complemento <properties> para garantizar filevault-package-maven-plugin que Adobe Cloud Manager no los implementa. El paquete de contenedor (all) debe ser el paquete singular implementado mediante Cloud Manager, que a su vez incorpora todos los paquetes de contenido y código necesarios.

...
<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>
    ...

Inicio de repo snippet-repo-init

Los scripts de inicio de repo que contienen los scripts de inicio de repo se definen en la configuración de fábrica de OSGi RepositoryInitializer mediante la propiedad scripts. Debido a que estos scripts se definen en configuraciones de OSGi, se pueden definir fácilmente mediante el modo de ejecución utilizando la semántica de carpeta habitual ../config.<runmode>.

Dado que los scripts suelen ser declaraciones multilínea, es más fácil definirlos en el archivo .config que en el formato .cfg.json basado en JSON.

/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
"]

La propiedad OSGi scripts contiene directivas tal como se definen en el idioma de inicialización de repositorio de Apache Sling.

Paquete de estructura de repositorio xml-repository-structure-package

En ui.apps/pom.xml y en cualquier otro pom.xml que declare un paquete de código (<packageType>application</packageType>), agregue la siguiente configuración de paquete de estructura de repositorio al complemento Maven de FileVault. Puede crear su propio paquete de estructura de repositorio para su proyecto.

...
<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>
    ...

Incrustación de subpaquetes en el paquete de contenedor xml-embeddeds

En all/pom.xml, agregue las siguientes directivas <embeddeds> a la declaración del complemento filevault-package-maven-plugin. Recuerde, no utiliza la configuración <subPackages>. El motivo es que incluye los subpaquetes de /etc/packages en lugar de /apps/my-app-packages/<application|content|container>/install(.author|.publish)?.

...
<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>
...

Definición del filtro del paquete del contenedor xml-container-package-filters

En filter.xml (all/src/main/content/jcr_root/META-INF/vault/definition/filter.xml) del proyecto all, incluya cualquier carpeta -packages que contenga subpaquetes para implementar:

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

Si se usan varios /apps/*-packages en los destinos incrustados, entonces todos deben enumerarse aquí.

Repositorios de Maven de terceros xml-3rd-party-maven-repositories

En pom.xml del proyecto del reactor, agregue cualquier directiva pública de repositorio de Maven necesaria. La configuración completa de <repository> debe estar disponible en el proveedor de repositorios de terceros.

<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>

Dependencias de paquete entre ui.apps de ui.content paquetes xml-package-dependencies

En ui.content/pom.xml, agregue las siguientes directivas <dependencies> a la declaración del complemento 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>
...

Limpiar la carpeta de destino del proyecto de contenedor xml-clean-container-package

En all/pom.xml, agregue el complemento maven-clean-plugin que limpia el directorio de destino antes de una compilación de Maven.

<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>

Recursos adicionales additional-resources