This page last changed on Apr 20, 2011 by alitokmen.

Definition

Installs a container

Explanation

An Installer is meant to install a container on your local machine. There is currently only a single Installer implementation: ZipURLInstaller which downloads a zipped container distribution from a URL and which installs it (i.e. unpacks it) in a specified directory. This is useful if you wish to fully automate a container installation without having to ask the user to manually install a container on their machine.

Of course you don't have to use an Installer if you want to use a container already installed on your machine.

Difference between versions
The ZipURLInstaller has been changed between Cargo versions:
  • In Cargo version 1.1.0 and onwards, the ZipURLInstaller has two attributes:
    • downloadDir: Directory in which the container's distributable archive is downloaded. Defaults to ${java.io.tmpdir}/cargo/installs.
    • extractDir: Directory in which the container's distributable archive is extracted. Defaults to:
      • ${java.io.tmpdir}/cargo/installs on the Java API and ANT tasks
      • ${project.build.directory}/cargo/installs on the Maven2 plugin
  • In older versions, the ZipURLInstaller has only one attribute:
    • installDir: Directory in which the container's distributable archive is downloaded and extracted. Defaults to ${java.io.tmpdir}/cargo/installs.
       
      Similarly, the ZipURLInstaller constructor's parameters also reflect the same mechanism.

Example using the Java API

// As described above, Cargo versions older than 1.1.0 accept only installDir,
// you therefore need to replace the "target/downloads", "target/extracts" to,
// for example, "target/installs"
Installer installer = new ZipURLInstaller(
    "http://download.eclipse.org/jetty/7.2.2.v20101205/dist/jetty-distribution-7.2.2.v20101205.tar.gz",
    "target/downloads", "target/extracts");
installer.install();

InstalledLocalContainer container = new Jetty7xInstalledLocalContainer(
    new Jetty7xStandaloneConfiguration("target/jetty7x"));
container.setHome(installer.getHome());
[...]

Example using the Ant API

<!--
  Careful: As described above, Cargo versions older than 1.1.0 accept only installDir,
  you therefore need to set installDir instead of downloadDir and extractDir.
  -->
<cargo containerId="jetty7x" [...]>
  <zipUrlInstaller
      installUrl="http://download.eclipse.org/jetty/7.2.2.v20101205/dist/jetty-distribution-7.2.2.v20101205.tar.gz",
      downloadDir="target/downloads"
      extractDir="target/extracts"/>
  [...]
</cargo>

Example using the Maven2 plugin

  <plugin>
    <groupId>org.codehaus.cargo</groupId>
    <artifactId>cargo-maven2-plugin</artifactId>
    <configuration>
      <container>
        <containerId>jetty7x</containerId>
        <zipUrlInstaller>
          <url>http://download.eclipse.org/jetty/7.2.2.v20101205/dist/jetty-distribution-7.2.2.v20101205.tar.gz</url>
          <!--
            Careful: As described above, Cargo versions older than 1.1.0
            accept only installDir, you therefore need to set installDir
            instead of downloadDir and extractDir.
            -->
          <downloadDir>${project.build.directory}/downloads</downloadDir>
          <extractDir>${project.build.directory}/extracts</extractDir>
        </zipUrlInstaller>
      </container>
      [...]
    </configuration>
  </plugin>

Using Maven2-based distributions

New versions of most application servers have their distribution packages built by Maven2, hence distribute these as ZIP or TAR.GZ files on a Maven2 repository. It is also rather easy to upload servers' packages to an internal (for example, enterprise) Maven repository.

Starting from Cargo 1.1.0, you can directly use such artifacts using an ArtifactInstaller. Here is the example for Jetty 7:

  <properties>
    <jetty.version>7.2.2.v20101205</jetty.version>
  </properties>

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
        <version>${cargo.version}</version>
        <configuration>
          <container>
            <containerId>jetty7x</containerId>
            <artifactInstaller>
              <groupId>org.eclipse.jetty</groupId>
              <artifactId>jetty-distribution</artifactId>
              <version>${jetty.version}</version>
            </artifactInstaller>
          </container>
          [...]
        </configuration>
        [...]
      </plugin>
    </plugins>
  </build>
</project>

In older versions of Cargo, the CARGO ZipUrlInstaller can be used to reuse the Maven dependency. The example below illustrates that use case applied on Jetty 7:

  <properties>
    <jetty.version>7.2.2.v20101205</jetty.version>
  </properties>

  <!-- This will make Maven2 download the official Jetty 7 ZIP distribution -->
  <dependencies>
    <dependency>
      <groupId>org.eclipse.jetty</groupId>
      <artifactId>jetty-distribution</artifactId>
      <version>${jetty.version}</version>
      <scope>test</scope>
      <type>zip</type>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
        <version>${cargo.version}</version>
        <configuration>
          <container>
            <containerId>jetty7x</containerId>
            <!-- Tell the ZipUrlInstaller to reuse the downloaded Jetty 7 ZIP distribution -->
            <zipUrlInstaller>
              <url>
                file:///${settings.localRepository}/org/eclipse/jetty/jetty-distribution/${jetty.version}/jetty-distribution-${jetty.version}.zip
              </url>
              <!--
                Careful: As described above, Cargo versions older than 1.1.0
                accept only installDir, you therefore need to set installDir
                instead of extractDir.
                -->
              <extractDir>${project.build.directory}/jetty-root</extractDir>
            </zipUrlInstaller>
          </container>
          [...]
        </configuration>
        [...]
      </plugin>
    </plugins>
  </build>
</project>
Document generated by Confluence on May 05, 2011 19:53