com.limegroup.gnutella
Class URN

java.lang.Object
  extended bycom.limegroup.gnutella.URN
All Implemented Interfaces:
HTTPHeaderValue, java.io.Serializable

public final class URN
extends java.lang.Object
implements HTTPHeaderValue, java.io.Serializable

This class represents an individual Uniform Resource Name (URN), as specified in RFC 2141. This does extensive validation of URNs to make sure that they are valid, with the factory methods throwing excpeptions when the arguments do not meet URN syntax. This does not perform rigorous verification of the SHA1 values themselves. This class is immutable.

See Also:
UrnCache, FileDesc, UrnType, Serializable, Serialized Form

Field Summary
static URN INVALID
          A constant invalid URN that classes can use to represent an invalid URN.
 
Method Summary
static URN createSHA1Urn(java.io.File file)
          Creates a new URN instance with a SHA1 hash.
static URN createSHA1Urn(java.lang.String urnString)
          Creates a new URN instance from the specified string.
static URN createSHA1UrnFromHttpRequest(java.lang.String requestLine)
          Creates a URN instance from the specified HTTP request line.
static URN createSHA1UrnFromUriRes(java.lang.String sha1String)
          Convenience method for creating a URN instance from a string in the form:
static URN createSHA1UrnFromURL(java.net.URL url)
          Convenience method for creating a SHA1 URN from a URL.
 boolean equals(java.lang.Object o)
          Checks for URN equality.
static int getHashingProgress(java.io.File file)
          Gets the amount of bytes hashed for a file that is being hashed.
 UrnType getUrnType()
          Returns the UrnType instance for this URN.
 int hashCode()
          Overrides the hashCode method of Object to meet the contract of hashCode.
 java.lang.String httpStringValue()
          Returns a string representation of the HTTP header value for this class.
 boolean isSHA1()
          Returns whether or not this URN is a SHA1 URN.
static boolean isUrn(java.lang.String urnString)
          Returns whether or not the URN_STRING argument is a valid URN string, as specified in RFC 2141.
 java.lang.String toString()
          Overrides toString to return the URN string.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

INVALID

public static final URN INVALID
A constant invalid URN that classes can use to represent an invalid URN.

Method Detail

getHashingProgress

public static int getHashingProgress(java.io.File file)
Gets the amount of bytes hashed for a file that is being hashed. Returns -1 if the file is not being hashed at all.


createSHA1Urn

public static URN createSHA1Urn(java.io.File file)
                         throws java.io.IOException,
                                java.lang.InterruptedException
Creates a new URN instance with a SHA1 hash.

Parameters:
file - the File instance to use to create a URN
Returns:
a new URN instance
Throws:
IOException - if there was an error constructing the URN
InterruptedException - if the calling thread was interrupted while hashing. (This method can take a while to execute.)
java.io.IOException
java.lang.InterruptedException

createSHA1Urn

public static URN createSHA1Urn(java.lang.String urnString)
                         throws java.io.IOException
Creates a new URN instance from the specified string. The resulting URN can have any Namespace Identifier and any Namespace Specific String.

Parameters:
urnString - a string description of the URN. Typically this will be a SHA1 containing a 32-character value, e.g., "urn:sha1:GLSTHIPQGSSZTS5FJUPAKPZWUGYQYPFB".
Returns:
a new URN instance
Throws:
IOException - urnString was malformed or an unsupported type
java.io.IOException

createSHA1UrnFromURL

public static URN createSHA1UrnFromURL(java.net.URL url)
                                throws java.io.IOException
Convenience method for creating a SHA1 URN from a URL. For the url to work, its getFile method must return the SHA1 urn in the form:

/uri-res/N2R?urn:sha1:SHA1URNHERE

Parameters:
url - the URL to extract the URN from
Throws:
IOException - if there is an error reading the URN from the URL
java.io.IOException

createSHA1UrnFromUriRes

public static URN createSHA1UrnFromUriRes(java.lang.String sha1String)
                                   throws java.io.IOException
Convenience method for creating a URN instance from a string in the form:

/uri-res/N2R?urn:sha1:PLSTHIPQGSSZTS5FJUPAKUZWUGYQYPFB

Throws:
java.io.IOException

createSHA1UrnFromHttpRequest

public static URN createSHA1UrnFromHttpRequest(java.lang.String requestLine)
                                        throws java.io.IOException
Creates a URN instance from the specified HTTP request line. The request must be in the standard from, as specified in RFC 2169. Note that com.limegroup.gnutella.Acceptor parses out the first word in the request, such as "GET" or "HEAD."

Parameters:
requestLine - the URN HTTP request of the form specified in RFC 2169, for example:

/uri-res/N2R?urn:sha1:PLSTHIPQGSSZTS5FJUPAKUZWUGYQYPFB HTTP/1.1

Returns:
a new URN instance from the specified request, or null if no URN could be created
Throws:
java.io.IOException
See Also:
Acceptor

getUrnType

public UrnType getUrnType()
Returns the UrnType instance for this URN.

Returns:
the UrnType instance for this URN

httpStringValue

public java.lang.String httpStringValue()
Description copied from interface: HTTPHeaderValue
Returns a string representation of the HTTP header value for this class.

Specified by:
httpStringValue in interface HTTPHeaderValue
Returns:
a string representation of the HTTP header value for this class

isUrn

public static boolean isUrn(java.lang.String urnString)
Returns whether or not the URN_STRING argument is a valid URN string, as specified in RFC 2141.

Parameters:
urnString - the urn string to check for validity
Returns:
true if the string argument is a URN, false otherwise

isSHA1

public boolean isSHA1()
Returns whether or not this URN is a SHA1 URN. Note that a bitprint URN will return false, even though it contains a SHA1 hash.

Returns:
true if this is a SHA1 URN, false otherwise

equals

public boolean equals(java.lang.Object o)
Checks for URN equality. For URNs to be equal, their URN strings must be equal.

Parameters:
o - the object to compare against
Returns:
true if the URNs are equal, false otherwise

hashCode

public int hashCode()
Overrides the hashCode method of Object to meet the contract of hashCode. Since we override equals, it is necessary to also override hashcode to ensure that two "equal" instances of this class return the same hashCode, less we unleash unknown havoc on the hash-based collections.

Returns:
a hash code value for this object

toString

public java.lang.String toString()
Overrides toString to return the URN string.

Returns:
the string representation of the URN