Author: brett
Date: Thu Feb 11 05:29:11 2010
New Revision: 908844
URL: http://svn.apache.org/viewvc?rev=908844&view=rev
Log:
start developer documentation for the branch
Added:
archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt.vm
- copied, changed from r908811,
archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt
archiva/branches/MRM-1025/archiva-modules/src/site/apt/metadata.apt
archiva/branches/MRM-1025/archiva-modules/src/site/apt/repositories.apt
archiva/branches/MRM-1025/archiva-modules/src/site/apt/terminology.apt
Removed:
archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt
Modified:
archiva/branches/MRM-1025/archiva-modules/metadata/content-model.txt
archiva/branches/MRM-1025/archiva-modules/src/site/site.xml
Modified: archiva/branches/MRM-1025/archiva-modules/metadata/content-model.txt
URL:
http://svn.apache.org/viewvc/archiva/branches/MRM-1025/archiva-modules/metadata/content-model.txt?rev=908844&r1=908843&r2=908844&view=diff
==============================================================================
--- archiva/branches/MRM-1025/archiva-modules/metadata/content-model.txt
(original)
+++ archiva/branches/MRM-1025/archiva-modules/metadata/content-model.txt Thu
Feb 11 05:29:11 2010
@@ -166,10 +166,6 @@
*) filename (scanner-1.0-20091120.012345-1.pom) is a node, and each is
distinct except for checksums, etc.
-*) the top level version (1.0-SNAPSHOT) is the version best used to describe
the project (the "marketed version"). It
- must still be unique for lookup and comparing project versions to each
other, but can contain several different
- "build" artifacts.
-
*) Projects are just a single code project. They do not have subprojects - if
such modeling needs to be done, then we
can create a products tree that will map what "Archiva 1.0" contains from
the other repositories.
Copied: archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt.vm
(from r908811, archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt)
URL:
http://svn.apache.org/viewvc/archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt.vm?p2=archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt.vm&p1=archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt&r1=908811&r2=908844&rev=908844&view=diff
==============================================================================
--- archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt (original)
+++ archiva/branches/MRM-1025/archiva-modules/src/site/apt/index.apt.vm Thu Feb
11 05:29:11 2010
@@ -4,5 +4,72 @@
Archiva Developer's Documentation
- These documents cover the architecture of Archiva and how to work with it.
+ These documents cover the architecture of Archiva and how to work with it.
Information for users and plugin
+ developers can be found instead in the
+ {{{http://archiva.apache.org/docs/${project.version}/index.html} main
Archiva documentation}}.
+ <Note:> This documentation is far from complete, and mostly covers new
improvements relevant to developers as they
+ are made, and may not cover older topics such as the <<<archiva-model>>>
or <<<archiva-repository-layer>>> libraries
+ that are still in use and particularly coupled to certain repository types
and the web interfaces.
+
+* Overview
+
+ Archiva is built as a layered application. It is intended to provide a
platform for dealing with repositories of
+ varied types, and so is built as a series of modular libraries that aim to
be able to be used independently (such as
+ embedded scenarios, from the CLI, or within the Archiva web application).
+
+ Central to the redesign of Archiva is the concept of a metadata content
repository. Archiva separates the physical
+ storage of a repository from the representation it works on, allowing it
to store information about the repository
+ in an extensible format that any plugin can operate on or add to, without
all subsystems needing to know about
+ each other. The metadata is not specific to any repository type - for
instance, the Maven 2 portions can be
+ completely optional. More information on the {{{./metadata.html} metadata
format}} and how it is persisted is
+ present in the section below.
+
+ This structure allows metadata repositories to be physically separated
from the repository they represent and
+ remotely updated. However, it is also possible to link the repository
storage via the API so that the metadata can
+ operate "live" on a repository, detecting changes. This also allows
plugins that wish to operate directly on a
+ repository (for example, Maven snapshot purging).
+
+ Similarly, the resolution strategy for resources in the repository is
abstracted from the storage and metadata to
+ allow multiple strategies. This facilitates features such as repository
proxying, repository grouping, and on the
+ fly format conversion. These are described in the {{{./repositories.html}
Repository API}} documents.
+
+ On top of the metadata repository, components can be built to provide the
services available in the application.
+ These are described as plugins, though at this time there is no formal
plugin registration mechanism or interface -
+ they are loaded by the presence of the JAR in the application classpath,
with the appropriate Spring or Plexus
+ manifest and implementation of a core interface that they can "plug in"
to. At present, these plugins interact
+ either due to a user request (the repository resolution extension points),
a distinct scheduled task, or as part of
+ a repository scanning operation (the Archiva 1.0+ 'consumer' mechanism).
In the future, an event mechanism is
+ envisaged as the main means of triggering plugin operations, further
decoupling them from the core interfaces.
+ Plugins generally interact directly with the metadata repository to
retrieve information, or store their own.
+
+ Some examples of current plugins are:
+
+ * Maven 2 storage repository type
+
+ * Repository statistics
+
+ * File-based metadata content repository persistence
+
+ []
+
+ Finally, we look to the web application layers. At present, there is a
single web application that serves both a
+ WebDAV and Struts 2-based application, and operates directly on the
metadata repository and some of the legacy
+ APIs. Future development plans to better decouple these from the
underlying plugins and legacy APIs, to allow
+ applications to be much more componentised in their deployment.
+
+** How it Works
+
+ * {{{./terminology.html} Terminology}}
+
+ * {{{./metadata.html} Repository metadata}}
+
+ * {{{./repositories.html} Repository APIs}}
+
+* More Information
+
+ More information is available on the Archiva Wiki:
+
+ *
{{{http://cwiki.apache.org/confluence/display/ARCHIVA/Archiva+Developer+Notes}
Developer Notes}}
+
+ *
{{{http://cwiki.apache.org/confluence/display/ARCHIVA/Conventions+and+Processes}
Conventions and Processes}}
Added: archiva/branches/MRM-1025/archiva-modules/src/site/apt/metadata.apt
URL:
http://svn.apache.org/viewvc/archiva/branches/MRM-1025/archiva-modules/src/site/apt/metadata.apt?rev=908844&view=auto
==============================================================================
(empty)
Added: archiva/branches/MRM-1025/archiva-modules/src/site/apt/repositories.apt
URL:
http://svn.apache.org/viewvc/archiva/branches/MRM-1025/archiva-modules/src/site/apt/repositories.apt?rev=908844&view=auto
==============================================================================
(empty)
Added: archiva/branches/MRM-1025/archiva-modules/src/site/apt/terminology.apt
URL:
http://svn.apache.org/viewvc/archiva/branches/MRM-1025/archiva-modules/src/site/apt/terminology.apt?rev=908844&view=auto
==============================================================================
--- archiva/branches/MRM-1025/archiva-modules/src/site/apt/terminology.apt
(added)
+++ archiva/branches/MRM-1025/archiva-modules/src/site/apt/terminology.apt Thu
Feb 11 05:29:11 2010
@@ -0,0 +1,84 @@
+ ----
+ Terminology
+ ----
+
+Terminology
+
+ Archiva uses a lot of pieces of data that can have heavily overloaded
meaning, so it is important to ensure the
+ terminology used is well defined and consistently used. The following
section highlights the terms used in these
+ documents.
+
+* Repository
+
+ Repository is the most overloaded term, but when used alone it will refer
to the abstract concept of anything that
+ can act as a repository. For example, an on-disk Maven 2 repository, a
remote proxied repository, or a repository
+ group that appears as a single repository.
+
+ A repository is capable of storing a number of artifacts and their
associated metadata. Each artifact is identified
+ by a number of elements: the repository itself, it's namespace, project,
project version and artifact ID. Some
+ components are optional, depending on the repository type being discussed
- for example each is mapped in a Maven 2
+ repository, while for a flat file storage only the repository and artifact
ID (file path and name) is needed.
+
+* Namespace
+
+ A namespace is a hierarchical grouping for projects and artifacts,
allowing project and artifact IDs to more easily
+ be made unique within their namespace and to assist in mapping between
different repository types.
+
+ In a Maven 2 repository, this maps to the group ID of an artifact.
+
+* Project
+
+ A project is a simple grouping of artifacts that share a version in a
repository. It does not contain subprojects.
+
+ In a Maven 2 repository, this maps to the artifact ID of an artifact. Note
that multi-module projects will actually
+ represent multiple projects by default, and additional grouping (other
than achieved by the namespace) would need
+ to be done through additional metadata.
+
+* Project Version
+
+ A project version is the version best used to describe the project (the
"marketed version"). It must be unique for
+ lookup and comparing project versions to each other, but the artifact(s)
it contains may still use a different
+ version. For example:
+
+ * Archiva 1.4-SNAPSHOT may have artifacts
<<<archiva-1.4-20090909.123456-1.jar>>> and
+ <<<archiva-1.4-20100201.345612-2.jar>>>.
+
+ * Jetty 7.0.0 may have an artifact <<<jetty-7.0.0.v20091005.jar>>>
+
+ In a Maven 2 repository, this maps to the (base) version of a project.
+
+* Artifact ID
+
+ The artifact ID uniquely identifies an artifact within a given namespace,
project and project version. For example,
+ <<<archiva-1.4-20100201.345612-2.jar>>> or
<<<archiva-1.4-20100201.345612-2.pom>>>.
+
+ In a Maven 2 repository, this maps to the filename within the repository,
including both the Maven artifact ID,
+ artifact version, classifier and type/extension. Note that the POM and the
classic artifact will be stored with
+ separate artifact IDs, but the repository implementation stores the common
information for the whole project
+ version (and perhaps all project versions in some instances).
+
+* Metadata Repository
+
+ The metadata repository is the metadata representation of a given
repository, containing information about the
+ artifacts it contains, as well as other auxiliary information such as
statistics, events, etc.
+
+* Metadata Content Repository
+
+ The metadata content repository is how the information in a metadata
repository is persisted. It is effectively the
+ same in appearance to the metadata repository.
+
+* Repository Resolver
+
+ A resolver decides how to translate a request into a given set of metadata
or an artifact retrieved from repository
+ storage. The default resolver first queries metadata, falling back to the
repository storage if available if
+ necessary due to not being found or being out of date. It is possible that
new resolvers can be introduced to also
+ check proxied repositories or to group multiple repositories.
+
+* Repository Storage
+
+ A physical storage medium for a type of repository. This may be a file
system in Maven 2 format, a URL pointing to
+ a repository in a certain format, a flat set of files, etc. It can be
queried and modified to affect the canonical
+ set of artifacts.
+
+
+
Modified: archiva/branches/MRM-1025/archiva-modules/src/site/site.xml
URL:
http://svn.apache.org/viewvc/archiva/branches/MRM-1025/archiva-modules/src/site/site.xml?rev=908844&r1=908843&r2=908844&view=diff
==============================================================================
--- archiva/branches/MRM-1025/archiva-modules/src/site/site.xml (original)
+++ archiva/branches/MRM-1025/archiva-modules/src/site/site.xml Thu Feb 11
05:29:11 2010
@@ -32,7 +32,10 @@
</breadcrumbs>
<menu name="Developers">
- <item name="About" href="/index.html" />
+ <item name="Overview" href="/index.html" />
+ <item name="Terminology" href="/terminology.html" />
+ <item name="Metadata" href="/metadata.html" />
+ <item name="Repositories" href="/repositories.html" />
</menu>
<menu ref="modules" />
</body>
