Artificer Maven Integration
---------------------------

Overview
~~~~~~~~
A key feature of the Artificer project is its integration with Maven.  Currently
there are two mechanisms provided to integrate with Maven.  First, the project provides
an HTTP servlet which acts as a facade in front of the Artificer repository.  This can be used for dependency retrieval
and artifact deployments, just as any other Maven repository.  Second, there is a "maven"
namespace in the Artificer Shell (CLI) providing integration between the CLI and Maven.


Deploying to Artificer
~~~~~~~~~~~~~~~~~~~~~~
The Artificer URL can be directly used in the distributionManagement section.  For example:

----
<distributionManagement>
  <repository>
    <id>local-artificer-repo</id>
    <name>Artificer Releases Repository</name>
    <url>http://localhost:8080/artificer-server/maven/repository</url>
  </repository>
  <snapshotRepository>
    <id>local-artificer-repo-snapshots</id>
    <name>Artificer Snapshots Repository</name>
    <url>http://localhost:8080/artificer-server/maven/repository</url>
  </snapshotRepository>
</distributionManagement>
----

With these settings, maven deployments will be sent directly to the Artificer repository using
the Artificer API.  Note that artifacts will be added to the Artificer repository with an artifact
type based on the maven type of the project.  This behavior can be overridden by adding a
query parameter to the repository URL in the pom.xml.  For example:

----
<distributionManagement>
  <repository>
    <id>local-artificer-repo</id>
    <name>Artificer Releases Repository</name>
    <url>http://localhost:8080/artificer-server/maven/repository?artifactType=SwitchYardApplication</url>
  </repository>
</distributionManagement>
----

The above example will cause the maven artifact to be uploaded with an S-RAMP artifact type 
of "SwitchYardApplication" whenever a maven deployment or release build is performed.

For example, the following maven command could be run to deploy the maven artifact directly into Artificer:

----
mvn clean deploy
----


Adding Artificer Artifacts as Dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Additionally, artifacts from the Artificer repository can
be used as dependencies in your maven project.

First, the Artificer repository must be configured in the maven project as a maven repository.  This
can be done with the following markup in the pom.xml.

----
<repositories>
  <repository>
    <id>local-artificer-repo</id>
    <name>Local Artificer Repository</name>
    <url>http://localhost:8080/artificer-server/maven/repository</url>
    <layout>default</layout>
  </repository>
</repositories>
----

Once the repository is configured, an Artificer artifact can be referenced as a dependency in two
ways.  First, if the artifact was added to Artificer using the maven integration to deploy it, then
the artifact in Artificer will contain maven specific properties, allowing it to be referenced as a
dependency using those maven specific properties.  In this case, simply add the dependency as you 
normally would in a maven project.  For example:

----
<dependency>
  <groupId>org.artificer.wiki</groupId>
  <artifactId>artificer-wiki-example</artifactId>
  <version>1.0</version>
</dependency>
----

However, even if an artifact was added to the Artificer repository in some other way (and therefore
does not have any maven specific properties) it can be used as a dependency.  In this case, you 
can reference the dependency by using its Artificer artifact model, type, and UUID.  The model and
type are used to make up a maven groupId, while the UUID becomes the maven artifactId.  The 
version information is not used (but still required in the pom.xml).  For example, if a JAR is 
added to the Artificer repository and you wish to use it as a dependency, your pom.xml might contain
the following dependency.

----
<dependency>
  <groupId>ext.JavaArchive</groupId>
  <artifactId>8744-437487-4734525-382345-923424</artifactId>
  <version>1.0</version>
</dependency>
----


Authentication
~~~~~~~~~~~~~~
Whenever the Artificer Maven integration features are used, you will need to provide valid authentication credentials in the
http://maven.apache.org/settings.html[Maven settings.xml] file.
However, the typical "username" and "password" values are not sufficient, since they are ignored during artifact
retrieval (ie, GET calls to the repo).  Instead, you must explicitly define the BASIC authentication header value.
Unfortunately, this also means you have to manually Base64 encode the value.  For example, "Basic admin:artificer1!"
becomes "Basic YWRtaW46YXJ0aWZpY2VyMSE=".

It's a pain, but at least as of Maven 3.0.5, it's the best option we could find (PLEASE correct us if we're wrong!).

An example of providing credentials in the settings.xml file:

----
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>local-artificer-repo</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Basic YWRtaW46YXJ0aWZpY2VyMSE=</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
    <server>
      <id>local-artificer-repo-snapshots</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Basic YWRtaW46YXJ0aWZpY2VyMSE=</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>
----


Maven Integration in the CLI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
_Note_:  For more general information about the Artificer Shell please see the Artificer CLI chapter
in this guide.

Another available mechanism for integrating with maven is the Artificer CLI's "maven" command
namespace.  For help on the maven commands in the CLI, run the Artificer shell (artificer.sh) and
type the following from the resulting prompt:

----
help maven
----

Using the maven CLI commands is often a good choice if you wish to incorporate maven related
Artificer operations into a script of some kind.
