net.dpml.transit
Class Artifact

java.lang.Object
  extended by net.dpml.transit.Artifact
All Implemented Interfaces:
Serializable, Comparable

public final class Artifact
extends Object
implements Serializable, Comparable

A utility class the handles validation of artifact style uri strings.

Version:
2.1.0
Author:
Digital Product Management Library
See Also:
Serialized Form

Field Summary
static String ARTIFACT
          Constant scheme name for the artifact protocol.
static String LINK
          Constant scheme name for the link protocol.
static String LOCAL
          Constant scheme name for the local protocol.
 
Method Summary
 int compareTo(Object object)
          Compare this artifact with another artifact.
static Artifact createArtifact(String uri)
          Creation of a new artifact instance using a supplied uri specification.
static Artifact createArtifact(String group, String name, String version, String type)
          Creation of a new artifact instance using a supplied group, name, version and type arguments.
static Artifact createArtifact(String scheme, String group, String name, String version, String type)
          Creation of a new artifact instance using a supplied group, name, version and type arguments.
static Artifact createArtifact(URI uri)
          Creation of a new artifact instance using a supplied uri specification.
 boolean equals(Object other)
          Compare this artifact with the supplied object for equality.
 String getGroup()
          Return the group identifier for the artifact.
 String getName()
          Return the name of the artifact.
 String getScheme()
          Return the protocol for the artifact.
 String getType()
          Return the type of the artifact.
 String getVersion()
          Return the posssibly null version identifier.
 int hashCode()
          Return the hashcode for the artifact.
 boolean isRecognized()
          Test if the artifact scheme is recognized.
static boolean isRecognized(URI uri)
          Test if the supplied uri is from the artifact family.
 String toString()
          Return a string representation of the artifact.
 URI toURI()
          Create an artifact url backed by the repository.
 URL toURL()
          Create an artifact url backed by the repository.
static URL toURL(URI uri)
          Construct a new URL form a given URI.
 URL toURL(URLStreamHandler handler)
          Create an artifact url backed by the repository.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ARTIFACT

public static final String ARTIFACT
Constant scheme name for the artifact protocol.

See Also:
Constant Field Values

LINK

public static final String LINK
Constant scheme name for the link protocol.

See Also:
Constant Field Values

LOCAL

public static final String LOCAL
Constant scheme name for the local protocol.

See Also:
Constant Field Values
Method Detail

createArtifact

public static final Artifact createArtifact(String uri)
                                     throws URISyntaxException,
                                            UnsupportedSchemeException,
                                            NullPointerException
Creation of a new artifact instance using a supplied uri specification. An artifact uri contains the protocol identifier, a type, a group designator, a name, and an optional version identifier.

The following represent valid artifact uri examples:

If there is a internal reference identifier which is marked by the exclamation mark followed by slash (!/) it will be stripped. The version part can be either before or after such identifier. Example;

   artifact:war:jmx-html/jmx-html#1.3!/images/abc.png
   artifact:war:jmx-html/jmx-html!/images/abc.png#1.3
  
The above uris will both be referencing artifact:war:jmx-html/jmx-html#1.3

Parameters:
uri - the artifact uri
Returns:
the new artifact
Throws:
URISyntaxException - if the supplied uri is not valid.
UnsupportedSchemeException - if the URI does not have "artifact" or "link" as its scheme.
NullPointerException - if the supplied uri argument is null

createArtifact

public static final Artifact createArtifact(URI uri)
                                     throws UnsupportedSchemeException,
                                            NullPointerException
Creation of a new artifact instance using a supplied uri specification. An artifact uri contains the protocol identifier, an optional type, a group designator, a name, and an optional version identifier.

The following represent valid artifact uri examples:

Parameters:
uri - the artifact uri
Returns:
the new artifact
Throws:
UnsupportedSchemeException - if the URI does not have "artifact" or "link" as its scheme.
NullPointerException - if the supplied uri argument is null

createArtifact

public static Artifact createArtifact(String group,
                                      String name,
                                      String version,
                                      String type)
                               throws NullPointerException
Creation of a new artifact instance using a supplied group, name, version and type arguments.

Parameters:
group - the artifact group identifier
name - the artifact name
version - the version
type - the type
Returns:
the new artifact
Throws:
NullPointerException - if any of the group, name or type arguments are null.

createArtifact

public static Artifact createArtifact(String scheme,
                                      String group,
                                      String name,
                                      String version,
                                      String type)
                               throws NullPointerException
Creation of a new artifact instance using a supplied group, name, version and type arguments.

Parameters:
scheme - the artifact scheme
group - the artifact group identifier
name - the artifact name
version - the version
type - the type
Returns:
the new artifact
Throws:
NullPointerException - if any of the group, name or type arguments are null.

toURL

public static URL toURL(URI uri)
                 throws MalformedURLException
Construct a new URL form a given URI. If the URI is a Transit URI the returned URL will be associated with the appropriate handler.

Parameters:
uri - the uri to convert
Returns:
the converted url
Throws:
MalformedURLException - if the url could not be created

isRecognized

public static boolean isRecognized(URI uri)
Test if the supplied uri is from the artifact family. Specificially the test validates that the supplied uri has a scheme corresponding to 'artifact', link', or 'local'.

Parameters:
uri - the uri to check
Returns:
true if thie uri is artifact based

getScheme

public final String getScheme()
Return the protocol for the artifact.

Returns:
the protocol scheme

getGroup

public final String getGroup()
Return the group identifier for the artifact. The group identifier is composed of a sequence of named separated by the '/' character.

Returns:
the group identifier

getName

public final String getName()
Return the name of the artifact.

Returns:
the artifact name

getType

public final String getType()
Return the type of the artifact.

Returns:
the artifact type

getVersion

public final String getVersion()
Return the posssibly null version identifier. The value of the version is an opaque string.

Returns:
the artifact version

isRecognized

public boolean isRecognized()
Test if the artifact scheme is recognized. Specificially the test validates that the artifact scheme corresponding to 'artifact', link', or 'local'.

Returns:
true if the uri scheme is recognized

toURL

public URL toURL()
Create an artifact url backed by the repository.

Returns:
the artifact url

toURL

public URL toURL(URLStreamHandler handler)
Create an artifact url backed by the repository.

Parameters:
handler - the protocol handler
Returns:
the artifact url

toURI

public URI toURI()
Create an artifact url backed by the repository.

Returns:
the artifact url

compareTo

public int compareTo(Object object)
              throws NullPointerException,
                     ClassCastException
Compare this artifact with another artifact. Artifact comparisom is based on a comparison of the string representation of the artifact with the string representation of the supplied object.

Specified by:
compareTo in interface Comparable
Parameters:
object - the object to compare with this instance
Returns:
the comparative order of the supplied object relative to this artifact
Throws:
NullPointerException - if the supplied object argument is null.
ClassCastException - if the supplied object is not an Artifact.

toString

public String toString()
Return a string representation of the artifact.

Overrides:
toString in class Object
Returns:
the artifact as a uri

equals

public boolean equals(Object other)
Compare this artifact with the supplied object for equality. This method will return true if the supplied object is an Artifact and has an equal uri.

Overrides:
equals in class Object
Parameters:
other - the object to compare with this instance
Returns:
TRUE if this artifact is equal to the supplied object

hashCode

public int hashCode()
Return the hashcode for the artifact.

Overrides:
hashCode in class Object
Returns:
the hashcode value