 |
CJAN Repository URI Specification version 0.3
This document is a proposed update to:
http://sourceforge.net/docman/display_doc.php?docid=8328&group_id=41872
@author Brian Tol - briant at imagegroup.com
@author Michael Davey - michael.davey at coderage.org
@version 0.3 (2004-04-30)
This document describes the CJAN naming convention. To make CJAN easier to use, we recommend the following naming convention when naming Jar files, however the convention is not compulsary for Jar files on CJAN.
repository-uri
An absolute repository URI is written as follows:
repository-uri = access-repository-uri | uuid-repository-uri
access-repository-uri = access-specifier "/" access-pva-specifier
access-pva-specifier = product-specifier "/" version-specifier "/" access-artifact-specifier
uuid-repository-uri = urn-specifier ":" uuid-artifact-specifier
URI examples:
urn:cjan:CJMD5-aa3b02390cf4fbd124e6dc16d03ca8cf00
urn:cjan:CJSHA1-eb5a29d0f7e081d9646751f9e0b1a103a1d05ac500
access-specifier
Access specifier is per Apache Repository URI Syntax Version 0.3 (a.ka. revision 24). A CJAN implementation MUST NOT use either earlier or later versions unless explicitly permitted in updates to this document.
Access specifier is used to fetch an artifact using an Internet-standard protocol. The access specifier determines the scheme, authority, and optional repository directory prefix. There is currently no requirement for ftp, scp or file based access - only http is supported:
access-specifier = http-access-specifier
http-access-specifier = "http://" authority "/" [directory "/"]
directory = path_segments
(authority and path_segments are per http://www.ietf.org/rfc/rfc2396.txt)
<directory> is used when the repository cannot be located at the root of an absolute URI.
URI examples:
http://repo.cjan.org/
http://www.cjan.org/repository
urn-specifier
URN specifier is used to search for and fetch an artifact using the CJAN search protocol. The URN specifier determines the sceme and authority prefix:
urn-specifier = scheme ":" authority
scheme = "urn"
authority = "cjan"
Note that the scheme does not specify the protocol to use. The CJAN search protocol will be defined elsewhere and will include details of how to transform a uuid-repository-uri into access-repository-uris (there is a one-to-many relationship as the same artifact may be hosted on multiple URLs and clients may choose to download different chunks of the file from different URLs, in parallel).
product-specifier
Product specifier is per Apache Repository URI Syntax Version 0.3 (a.ka. revision 24). A CJAN implementation MUST NOT use either earlier or later versions unless explicitly permitted in updates to this document.
The product specifier specifies the organisation and project:
product-specifier = organisation "/" project
organisation = pchar+
project = pchar+
(pchar is per http://www.ietf.org/rfc/rfc2396.txt)
<organisation> is the organisation name. It is arbitrary, but should be globally unique. It could be the domain name, reverse domain name, or simply the name of the organisation. Individuals may choose to create a unique name based upon their website or email address. E.g:
"apache.org", "org.apache", "apache"
"java.sun.com", "com.sun.java", "sun"
"adambuckley.net", "net.adambuckley", "adambuckley"
<project> is the project name. It is unique within an organisation. If your artifact is a sub-project of a larger project, or is unique in some way, include that information in the name. For example, if your artifact is part of the "bar" project, which is a sub-project of "foo", then your package would be named "foo-bar". E.g:
"ldap", "jndi", "maven", "commons-logging".
URI examples:
http://repo.cjan.org/apache.org/ant
http://repo.cjan.org/apache.org/maven
http://repo.cjan.org/java.sun.com/jndi
http://repo.cjan.org/org.apache/ant
http://repo.cjan.org/org.apache/maven
http://repo.cjan.org/com.sun.java/jndi
http://repo.cjan.org/apache/ant
http://repo.cjan.org/apache/maven
http://repo.cjan.org/sun/jndi
version-specifier
version-specifier = version
<version> is the version number for your jar. The version format is opaque at the time of writing, but will probably be the format specified by the Apache Depot Version project and API.
The original (draft) format is defined below:
version = digit dot digit dot digit [ "-" type ] [dbg]
digit = "0" - "9"
dot = "."
type = "src" | "bin" | "doc"
dbg = "-debug"
Where:
* [-src|-bin|-doc] is the type of your jar, normally -src or -bin for java source or class file distributions respectively. For small projects where there is a single distribution including the source, classes and documentation, the distribution type may be obmitted
URI examples:
* 1.4.3-src - Version 1.4.3. Source distribution
* 0.3.0-doc - Version 0.3.0. Documentation only
* 2.3.1 - Version 2.3.1. Distribution contains source, classes and documentation
access-artifact-specifier
The access artifact specifier should be treated as opaque for the moment. The original format is defined below but it is likely that CJAN will adopt the artifact specifiers provided by the Apache Depot project.
access-artifact-specifier = name "-" version-specifier ext [ct]
name = pchar+
ext = ".jar" | ".war" | ".ear" | ".bar" | ".rar" | ".block" | ".tar"
ct = ".gz" | ".bz2" | ".Z"
<version-specifier> is defined above.
URI examples:
* <name>-<version>[-src|-bin|-doc].jar
* foo-bar-optional-1.4.3-src.jar - Version 1.4.3 of the optional jar for the foo-bar project. Source distribution
* ray-0.3.0-doc.jar - Version 0.3.0 of the jar for the ray project. Documentation only
* fred-util-2.3.1.jar - Version 2.3.1 of the jar for the FredUtil project. Distribution contains source, classes and documentation
uuid-artifact-specifier
uuid = md5-uuid | sha-uuid
md5-uuid = cjan-md5 "-" md5-fingerprint md5-version
cjan-md5 = "CJMD5"
md5-version = "00"
sha-uuid = cjan-sha "-" sha-fingerprint sha-version
cjan-sha = "CJSHA1"
sha-version = "00"
<;uuid> specifies the format for the universally unique artifact id. The algorithm is specified
by the CJAN JarDigest? API (briefly, it is either an MD5 or SHA1 digest on selected contents of the
artifact).
<md5-fingerprint> is a 128-bit value represented as a 32 character hexadecimal string.
<sha-fingerprint> is a 160-bit value represented as a 40 character hexadecimal string.
URI examples:
urn:cjan:CJMD5-aa3b02390cf4fbd124e6dc16d03ca8cf00
urn:cjan:CJSHA1-eb5a29d0f7e081d9646751f9e0b1a103a1d05ac500
User friendly:
Authors are encouraged to support '-version' and '-fullversion' arguments to jar files so that 'java my-util.jar -version' or simply './my-util.jar -version' prints out the version number. The information should be obtained from the jars' manifest.
'-version' should print a user-friendly version number, for instance, 'my-util, version "0.0.1"'.
'-fullversion' should print a unique version message, for instance '0.0.1-b23'
Notes:
* To make CJAN easier to use, we recommend naming Java artifacts to comply with access-artifact-specifier, however CJAN automaticall converts file names to urn-artifact-specifier when uploading and to access-artifact-specifier when downloading.
* Jar names adhereing to this convention MUST only contain ascii characters from the lowercase alphabet a-z, digits 0-9, dot '.', hyphen '-' and underscore '_'. The underscore should be avoided
* How to represent beta versions? 1.4.0b where b indicates beta version or GNU/Linux version whereby if the middle digit is odd it is a beta version, otherwise it is a stable version. To be decided
Changes:
2001-12-14 briant - Original version on SF.net
2002-07-30 michaed - Moved version to directory name
2004-04-29 michaed - Added BNF notation and references to Apache documentation
2004-05-20 michaed - Added access-pva-specifier, modified definition of version
|