Artificer Extension Points
--------------------------

Artificer includes multiple "extension point" contracts that allow users to provide additional, custom
functionality.  The contracts currently include the following:

ArtifactBuilder
~~~~~~~~~~~~~~~
As mentioned earlier in this guide, part of the S-RAMP specification is the concept of 
derived content.  This happens when an artifact of a certain type is added to the Artificer
repository.  The server is responsible for creating relevant and interesting derived
artifacts from it.  For example, when an XML Schema (XSD) document is added to the 
repository, the server is responsible for automatically creating an artifact for every
top level Element, Complex Type, Simple Type, and Attribute declaration found in the XSD.

The ArtifactBuilder contract allows integrations to define custom properties on the
primary artifact, generate derived artifacts, and resolve relationships between the whole set.
The Artificer implementation includes ArtifactBuilders for all of the logical models
defined by the S-RAMP specification (e.g. WSDL, XSD, Policy).  However, it also provides a
mechanism that allows users to provide ArtifactBuilders for their own artifact types.  This
is done by performing the following steps:

1. Write a custom ArtifactBuilder Java class - it must implement *ArtifactBuilder*
2. Create an ArtifactBuilderProvider (a class that implements *ArtifactBuilderProvider*) - 
   used to map artifact types to implementations of ArtifactBuilder
3. Provide a text file named *org.artificer.integration.artifactbuilder.ArtifactBuilderProvider* in the following
   location:  *META-INF/services*.  The content of that file should simply be one line containing
   the fully qualified classname of the class defined in #2
4. Package everything up into a JAR and make it available either on the classpath or in an
   external directory configured by setting property *artificer.extension.customDir*.
   
The Artificer distribution comes with an example of how to write and package a custom 
builder - the demo is named *custom-artifact-builder*.  Also, see the Javadocs for
the relevant classes.

ArtifactTypeDetector
~~~~~~~~~~~~~~~~~~~~
When an artifact is deployed *without* an explicit model and type, we must attempt to automatically detect them.
The ArtifactTypeDetector contract allows integrations to automatically detect an artifact's type, given various
contextual-clues.  The clues include the path/filename, the artifact's context within an archive, and the artifact's
full content.  That last bit is the most powerful part, allowing integrations to, for example, parse files and
introduce complex business logic.

As with ArtifactBuilder, Artificer provides several built-in detectors.  However, it also provides a
mechanism that allows users to provide their own ArtifactTypeDetectors .  This
is done by performing the following steps:

1. Write a custom ArtifactTypeDetector Java class - it must implement *ArtifactTypeDetector*
2. Provide a text file named *org.artificer.integration.artifacttypedetector.ArtifactTypeDetector* in the following
   location:  *META-INF/services*.  The content of that file should simply be one line containing
   the fully qualified classname of the class defined in #1
3. Package everything up into a JAR and make it available either on the classpath or in an
   external directory configured by setting property *artificer.extension.customDir*.

The implementations form a prioritized chain, most-specialized at the top and most-generic at the bottom
(the contract includes a #getPriority method).  It's important to note that execution is *exclusive* and ends
processing for the rest of the chain.  So, custom implementations *extending* built-in detectors isn't really necessary
-- simply return null and they'll be executed eventually.