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"
