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
jar-artifact = "jars" "/" versioned-artifact-name ".jar"
war-artifact = "wars" "/" versioned-artifact-name ".war"
rar-artifact = "rars" "/" versioned-artifact-name ".rar"
ear-artifact = "ears" "/" versioned-artifact-name ".ear"
bar-artifact = "bars" "/" versioned-artifact-name ".bar"
block-artifact = "blocks" "/" versioned-artifact-name ".block"
tld-specifier = "tlds" "/" versioned-artifact-name ".tld"
javadoc-artifact = "docs" "/" versioned-artifact-name
"-javadoc" "." arc-ext
arc-ext = "tar.gz" | "zip" | "bzip2" | ...
Versioned artifact names
Java 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 Self: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-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: /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"