* added first draft of documentation for metadata module

git-svn-id: svn+ssh://svn.synyx.de/var/svn/synyx/opensource/hera/trunk@3259 5a64d73e-33d6-4ccc-9058-23f8668ecac9

hera-metadata/src/doc/metadata.xml

@@ -1,6 +1,54 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<chapter>
+<chapter id="metadata">
   <title>Metadata</title>
 
-  <para>TODO</para>
-</chapter>
+  <para>For plugin architectures it is essential to capture metadata
+  information about plugin instances. A very core set of metadata (name,
+  version) also serves as identifier of a plugin and thus can be used. The
+  Hera metadata module provides support to capture metadata.</para>
+
+  <section id="metadata.core-concepts">
+    <title>Core concepts</title>
+
+    <para>The metadata module actually builds around two core interfaces,
+    <interfacename>PluginMetadata</interfacename> and
+    <interfacename>MetadataProvider</interfacename>:</para>
+
+    <example>
+      <title>Core concepts</title>
+
+      <programlisting language="java">public interface PluginMetadata {
+
+  String getName();
+
+  String getVersion();
+}
+
+
+public interface MetadataProvider {
+
+  PluginMetadata getMetadata();
+}</programlisting>
+    </example>
+
+    <para>The <interfacename>PluginMetadata</interfacename> interface captures
+    the required properties to define an identifyable plugin. This means, that
+    implementations should ensure uniqueness through these two properties.
+    With <classname>SimplePluginMetadata</classname> Hera provides a Java bean
+    style class to capture metadata. Of course applications can and should
+    provide extended metadata information according to their needs. The very
+    narrow interface is only targeted at integrating the metadata concept with
+    the <classname>PluginRegistry</classname> (see <xref
+    linkend="core.plugin-registry" />) without bothering developers with too
+    much information required.</para>
+
+    <para>The MetadataProvider interface is to be used in application plugin
+    interfaces to indicate that they can provide metadata. To ease plugin
+    implementation we provide AbstractMetadataBasedPlugin that uses the
+    internal metadata to implement supports(..) method of Plugin. Extending
+    this base class plugins with metadata as selection criteria can easily be
+    build. This way you could store the metadata in user specific
+    configuration files and use this to select a distinct plugin specific to a
+    given user.</para>
+  </section>
+</chapter>

src/doc/hera-reference.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book  [
-  <!ENTITY core SYSTEM "../../hera-core/src/doc/core.xml">
-  <!ENTITY metadata SYSTEM "../../hera-metadata/src/doc/metadata.xml">
+<!DOCTYPE book [
+<!ENTITY core SYSTEM "../../hera-core/src/doc/core.xml">
+<!ENTITY metadata SYSTEM "../../hera-metadata/src/doc/metadata.xml">
 ]>
 <!-- PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" -->
@@ -49,7 +49,19 @@
           <surname>Gierke</surname>
         </author>
 
-        <revremark>Initial draft </revremark>
+        <revremark>Initial draft</revremark>
+      </revision>
+
+      <revision>
+        <date>05.11.2008</date>
+
+        <author>
+          <firstname>Oliver</firstname>
+
+          <surname>Gierke</surname>
+        </author>
+
+        <revremark>Added metadata module documentation</revremark>
       </revision>
     </revhistory>
   </bookinfo>
@@ -127,6 +139,7 @@
   </preface>
 
   &core;
+
   &metadata;
 
   <glossary>