re-arrange docs and write up metadata repository

git-svn-id: https://svn.apache.org/repos/asf/archiva/branches/MRM-1025@909022 13f79535-47bb-0310-9956-ffa450edef68

6 files changed, 71 insertions, 23 deletions

diff --git a/archiva-modules/src/site/apt/index.apt.vm b/archiva-modules/src/site/apt/index.apt.vm
index c0af70403..4e4e22ea3 100644
--- a/archiva-modules/src/site/apt/index.apt.vm
+++ b/archiva-modules/src/site/apt/index.apt.vm
@@ -62,9 +62,11 @@ Archiva Developer's Documentation
 
     * {{{./terminology.html} Terminology}}
 
-    * {{{./metadata.html} Repository metadata}}
+    * {{{./metadata-content-model.html} Repository metadata content model}}
 
-    * {{{./repositories.html} Repository APIs}}
+    * {{{./metadata-api.html} Repository metadata API and persistence}}
+
+    * {{{./repository-api.html} Repository APIs}}
 
 * More Information
 
diff --git a/archiva-modules/src/site/apt/metadata-api.apt b/archiva-modules/src/site/apt/metadata-api.apt
new file mode 100644
index 000000000..c917eaf0f
--- /dev/null
+++ b/archiva-modules/src/site/apt/metadata-api.apt
@@ -0,0 +1,46 @@
+ ----
+ Metadata API
+ ----
+
+Metadata API and Persistence
+
+    The Metadata Java API is comprised of the following:
+
+        * The Java model
+
+        * The Metadata repository API
+
+        * The plugins for storing the metadata repository content
+
+* Metadata Models
+
+    The Java model is a very simply representation of the metadata. Presently the following are represented:
+
+        * {{{./apidocs/org/apache/archiva/metadata/model/MetadataFacet.html} repository metadata facets}}
+
+        * {{{./apidocs/org/apache/archiva/metadata/model/ProjectMetadata.html} project metadata}}
+
+        * {{{./apidocs/org/apache/archiva/metadata/model/ProjectVersionMetadata.html} project version metadata}}
+
+        * various subtypes
+
+    More information can be found in the
+    {{{./apidocs/org/apache/archiva/metadata/model/package-summary.html} org.apache.archiva.metadata.model}} package,
+    or the {{{./metadata/metadata-model/index.html} metadata-model}} module.
+
+* Metadata Repository API
+
+    The metadata repository API is responsible for accessing the metadata repository and persisting changes. This is
+    handled by the {{{./apidocs/org/apache/archiva/metadata/repository/MetadataRepository.html} MetadataRepository}}
+    class.
+
+    More information can be found in the {{{./metadata/metadata-repository-api/index.html} metadata-repository-api}}
+    module.
+
+* Persistence
+
+    Currently, the only implementation of persistence for the metadata content is a flat-file option using Java
+    properties. The code is note yet production quality. You can find out more in the:
+    {{{./apidocs/org/apache/archiva/metadata/repository/file/FileMetadataRepository.html} FileMetadataRepository}}
+    class.
+
diff --git a/archiva-modules/src/site/apt/metadata.apt b/archiva-modules/src/site/apt/metadata-content-model.apt
index a7a1c68ef..f5c193615 100644
--- a/archiva-modules/src/site/apt/metadata.apt
+++ b/archiva-modules/src/site/apt/metadata-content-model.apt
@@ -1,20 +1,17 @@
  ----
- Metadata Repository
+ Metadata Control Model
  ----
 
-Metadata Repository
+Metadata Content Model
 
     The metadata repository stores all known information about a repository in a common format that other plugins can
     understand, and that eventually external applications will be able to query.
 
-    Dealing with metadata repositories covers two aspects: the content model, and the content repository access API
-    (and persistence).
-
-* Content Model
-
     The content model is designed such that it models the most likely structure of the data both for storage and
     retrieval. For example, audit logs are stored by the time they occur, not grouped under an action.
 
+* Content Model Structure
+
     The following is a sample tree that represents the content model:
 
 ----
@@ -174,6 +171,14 @@ Metadata Repository
     This uses a typical content repository structure, where there is a path to a particular node (the last paths in
     the structure above), and nodes can have properties and values (shown as <<<property=value>>> above).
 
+    Properties with '.' may be nested in other representations such as Java models or XML, if appropriate - this is
+    the decision of the content repository persistence implementation.
+
+    Additionally, while some information is stored at the most generic level in the metadata repository (eg
+    <<<maven:groupId>>>, <<<maven:artifactId>>>), for convenience when loaded by the implementation it may all be pushed
+    into the project version's information. The metadata repository implementation can decide how best to store and
+    retrieve the information.
+
     <Note:> Some of the properties have been put in place temporarily but need to be revisited - for example the use
             of index counters for the lists of Maven POM information are not ideal, and some Maven specific aspects of
             the dependencies should become faceted content
@@ -351,15 +356,3 @@ Metadata Repository
     References are stored outside the main model so that their creation doesn't imply a "stub" model - we know if the
     project exists whether a reference is created or not. References need not infer referential integrity.
 
-
-    ~~ Java API
-
-    ~~ access
-
-    ~~ persistence
-
-        ~~ properties with '.' may be nested in other representations such as Java models or XML, if appropriate
-
-        ~~ while some information is stored at the most generic level in the metadata repository (eg maven:groupId,
-           maven:artifactId), for convenience when loaded by the implementation it may all be pushed into the projectVersion's
-           information. The metadata repository implementation can decide how best to store and retrieve the information.
diff --git a/archiva-modules/src/site/apt/repositories.apt b/archiva-modules/src/site/apt/repositories.apt
deleted file mode 100644
index e69de29bb..000000000
--- a/archiva-modules/src/site/apt/repositories.apt
+++ /dev/null
diff --git a/archiva-modules/src/site/apt/repository-api.apt b/archiva-modules/src/site/apt/repository-api.apt
new file mode 100644
index 000000000..8c8977a4e
--- /dev/null
+++ b/archiva-modules/src/site/apt/repository-api.apt
@@ -0,0 +1,6 @@
+ ----
+ Repository APIs
+ ----
+
+Repository APIs
+
diff --git a/archiva-modules/src/site/site.xml b/archiva-modules/src/site/site.xml
index 3a18408c7..c5cf9ea63 100644
--- a/archiva-modules/src/site/site.xml
+++ b/archiva-modules/src/site/site.xml
@@ -34,8 +34,9 @@
     <menu name="Developers">
       <item name="Overview" href="/index.html" />
       <item name="Terminology" href="/terminology.html" />
-      <item name="Metadata" href="/metadata.html" />
-      <item name="Repositories" href="/repositories.html" />
+      <item name="Metadata Control Model" href="/metadata-content-model.html" />
+      <item name="Metadata API" href="/metadata-api.html" />
+      <item name="Repository API" href="/repository-api.html" />
     </menu>
     <menu ref="modules" />
   </body>