www-repository mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Tim Anderson" <...@netspace.net.au>
Subject [proposal] java artifact specifier - v0.2
Date Sat, 15 Nov 2003 13:03:35 GMT
Overview
========

This proposal extends the URI Syntax proposal:
  http://nagoya.apache.org/wiki/apachewiki.cgi?ASFRepository/URISyntax

It is recommended, but not required, that it be used in conjunction
with the Common Build Version Specifier proposal:

http://nagoya.apache.org/wiki/apachewiki.cgi?ASFRepository/CommonBuildVersio
nSpecifier

The key aims of this proposal are to:

. formalise artifact-specifier for java based projects
. provide a set of best practices for such projects; and
. enable tools to construct a URI to unambigously locate
  a particular java project artifact using a set of known
  criteria

Java project artifacts include, but are not limited to:
   jars, wars, rars, tlds, source, binary and document
   distributions, and licenses.

URI Components
==============

An absolute repository URI is written as follows:

  repository-uri = access-specifier "/" product-specifier "/"
                   version-specifier "/" artifact-specifier

For java project artifacts, artifact-specifier is:

  artifact-specifier = java-project-artifact
  java-project-artifact = java-artifact |
                          distribution-artifact |
                          signature-artifact |
                          signature-keys |
                          license-artifact

Java artifacts
--------------

Java artifacts include, but are not limited to, jars, wars, rars,
and tlds.

  java-artifact = jar-artifact | war-artifact| rar-artifact
                 | tld-artifact | path_segments
  jar-artifact = "jars" "/" versioned-artifact-name ".jar"
  war-artifact = "wars" "/" versioned-artifact-name ".war"
  rar-artifact = "rars" "/" versioned-artifact-name ".rar"
  tld-specifier = "tlds" "/" versioned-artifact-name ".tld"

  (path_segments is per http://www.ietf.org/rfc/rfc2396.txt)

Versioned artifact names
------------------------

Java and distribution artifacts include the project version:

  versioned-artifact-name = artifact-name "-" short-version [debug]
  artifact-name = pchar+
  short-version = version-name  ["-" timestamp]
  debug = "-dbg"

  (version-name and timestamp are per

http://nagoya.apache.org/wiki/apachewiki.cgi?ASFRepository/CommonBuildVersio
nSpecifier)
  (pchar is per http://www.ietf.org/rfc/rfc2396.txt)

Artifacts can indicate that they include debugging information
via the "-dbg" suffix.

E.g:
  ant-1.5.4.jar
  ant-1.5.4-20031113.1043.jar
  ant-1.5.4-dbg.jar


Distribution artifacts
----------------------

Distribution artifacts include binary, source, and documentation
distributions:

  distribution-artifact = binary-artifact | source-artifact
                          | doc-artifact

  binary-artifact = "binaries" "/" versioned-artifact-name
                    "-bin" "." arc-ext
  source-artifact = "source" "/" versioned-artifact-name
                     "-src" "." arc-ext
  doc-artifact = document-artifact | javadoc-artifact
  document-artifact = "docs" "/" versioned-artifact-name
                     "-doc" "." arc-ext
  javadoc-artifact = "docs" "/" versioned-artifact-name
                     "-javadoc" "." arc-ext

  arc-ext = "tar.gz" | "zip" | "bzip2" | ...

E.g:
  binaries/ant-1.5.4-bin.zip
  binaries/ant-1.5.4-dbg-bin.tar.gz
  source/ant-1.5.4-src.zip
  source/ant-1.5.4-src.tar.gz
  docs/ant-1.5.4-doc.zip
  docs/ant-1.5.4-javadoc.zip

Signatures
----------

An artifact may have an associated PGP, MD5, or SHA signature
artifact, located alongside it:

  signature-artifact-specifier = java-project-artifact "." sig-type
  sig-type = "pgp" | "md5" | "sha" | ...

E.g:
  http://repo.apache.org/apache/ant/1.5.4/jars/ant-1.5.4.jar.md5
  http://repo.apache.org/apache/ant/1.5.4/jars/ant-1.5.4.jar.pgp
  http://repo.apache.org/apache/ant/1.5.4/jars/ant-1.5.4.jar.sha

Where a signature has associated keys, these are specified by:
  signature-keys = sig-type "/" "KEYS"

E.g:
  http://repo.apache.org/apache/ant/1.5.4/pgp/KEYS

Licenses
--------

  license-specifier = "licenses" "/" license-name
  license-name = LICENSE.txt | path_segment

  (path_segment is per http://www.ietf.org/rfc/rfc2396.txt)

Rationale
=========

Artifacts in subdirectories
---------------------------

Each category of artifact in this proposal is required
to be located in its own directory, e.g:
  "jars/commons-cli-1.0.jar"
rather than in the root project version directory.

The alternative approach of placing each artifact in the
root makes repository navigation harder, particularly
for projects:
. which deploy with large numbers of artifacts
. which deploy artifacts other than those defined by this
  proposal.

Inclusion of version in artifact names
--------------------------------------

Java and distribution artifacts require that the version be
included in their names:

  versioned-artifact-name = artifact-name "-" short-version [debug]
  short-version = version-name  ["-" timestamp]

This ensures that it is immediately obvious to users what version of
an artifact they are using, subsequent to its download.

The optional timestamp indicates interim builds, as per:

http://nagoya.apache.org/wiki/apachewiki.cgi?ASFRepository/CommonBuildVersio
nSpecifier

It is assumed that MANIFEST.MF entries in artifacts will
include the versioned artifact name.


Tool support
============

Tools can unambigously locate an artifact within a project version
given the following criteria:

. artifact type
  Mandatory.

. artifact name
  Mandatory.

. debug information
  Optional.

. artifact version
  Mandatory for versioned artifacts, optional otherwise.
  May include interim build timestamp.

. archive type
  Mandatory for distribution artifacts, optional otherwise.

Example 1
---------

Given:
  type = "jar"
  name = "commons-cli"
  version = "1.1"
  debug = "false"

The URI fragment would be:
  "jars/commons-cli-1.1.jar"

The associated MD5 and PGP artifacts would be:
  "jars/commons-cli-1.1.jar.md5"
  "jars/commons-cli-1.1.jar.pgp"

Example 2
---------

Given:
  type = "jar"
  name = "commons-cli"
  version = "1.1-20031113.1043"
  debug = "true"

The URI fragment would be:
  "jars/commons-cli-1.1-20031113.1043-dbg.jar"

The associated MD5 and PGP artifacts would be:
  "jars/commons-cli-1.1-20031113.1043-dbg.jar.md5"
  "jars/commons-cli-1.1-20031113.1043-dbg.jar.pgp"

Example 3
---------

Given:
  type = "binary"
  name = "commons-cli"
  version = "1.1"
  debug = "false"
  arc-type = "tar.gz"

The URI fragment would be:
  "binaries/commons-cli-1.1-bin.tar.gz"

The associated MD5 and PGP artifacts would be:
  "binaries/commons-cli-1.1-bin.tar.gz.md5"
  "binaries/commons-cli-1.1-bin.tar.gz.pgp"


URI Examples
============

JARS
----

  http://repo.apache.org/apache/ant/1.5.4/jars/ant-1.5.4.jar
  http://repo.apache.org/apache/ant/1.5.4/jars/ant-1.5.4.jar.md5
  http://repo.apache.org/apache/ant/1.5.4/jars/ant-1.5.4-dbg.jar
  http://repo.apache.org/apache/ant/1.5.4/jars/ant-1.5.4-dbg.jar.md5

Binaries
--------

  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-bin.zip
  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-bin.zip.pgp
  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-dbg-bin.zip
  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-dbg-bin.zip.pgp
  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-bin.tar.gz
  http://repo.apache.org/apache/ant/1.5.4/binaries/ant-1.5.4-bin.tar.gz.pgp


Source
------

  http://repo.apache.org/apache/ant/1.5.4/source/ant-1.5.4-src.zip
  http://repo.apache.org/apache/ant/1.5.4/source/ant-1.5.4-src.zip.md5
  http://repo.apache.org/apache/ant/1.5.4/source/ant-1.5.4-src.tar.gz
  http://repo.apache.org/apache/ant/1.5.4/source/ant-1.5.4-src.tar.gz.pgp

Documentation
-------------

  http://repo.apache.org/apache/ant/1.5.4/docs/ant-1.5.4-doc.zip
  http://repo.apache.org/apache/ant/1.5.4/docs/ant-1.5.4-javadoc.zip

Licenses
--------

  http://repo.apache.org/apache/ant/1.5.4/licenses/LICENSE.txt

PGP keys
---------

  http://repo.apache.org/apache/ant/1.5.4/pgp/KEYS


Appendix
========

Changes from 0.1
----------------

. constrained the BNF

. clarified version inclusion in artifact names

. added doc and javadoc artifacts

. renamed pgp signature extension from ".asc" to ".pgp"

. moved pgp KEYS from project version root to "pgp/KEYS"



Mime
View raw message