ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r1533428 - in /ace/site/trunk: content/dev-doc/adding-custom-artifact-types.mdtext content/user-doc/getting-started.mdtext content/user-doc/user-guide.mdtext templates/sidenav.html templates/skeleton.html
Date Fri, 18 Oct 2013 12:50:11 GMT
Author: marrs
Date: Fri Oct 18 12:50:11 2013
New Revision: 1533428

URL: http://svn.apache.org/r1533428
Log:
Added the user guide to the navigation. Added a page about adding new artifact types to ACE.

Added:
    ace/site/trunk/content/dev-doc/adding-custom-artifact-types.mdtext
Modified:
    ace/site/trunk/content/user-doc/getting-started.mdtext
    ace/site/trunk/content/user-doc/user-guide.mdtext
    ace/site/trunk/templates/sidenav.html
    ace/site/trunk/templates/skeleton.html

Added: ace/site/trunk/content/dev-doc/adding-custom-artifact-types.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/adding-custom-artifact-types.mdtext?rev=1533428&view=auto
==============================================================================
--- ace/site/trunk/content/dev-doc/adding-custom-artifact-types.mdtext (added)
+++ ace/site/trunk/content/dev-doc/adding-custom-artifact-types.mdtext Fri Oct 18 12:50:11
2013
@@ -0,0 +1,204 @@
+Title: Adding custom artifact types
+
+Out of the box, ACE comes with support for bundles and configuration files that follow the
Auto Configuration specification. However, it is possible to extend ACE with support for new
types of artifacts. Doing so requires you to do three things:
+
+1. Write a resource processor, according to the Deployment Admin specification.
+2. Write an ArtifactRecognizer service implementation.
+3. Write an ArtifactHelper service implementation.
+
+This document explains how to write each of these, and how to subsequently deploy them appropriately.
+
+# Writing a resource processor
+
+A resource processor implements the ResourceProcessor interface as defined in the Deployment
Admin specification (OSGi Compendium 114.10). It describes in detail the contract that needs
to be implemented and also contains an example. If you want to get started quickly, you can
use the following code:
+
+	:::java
+	public class Processor implements ResourceProcessor {
+	    private volatile DeploymentSession m_session;
+	    private String m_deploymentPackageName;
+	    private List<String> m_toInstall;
+	    private List<String> m_toRemove;
+
+	    /**
+	     * Sets up the necessary environment for a deployment session.
+	     */
+	    private void startSession(DeploymentSession session) {
+	        if (m_session != null) {
+	            throw new IllegalArgumentException("This resource processor is currently processing
another deployment session, installing deploymentpackage" + m_session.getTargetDeploymentPackage().getName());
+	        }
+	        m_session = session;
+	        m_toInstall = new ArrayList<String>();
+	        m_toRemove = new ArrayList<String>();
+	        String fromSource = session.getSourceDeploymentPackage().getName();
+	        String fromTarget = session.getTargetDeploymentPackage().getName();
+	        if (fromSource.equals("")) {
+	            m_deploymentPackageName = fromTarget;
+	        }
+	        else {
+	            m_deploymentPackageName = fromSource;
+	        }
+	    }
+
+	    /**
+	     * Ends a deployment session.
+	     */
+	    private void endSession() {
+	        m_session = null;
+	        m_deploymentPackageName = null;
+	        m_toInstall = null;
+	        m_toRemove = null;
+	    }
+
+	    private void ensureSession()  {
+	        if (m_session == null) {
+	            throw new IllegalStateException("This resource processor is currently not part
of a deployment session.");
+	        }
+	    }
+
+	    public void begin(DeploymentSession session) {
+	        startSession(session);
+	    }
+
+	    public void process(String name, InputStream stream) throws ResourceProcessorException
{
+	        ensureSession();
+	        m_toInstall.add(name);
+	    }
+
+	    public void dropped(String resource) throws ResourceProcessorException {
+	        ensureSession();
+	        m_toRemove.add(resource);
+	    }
+
+	    public void dropAllResources() throws ResourceProcessorException {
+	        ensureSession();
+	        m_toRemove.addAll(Collections.EMPTY_LIST /* should be a list of all current resources
*/);
+	    }
+
+	    public void prepare() throws ResourceProcessorException {
+	        ensureSession();
+	    }
+
+	    public void commit() {
+	        ensureSession();
+	        while (!m_toInstall.isEmpty()) {
+	        	System.out.println("installing: " + m_toInstall.remove(0));
+	        }
+	        while (!m_toRemove.isEmpty()) {
+	        	System.out.println("removing: " + m_toRemove.remove(0));
+	        }
+	        endSession();
+	    }
+
+	    public void rollback() {
+	        // nothing special to do.
+	        ensureSession();
+	        endSession();
+	    }
+
+	    public void cancel() {
+	        ensureSession();
+	        // Nothing to do: we have no long-running operation, we only read the stream.
+	    }
+	}
+
+This should be enough to get you started, but the code takes a few shortcuts so please do
take some time to read the specification and implement each method correctly.
+
+The next step then is to publish this processor as an OSGi service. Don't forget to add the
SERVICE_PID property and set its value, because that is how the processor is later recognized.
Package everything up in an OSGi bundle and make sure to include these two headers in its
manifest:
+
+	Deployment-ProvidesResourceProcessor: org.apache.ace.resourceprocessor.custom
+	DeploymentPackage-Customizer: true
+
+The first one should match the PID you used earlier.
+
+# Writing an ArtifactHelper and ArtifactRecognizer
+
+These services can usually just be implemented by the same class. The artifact recognizer
is used to identify an artifact as being of this specific type. How it does that is up to
the implementation. It might do something as simple as look at the file extension, but a lot
of recognizers will also inspect (part of) the actual file. The artifact helper then contains
all kinds of methods to help ACE deal with this specific type of artifact. The API documentation
of these two interfaces explains the methods in detail. Again, let's get started with an implementation
of both for a very simple artifact: a file with a specific extension:
+
+	:::java
+	public class CustomArtifactHelper implements ArtifactRecognizer, ArtifactHelper {
+	    public static final String KEY_FILENAME = "filename";
+	    public static final String MIMETYPE = "application/vnd.apache.ace.custom";
+	    public static final String PROCESSOR = "org.apache.ace.resourceprocessor.custom";
+
+		@Override
+		public boolean canUse(ArtifactObject object) {
+	        return (object == null) ? false : MIMETYPE.equals(object.getMimetype());
+		}
+
+		@Override
+		public ArtifactPreprocessor getPreprocessor() {
+			return null;
+		}
+
+		@Override
+		public <TYPE extends ArtifactObject> String getAssociationFilter(TYPE obj, Map<String,
String> properties) {
+	        return "(" + ArtifactObject.KEY_ARTIFACT_NAME + "=" + obj.getAttribute(ArtifactObject.KEY_ARTIFACT_NAME)
+ ")";
+		}
+
+		@Override
+		public <TYPE extends ArtifactObject> int getCardinality(TYPE obj, Map<String,
String> properties) {
+	        return Integer.MAX_VALUE;
+		}
+
+		@Override
+		public Comparator<ArtifactObject> getComparator() {
+			return null;
+		}
+
+		@Override
+		public Map<String, String> checkAttributes(Map<String, String> attributes)
{
+			return attributes;
+		}
+
+	    public String[] getDefiningKeys() {
+	        return new String[] {ArtifactObject.KEY_ARTIFACT_NAME};
+	    }
+
+	    public String[] getMandatoryAttributes() {
+	        return new String[] {ArtifactObject.KEY_ARTIFACT_NAME};
+	    }
+
+		@Override
+		public String recognize(ArtifactResource artifact) {
+			// here we can examine the stream to check the contents of the artifact
+			// for this demo, our check is just for the extension of the URL, which is
+			// a bit simplistic
+			if (artifact.getURL().toExternalForm().endsWith(".custom")) {
+				return MIMETYPE;
+			}
+			return null;
+		}
+
+		@Override
+		public Map<String, String> extractMetaData(ArtifactResource artifact) throws IllegalArgumentException
{
+	        Map<String, String> result = new HashMap<String, String>();
+	        result.put(ArtifactObject.KEY_PROCESSOR_PID, PROCESSOR);
+	        result.put(ArtifactObject.KEY_MIMETYPE, MIMETYPE);
+	        String name = new File(artifact.getURL().getFile()).getName();
+	        result.put(ArtifactObject.KEY_ARTIFACT_NAME, name);
+	        result.put(KEY_FILENAME, name);
+	        return result;
+		}
+
+		@Override
+		public boolean canHandle(String mimetype) {
+			return MIMETYPE.equals(mimetype);
+		}
+
+		@Override
+		public String getExtension(ArtifactResource artifact) {
+			return ".custom";
+		}
+	}
+
+Again, this is no production code, but it should get you started quickly. This code will
recognize artifacts that have the ".custom" file extension. No effort is done here to look
at the contents of the file, to keep the example simple. Publish this instance as both an
ArtifactHelper and an ArtifactRecognizer and make sure to add a service property for the mime
type: ArtifactObject.KEY_MIMETYPE, CustomArtifactHelper.MIMETYPE
+
+Wrap it up in a bundle, and you're ready to use your custom artifact in ACE.
+
+# Installing everything in ACE
+
+To add the new artifact type to ACE, you first have to take the bundle that contained the
ArtifactHelper and ArtifactRecognizer service and add that to ACE. The bundle should be part
of the ACE client. If you use the "all in one" server, add it to that.
+
+The second step is to upload the resource processor to ACE. You can do that like you upload
any other bundle. Just add it to the artifact column. After adding it, it will not show up
in the column, but ACE will send it to a target if that target needs an artifact of this type.
+
+Should you ever discover that you made a mistake in your resource processor, you can simply
upload a newer one. Just make sure you bump the version and ACE will ensure that everybody
gets this latest version.

Modified: ace/site/trunk/content/user-doc/getting-started.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/getting-started.mdtext?rev=1533428&r1=1533427&r2=1533428&view=diff
==============================================================================
--- ace/site/trunk/content/user-doc/getting-started.mdtext (original)
+++ ace/site/trunk/content/user-doc/getting-started.mdtext Fri Oct 18 12:50:11 2013
@@ -6,39 +6,17 @@ This guide shows the core functionality 
 
 To start using ACE, you must first launch a server. If you're a developer, you can do that
inside Eclipse, as explained [here](/dev-doc/getting-started.html). Otherwise, you need to
download a distribution of the server, unpack it, and start it up:
 
-### Version 0.8.1
-
-1. Download a binary distribution of the server from the [download](/downloads.html) page.
-1. Unpack the archive somewhere on your filesystem.
-
-### Version 1.0 (comming soon)
-
 1. Download the binary distribution called `apache-ace-<version>-bin.zip` from the
[download](/downloads.html) page.
 1. Unpack the archive somewhere on your filesystem.
 
 ## Start the ACE server
 
-### Version 0.8.1
-
-1. Open a terminal and navigate into the root of the distribution.
-1. Start the server using `run.sh` (on Linux and Mac OS X) or `run.bat` (on Windows).
-
-### Version 1.0
-
 1. Open a terminal and navigate nto the root of the distribution.
 1. Navigate to the sub directory `server-allinone`.
 1. Start the server using `java -jar server-allinone.jar`
 
 ## Start an ACE target
 
-### Version 0.8.1
-
-1. Open a terminal and navigate into the root of the distribution.
-1. Navigate to the sub directory `ace-launcher/target`.
-1. Start the agent using `java -jar org.apache.ace.launcher*.jar`
-
-### Version 1.0
-
 1. Open a terminal and navigate into the root of the distribution.
 1. Navigate to the sub directory `target`.
 1. Start the target using `java -jar target.jar`

Modified: ace/site/trunk/content/user-doc/user-guide.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/user-guide.mdtext?rev=1533428&r1=1533427&r2=1533428&view=diff
==============================================================================
--- ace/site/trunk/content/user-doc/user-guide.mdtext (original)
+++ ace/site/trunk/content/user-doc/user-guide.mdtext Fri Oct 18 12:50:11 2013
@@ -50,7 +50,7 @@ To upload one or more artifacts, you cli
 
 Once artifacts are uploaded, they appear in the Artifacts column. For each artifact, you
can edit its properties by double clicking on it. In addition, you can unlink an artifact
from a feature, which will be discussed later on, and remove an artifact. **Note**: removing
an artifact will only remove it from the server's metadata, *not* from the OBR. 
 
-If you try to upload an artifact that is not recognized by ACE, an error is displayed noting
that that particular artifact is not uploaded. Adding support for new types of artifacts in
ACE is discussed in [this article](/dev-doc/adding-artifact-recognizers.html).
+If you try to upload an artifact that is not recognized by ACE, an error is displayed noting
that that particular artifact is not uploaded. Adding support for new types of artifacts in
ACE is discussed in [this article](/dev-doc/adding-custom-artifact-types.html).
 
 **NOTE**: All changes made through the Web UI need to be stored explicitly by pressing the
"Store" button, otherwise they will not be visible to the ACE server. In case you want to
revert all changes, you can use the "Revert" button. This will ignore all changes and retrieve
the latest state from the server. In case there are no local changes, you can still retrieve
the latest state from the server using the "Retrieve" button.
 

Modified: ace/site/trunk/templates/sidenav.html
URL: http://svn.apache.org/viewvc/ace/site/trunk/templates/sidenav.html?rev=1533428&r1=1533427&r2=1533428&view=diff
==============================================================================
--- ace/site/trunk/templates/sidenav.html (original)
+++ ace/site/trunk/templates/sidenav.html Fri Oct 18 12:50:11 2013
@@ -14,7 +14,7 @@
     <a href="/downloads.html">Downloads</a>
   </li>
   <li class="dropdown">
-    <a href="#" class="dropdown-toggle" data-toggle="dropdown">User Documentation <b
class="caret"></b></a>
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Users <b class="caret"></b></a>
     <ul class="dropdown-menu">
       <li>
         <a href="/user-doc/introduction.html">Introduction</a>
@@ -23,6 +23,9 @@
         <a href="/user-doc/getting-started.html">Getting Started</a>
       </li>
       <li>
+        <a href="/user-doc/user-guide.html">User Guide</a>
+      </li>
+      <li>
         <a href="/user-doc/features.html">Features</a>
       </li>
 	    <li>
@@ -40,7 +43,7 @@
     </ul>
   </li>
   <li class="dropdown">
-    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developer Documentation
<b class="caret"></b></a>
+    <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developers <b class="caret"></b></a>
     <ul class="dropdown-menu">
       <li>
         <a href="/dev-doc/getting-started.html">Getting Started</a>
@@ -66,6 +69,9 @@
       <li>
         <a href="/dev-doc/writing-tests.html">Writing unit/integration tests</a>
       </li>
+      <li>
+        <a href="/dev-doc/adding-custom-artifact-types.html">Adding custom artifact
types</a>
+      </li>
     </ul>
   </li>
   <li class="dropdown">

Modified: ace/site/trunk/templates/skeleton.html
URL: http://svn.apache.org/viewvc/ace/site/trunk/templates/skeleton.html?rev=1533428&r1=1533427&r2=1533428&view=diff
==============================================================================
--- ace/site/trunk/templates/skeleton.html (original)
+++ ace/site/trunk/templates/skeleton.html Fri Oct 18 12:50:11 2013
@@ -2,44 +2,14 @@
 <html lang="en">
   <head>
     <title>{% block title %}{{ headers.title }}{% endblock %}</title>
-
     <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
     <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
-
-  <!--
-    <link rel="stylesheet/less" type="text/css" href="/lib/bootstrap.less">
-    <link href="/css/prettify.css" rel="stylesheet" media="screen">
-    <link href="/css/code.css" rel="stylesheet" media="screen">
-
-    <script src="/js/less-1.2.1.min.js" type="text/javascript"></script>
-    <script src="http://code.jquery.com/jquery-1.7.min.js"></script>
-    <script src="/js/prettify.js"></script>
-    
-    <script src="/js/bootstrap-alert.js"></script>
-    <script src="/js/bootstrap-dropdown.js"></script>
-    <script src="/js/bootstrap-tooltip.js"></script>
-    <script src="/js/bootstrap-alerts.js"></script>
-    <script src="/js/bootstrap-modal.js"></script>
-    <script src="/js/bootstrap-transition.js"></script>
-    <script src="/js/bootstrap-button.js"></script>
-    <script src="/js/bootstrap-popover.js"></script>
-    <script src="/js/bootstrap-twipsy.js"></script>
-    <script src="/js/bootstrap-buttons.js"></script>
-    <script src="/js/bootstrap-scrollspy.js"></script>
-    <script src="/js/bootstrap-typeahead.js"></script>
-    <script src="/js/bootstrap-carousel.js"></script>
-    <script src="/js/bootstrap-tab.js"></script>
-    <script src="/js/bootstrap-collapse.js"></script>
-    <script src="/js/bootstrap-tabs.js"></script>
-  -->
-
     <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen">
     <link href="/css/prettify.css" rel="stylesheet" media="screen">
     <link href="/css/code.css" rel="stylesheet" media="screen">
     <script src="http://code.jquery.com/jquery.js"></script>
     <script src="/js/bootstrap.min.js"></script>    
     <script src="/js/prettify.js"></script>
-
     {% if headers.atom %}<link rel="alternate" href="{{ headers.atom.url }}" type="application/atom+xml"
title="{{ headers.atom.title }}" />{% endif %}
     {% if headers.base %}<base href="{{ headers.base }}" />{% endif %}
     {% if headers.notice %}<!-- {{ headers.notice }} -->{% endif %}
@@ -48,7 +18,6 @@
     $().dropdown()
     </script>
   </head>
-
   <body style="padding-top: 50px;">
     <div class="navbar navbar-fixed-top">
       <div class="navbar-inner">



Mime
View raw message