From 666af8db996298e6bcd9b8c1d980c3be10bed838 Mon Sep 17 00:00:00 2001 From: Brett Porter Date: Thu, 11 Feb 2010 05:29:11 +0000 Subject: [PATCH] start developer documentation for the branch git-svn-id: https://svn.apache.org/repos/asf/archiva/branches/MRM-1025@908844 13f79535-47bb-0310-9956-ffa450edef68 --- archiva-modules/metadata/content-model.txt | 4 - archiva-modules/src/site/apt/index.apt | 8 -- archiva-modules/src/site/apt/index.apt.vm | 75 +++++++++++++++++ archiva-modules/src/site/apt/metadata.apt | 0 archiva-modules/src/site/apt/repositories.apt | 0 archiva-modules/src/site/apt/terminology.apt | 84 +++++++++++++++++++ archiva-modules/src/site/site.xml | 5 +- 7 files changed, 163 insertions(+), 13 deletions(-) delete mode 100644 archiva-modules/src/site/apt/index.apt create mode 100644 archiva-modules/src/site/apt/index.apt.vm create mode 100644 archiva-modules/src/site/apt/metadata.apt create mode 100644 archiva-modules/src/site/apt/repositories.apt create mode 100644 archiva-modules/src/site/apt/terminology.apt diff --git a/archiva-modules/metadata/content-model.txt b/archiva-modules/metadata/content-model.txt index 547af9ec8..94ed443c1 100644 --- a/archiva-modules/metadata/content-model.txt +++ b/archiva-modules/metadata/content-model.txt @@ -166,10 +166,6 @@ Notes: *) 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. diff --git a/archiva-modules/src/site/apt/index.apt b/archiva-modules/src/site/apt/index.apt deleted file mode 100644 index 7bd2758a9..000000000 --- a/archiva-modules/src/site/apt/index.apt +++ /dev/null @@ -1,8 +0,0 @@ - ---- - Archiva Developer's Documentation - ---- - -Archiva Developer's Documentation - - These documents cover the architecture of Archiva and how to work with it. - diff --git a/archiva-modules/src/site/apt/index.apt.vm b/archiva-modules/src/site/apt/index.apt.vm new file mode 100644 index 000000000..c0af70403 --- /dev/null +++ b/archiva-modules/src/site/apt/index.apt.vm @@ -0,0 +1,75 @@ + ---- + Archiva Developer's Documentation + ---- + +Archiva Developer's Documentation + + 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}}. + + 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 <<>> or <<>> 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}} diff --git a/archiva-modules/src/site/apt/metadata.apt b/archiva-modules/src/site/apt/metadata.apt new file mode 100644 index 000000000..e69de29bb diff --git a/archiva-modules/src/site/apt/repositories.apt b/archiva-modules/src/site/apt/repositories.apt new file mode 100644 index 000000000..e69de29bb diff --git a/archiva-modules/src/site/apt/terminology.apt b/archiva-modules/src/site/apt/terminology.apt new file mode 100644 index 000000000..fd82d4b26 --- /dev/null +++ b/archiva-modules/src/site/apt/terminology.apt @@ -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 <<>> and + <<>>. + + * Jetty 7.0.0 may have an artifact <<>> + + 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, + <<>> or <<>>. + + 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. + + + diff --git a/archiva-modules/src/site/site.xml b/archiva-modules/src/site/site.xml index bc1849025..3a18408c7 100644 --- a/archiva-modules/src/site/site.xml +++ b/archiva-modules/src/site/site.xml @@ -32,7 +32,10 @@ - + + + + -- 2.39.5