Java Artifact Specifier
Version 0.3
Overview
This proposal extends the URI Syntax proposal: /URISyntax
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 artifact using a set of known criteria
Relationship to other proposals
It is recommended, but not required, that this proposal be used in conjunction with the Common Build Version Specifier proposal: /CommonBuildVersionSpecifier
Source and binary distribution artifacts are covered by the Common Distribution Artifact Specifier proposal: /CommonDistributionArtifactSpecifier
Signature artifacts (pgp keys, MD5 checksums etc) are covered by the Signature Artifact Specifier: /SignatureArtifactSpecifier
License artifacts are covered by the License Artifact Specifier proposal: /LicenseArtifactSpecifier
URI Components
An absolute repository URI is written as follows:
{{{ repository-uri = access-specifier "/" product-specifier "/"
- version-specifier "/" artifact-specifier }}}
For java projects, artifact-specifier is defined as:
{{{ artifact-specifier = java-artifact-specifier
- java-artifact-specifier = jar-artifact | war-artifact| rar-artifact
- | ear-artifact | bar-artifact | block-artifact | tld-artifact | javadoc-artifact
- "-javadoc" "." arc-ext
Versioned artifact names
Java artifacts include the project version:
{{{ versioned-artifact-name = artifact-name "-" short-versiondebug
- artifact-name = pchar+ short-version = version-name ["-" timestamp] debug = "-dbg"
(version-name and timestamp are per /CommonBuildVersionSpecifier) (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 }}}
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 document artifacts require that the version be included in their names:
{{{ versioned-artifact-name = artifact-name "-" short-versiondebug
- 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: /CommonBuildVersionSpecifier
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. May include interim build timestamp.
- archive type
- Mandatory for javadoc 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" }}}
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-dbg.jar http://repo.apache.org/apache/ant/1.5.4/jars/ant-optional-1.5.4.jar http://repo.apache.org/apache/ant/1.5.4/jars/ant-optional-1.5.4-dbg.jar }}}
Documentation
http://repo.apache.org/apache/ant/1.5.4/docs/ant-1.5.4-javadoc.zip
Project Example
The following URIs show the repository structure for version 1.5.4 of Ant, when this proposal is used in conjunction with the following proposals:
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.jar.pgp 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 http://repo.apache.org/apache/ant/1.5.4/jars/ant-1.5.4-dbg.jar.pgp http://repo.apache.org/apache/ant/1.5.4/jars/ant-optional-1.5.4.jar http://repo.apache.org/apache/ant/1.5.4/jars/ant-optional-1.5.4.jar.md5 http://repo.apache.org/apache/ant/1.5.4/jars/ant-optional-1.5.4.jar.pgp http://repo.apache.org/apache/ant/1.5.4/jars/ant-optional-1.5.4-dbg.jar http://repo.apache.org/apache/ant/1.5.4/jars/ant-optional-1.5.4-dbg.jar.md5 http://repo.apache.org/apache/ant/1.5.4/jars/ant-optional-1.5.4-dbg.jar.pgp }}}
Documentation
{{{ http://repo.apache.org/apache/ant/1.5.4/docs/ant-1.5.4-javadoc.zip
http://repo.apache.org/apache/ant/1.5.4/docs/ant-1.5.4-javadoc.zip.md5 http://repo.apache.org/apache/ant/1.5.4/docs/ant-1.5.4-javadoc.zip.pgp }}}
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.md5 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.md5 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.md5 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.zip.pgp 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.md5 http://repo.apache.org/apache/ant/1.5.4/source/ant-1.5.4-src.tar.gz.pgp }}}
Licenses
http://repo.apache.org/apache/ant/1.5.4/license/LICENSE.txt
PGP keys
http://repo.apache.org/apache/ant/1.5.4/pgp/KEYS
Appendix
Changes from 0.2
moved source and binary distributions to Common Distribution Artifact Specifier: /CommonDistributionArtifactSpecifier
moved signature artifacts to Signature Artifact Specifier: /SignatureArtifactSpecifier
moved license artifacts to License Artifact Specifier: /LicenseArtifactSpecifier
- added ear-artifact
- removed doc-artifact, as its not specific to java projects.
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"