Skip to content
This repository has been archived by the owner on Jan 29, 2021. It is now read-only.

Home

Jump to bottom
lmatyja edited this page Jun 23, 2017 · 10 revisions

Maven CRX Plugin 1.0.4

Introduction

This document describes a Maven plugin used for uploading, installing and replicating artifacts to a running CRX 2.1 or better based application (like Adobe CQ5) using official CRX API. Thanks to that feature, development process can be automated up to the deployment step of final application which makes developer's work more easy. The plugin is able to detect subtle errors (such as xml parsing exception) during package installation. It was tested with CQ 5.4 (CRX 2.2) and CQ 5.5 (CRX 2.3).

Maven CRX Plugin provides the following goals:

Goal Description
crx:upload Uploads a selected artifact to a running CRX instance
crx:install Installs previously uploaded artifact in a running CRX instance (invokes crx:upload goal before running itself)
crx:activate Activates (replicates and installs) previously uploaded artifact on all publish instances (requires CRX 2.3 / CQ 5.5)
crx:statusCheck Checks status of CRX Package Manager service

Installation

Plugin requires Maven 3.0.3 (or newer) to work (previous versions may work also, but they have not been tested).

Using Maven repository

Since version 1.0.2 Maven CRX Plugin is available in official remote Maven repository (http://search.maven.org/#search|ga|1|maven-crx-plugin). To start using it simply add proper configuration tag in your pom.xml. See usage section.

Manual installation

Also, you can always build it by yourself and deploy it to your local Maven repository. To do so simply:

Checkout the source code:

cd [folder of your choice]
git clone git://github.com/Cognifide/Maven-CRX-Plugin.git
cd Maven-CRX-Plugin

Compile and install (or deploy):

mvn clean package install

Provided that build succeeded, plugin is now available for your Maven projects.

Usage

To use the plugin, add the following definition to your parent pom.xml and/or in every submodule accordingly:

<build>
  <plugins>
    <!-- Configure Maven CRX Plugin in current POM -->
    <plugin>
      <groupId>com.cognifide.maven.plugins</groupId>
      <artifactId>maven-crx-plugin</artifactId>
      <version>1.0.4</version>
      <configuration>
        <skip>true</skip>      <!-- We may want to disable this plugin in parent POM -->
      </configuration>
    </plugin>
    (...)
  </plugins>
  <pluginManagement>
    <plugins>
      <!-- Configure Maven CRX Plugin in parent POM to take effect in submodules -->
      <plugin>
        <groupId>com.cognifide.maven.plugins</groupId>
        <artifactId>maven-crx-plugin</artifactId>
        <version>1.0.3</version>
        <configuration>        <!-- See 'Configuration' section below for more options -->
          <url>http://crx-machine:5402</url>
          <user>${crx.username}</user>
          <password>${crx.password}</password>
        </configuration>
      </plugin>
      (...)
    </plugins>
  </pluginManagement>
</build>

It is recommended that you extract the URL, user and password values into a separate properties and store them in the ~/.m2/settings.xml file - so that each developer can have independent configuration(s).

Configuration

Maven CRX Plugin can be configured using <configuration> element (see Usage sample above) with following tags:

Property Default Value Description
url http://localhost:5402 The URL of the running CRX instance.
user admin The user name to authenticate at the running CRX instance.
password admin The password to authenticate at the running CRX instance.
packageFileName ${project.build.directory}/${project.build.finalName}.zip Artifact file name to be uploaded and installed.
force true Forces plugin to upload the artifact even there is already one with the same name in CRX repository.
packageManagerSuffix /crx/packmgr/service An optional URL suffix which will be appended to the url for use as the real target URL of package manager. Current default value supports recent version of CRX API so there is no need to change it at the moment.
skip false Indicates whether to skip this step even though it has been configured in the project to be executed.
retryCount 1 Defines how many times CRX Package Manager service status will be checked.
waitingTime 2000 Defines interval between each CRX Package Manager service call.

Please note that it is always possible to override those parameters from command line by referencing a system property that user can provide using -D option. Every such a parameter should be proceed by a crx. prefix, i.e.: mvn ... crx:install -Dcrx.password=secure

If your Maven instance reports that No plugin found for prefix 'crx' you may need to add following elements to ~/.m2/settings.xml file:

<settings>
(...)
  <pluginGroups>
    <pluginGroup>com.cognifide.maven.plugins</pluginGroup>
  </pluginGroups>
</settings>

Goal: crx:upload

The upload goal simply uploads specified file to the running instance of CRX repository. In most cases it would be any artifact build by Maven in proceeding goal: a jar file or zip package. Proper file can be selected using <package.file> configuration element, i.e.: <packageFileName>${project.build.directory}/${project.build.finalName}.zip</packageFileName>.

Use

You can invoke upload goal by running following command:

mvn clean package assembly:single crx:upload

Goal: crx:install

The install goal sends request to running instance of CRX repository to install previously uploaded package. To be properly installed, this should be a valid CRX package. Please note that before running this goal, upload goal is always being invoked before to ensure that there is a proper package upoaded already.

Use

You can invoke install goal by running following command:

mvn clean package assembly:single crx:install

Goal: crx:activate

The activate goal sends request to running instance of CRX repository to replicate and install previously uploaded package on publish instances. Please note that before running this goal, upload and install goals are always invoked to ensure that there is already a proper package installed. The activate goal is only supported by CRX 2.3 (CQ 5.5).

Use

You can invoke activate goal by running following command:

mvn clean package assembly:single crx:activate

Goal: crx:statusCheck

The statusCheck goal sends request to running instance of CRX repository to check if CRX Package Manager service is running. This will allow to prevent situation when CRX package upload process failed because CRX Package Manager service is not available.

Use

You can invoke statusCheck goal by running following command:

mvn clean package assembly:single crx:statusCheck
Clone this wiki locally