FreenetURI (fred API)

java.lang.Object
- freenet.keys.FreenetURI

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<FreenetURI>
```
public class FreenetURI
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Comparable<FreenetURI>, java.io.Serializable
```
Note that the metadata pairs below are not presently supported. They are supported by the old (0.5) code however. FreenetURI handles parsing and creation of the Freenet URI format, defined as follows:
freenet:[KeyType@]RoutingKey,CryptoKey[,n1=v1,n2=v2,...][/docname][/metastring]

where KeyType is the TLA of the key (currently USK, SSK, KSK, or CHK). If omitted, KeyType defaults to KSK. BUT: CHKs don't support or require a docname. KSKs and SSKs do. Therefore CHKs go straight into metastrings.

For KSKs, the string keyword (docname) takes the RoutingKey position and the remainder of the fields are inapplicable (except metastring). Examples: freenet:KSK@foo/bar freenet:KSK@test.html freenet:test.html.

RoutingKey is the modified Base64 encoded key value. CryptoKey is the modified Base64 encoded decryption key.

Following the RoutingKey and CryptoKey there may be a series of name=value pairs representing URI meta-information.

The docname is only meaningful for SSKs, and is hashed with the PK fingerprint to get the key value.

The metastring is meant to be passed to the metadata processing systems that act on the retrieved document.

When constructing a FreenetURI with a String argument, it is now legal for CHK keys to have a '.extension' tail, eg 'CHK@blahblahblah.html'. The constructor will simply chop off at the first dot.
REDFLAG: Old code has a FieldSet, and the ability to put arbitrary metadata in through name/value pairs. Do we want this? WARNING: Changing non-transient members on classes that are Serializable can result in restarting downloads or losing uploads.

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static FreenetURI`	`EMPTY_CHK_URI`
`static java.util.Comparator<FreenetURI>`	`FAST_COMPARATOR`
`protected java.lang.String`	`toStringCache`
`protected static java.util.regex.Pattern`	`URI_PREFIX`

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`FreenetURI()`
	`FreenetURI(byte[] pubKeyHash, byte[] cryptoKey, byte[] extra, java.lang.String siteName, long suggestedEdition2)` USK constructor from components.
	`FreenetURI(FreenetURI uri)`
	`FreenetURI(java.lang.String URI)`
	`FreenetURI(java.lang.String URI, boolean noTrim)` Create a FreenetURI from its string form.
	`FreenetURI(java.lang.String keyType, java.lang.String docName)`
	`FreenetURI(java.lang.String keyType, java.lang.String docName, byte[] routingKey, byte[] cryptoKey, byte[] extra2)`
	`FreenetURI(java.lang.String keyType, java.lang.String docName, java.lang.String[] metaStr, byte[] routingKey, byte[] cryptoKey, byte[] extra2)`
	`FreenetURI(java.lang.String keyType, java.lang.String docName, java.lang.String[] metaStr, byte[] routingKey, byte[] cryptoKey, byte[] extra2, long suggestedEdition)`
	`FreenetURI(java.lang.String keyType, java.lang.String docName, java.lang.String metaStr, byte[] routingKey, byte[] cryptoKey)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`FreenetURI`	`addMetaStrings(java.util.List<java.lang.String> metaStrings)` Returns a copy of this URI with these meta strings appended.
`FreenetURI`	`addMetaStrings(java.lang.String[] strs)` Returns a copy of this URI with these meta strings appended.
`void`	`checkInsertURI()` Throw an InsertException if we have any meta-strings.
`static void`	`checkInsertURI(FreenetURI uri)` Throw an InsertException if the argument has any meta-strings.
`FreenetURI`	`clone()`
`int`	`compareTo(FreenetURI o)`
`void`	`decompose()` Dump the individual components of the key to System.out.
`FreenetURI`	`deriveRequestURIFromInsertURI()` If this object is a USK/SSK insert URI, this function computes the request URI which belongs to it.
`FreenetURI`	`dropLastMetaStrings(int i)` Create a new URI with the last few meta-strings dropped.
`boolean`	`equals(java.lang.Object o)`
`boolean`	`equalsKeypair(FreenetURI u2)` Is the keypair (the routing key and crypto key) the same as the given key?
`static FreenetURI`	`fromFullBinaryKey(byte[] buf)` Create a FreenetURI from the binary form of the key.
`static FreenetURI`	`generateRandomCHK(java.util.Random rand)`
`java.lang.String[]`	`getAllMetaStrings()` Get all the meta strings.
`byte[]`	`getCryptoKey()` Get the crypto key.
`java.lang.String`	`getDocName()` Get the document name.
`long`	`getEdition()` Get the edition number, if the key is a USK or a USK converted to an SSK.
`byte[]`	`getExtra()` Get the extra bytes.
`java.lang.String`	`getGuessableKey()`
`java.lang.String`	`getKeyType()` Get the key type.
`java.lang.String`	`getMetaString()` Get the first meta-string.
`java.lang.String`	`getPreferredFilename()` Generate a suggested filename for the URI.
`byte[]`	`getRoutingKey()` Get the routing key.
`long`	`getSuggestedEdition()` Get suggested edition.
`int`	`hashCode()`
`boolean`	`hasMetaStrings()` Are there any meta-strings?
`FreenetURI`	`intern()` Optimize for memory.
`boolean`	`isCHK()` Is this key a CHK?
`boolean`	`isKSK()` Is this key a KSK?
`boolean`	`isSSK()` Is this key an SSK?
`boolean`	`isSSKForUSK()` Could this SSK be the result of sskForUSK()?
`boolean`	`isUSK()` Is this key a USK?
`java.lang.String`	`lastMetaString()` Get the last meta string.
`java.util.ArrayList<java.lang.String>`	`listMetaStrings()` Get the meta strings as an ArrayList.
`static void`	`main(java.lang.String[] args)` Run this class to decompose the argument.
`FreenetURI`	`popMetaString()` Returns a copy of this URI with the first meta string removed.
`FreenetURI`	`pushMetaString(java.lang.String name)` Returns a copy of this URI with the given string appended as a meta-string.
`static FreenetURI`	`readFullBinaryKey(java.io.DataInputStream dis)` Create a FreenetURI from the binary form of the key, read from a stream, with no length.
`static FreenetURI`	`readFullBinaryKeyWithLength(java.io.DataInputStream dis)` Read the binary form of a key, preceded by a short for its length.
`FreenetURI`	`setDocName(java.lang.String name)` Returns a copy of this URI with a new Document name set.
`FreenetURI`	`setKeyType(java.lang.String newKeyType)` Returns a new FreenetURI with a new key type.
`FreenetURI`	`setMetaString(java.lang.String[] newMetaStr)` Returns a copy of this URI with new meta-strings.
`FreenetURI`	`setRoutingKey(byte[] newRoutingKey)` Returns a new FreenetURI with a new routing key.
`FreenetURI`	`setSuggestedEdition(long newEdition)` Returns a new FreenetURI with a new suggested edition number.
`FreenetURI`	`sskForUSK()` Convert a USK into an SSK by appending "-" and the suggested edition to the document name and changing the key type.
`java.lang.String`	`toACIIString()` Deprecated. Use `toASCIIString()` instead
`java.lang.String`	`toASCIIString()` Get the FreenetURI as a pure ASCII string, any non-english characters as well as any dangerous characters are encoded.
`java.net.URI`	`toRelativeURI()` Convert to a relative URI in the form of a URI (/KSK@gpl.txt etc).
`java.lang.String`	`toShortString()` Encode to a user-friendly, incomplete string with ...
`java.lang.String`	`toString()` toString() is equivalent to toString(false, false) but is cached.
`java.lang.String`	`toString(boolean prefix, boolean pureAscii)` Get the FreenetURI as a string.
`java.net.URI`	`toURI(java.lang.String basePath)` Convert to a relative URI in the form of a URI, with the base path not necessarily /.
`FreenetURI`	`uskForSSK()` Convert an SSK into a USK, if possible.
`void`	`writeFullBinaryKeyWithLength(java.io.DataOutputStream dos)` Write a binary representation of this URI, with a short length, so it can be passed over if necessary.
`static void`	`writeFullBinaryKeyWithLength(FreenetURI uri, java.io.DataOutputStream dos)` Write either a null or a FreenetURI.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - EMPTY_CHK_URI
```
public static final FreenetURI EMPTY_CHK_URI
```
  - URI_PREFIX
```
protected static final java.util.regex.Pattern URI_PREFIX
```
  - toStringCache
```
protected java.lang.String toStringCache
```
  - FAST_COMPARATOR
```
public static final java.util.Comparator<FreenetURI> FAST_COMPARATOR
```
- Constructor Detail
  - FreenetURI
```
public FreenetURI(FreenetURI uri)
```
  - FreenetURI
```
public FreenetURI(java.lang.String keyType,
                  java.lang.String docName)
```
  - FreenetURI
```
public FreenetURI(java.lang.String keyType,
                  java.lang.String docName,
                  byte[] routingKey,
                  byte[] cryptoKey,
                  byte[] extra2)
```
  - FreenetURI
```
public FreenetURI(java.lang.String keyType,
                  java.lang.String docName,
                  java.lang.String metaStr,
                  byte[] routingKey,
                  byte[] cryptoKey)
```
  - FreenetURI
```
public FreenetURI(java.lang.String keyType,
                  java.lang.String docName,
                  java.lang.String[] metaStr,
                  byte[] routingKey,
                  byte[] cryptoKey,
                  byte[] extra2)
```
  - FreenetURI
```
public FreenetURI(java.lang.String keyType,
                  java.lang.String docName,
                  java.lang.String[] metaStr,
                  byte[] routingKey,
                  byte[] cryptoKey,
                  byte[] extra2,
                  long suggestedEdition)
```
  - FreenetURI
```
public FreenetURI(java.lang.String URI)
           throws java.net.MalformedURLException
```
    Throws:
    
    java.net.MalformedURLException
  - FreenetURI
```
public FreenetURI(java.lang.String URI,
                  boolean noTrim)
           throws java.net.MalformedURLException
```
    Create a FreenetURI from its string form. May or may not have a freenet: prefix.
    
    Throws:
    
    java.net.MalformedURLException - If the string could not be parsed.
  - FreenetURI
```
public FreenetURI(byte[] pubKeyHash,
                  byte[] cryptoKey,
                  byte[] extra,
                  java.lang.String siteName,
                  long suggestedEdition2)
```
    USK constructor from components.
  - FreenetURI
```
protected FreenetURI()
```
- Method Detail
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - equalsKeypair
```
public boolean equalsKeypair(FreenetURI u2)
```
    Is the keypair (the routing key and crypto key) the same as the given key?
    
    Returns:
    
    False if there is no routing key or no crypto key (CHKs, SSKs, USKs have them, KSKs don't), or if the keys don't have the same crypto key and routing key.
  - clone
```
public final FreenetURI clone()
```
    Overrides:
    
    clone in class java.lang.Object
  - intern
```
public FreenetURI intern()
```
    Optimize for memory.
  - decompose
```
public void decompose()
```
    Dump the individual components of the key to System.out.
  - getGuessableKey
```
public java.lang.String getGuessableKey()
```
  - getDocName
```
public java.lang.String getDocName()
```
    Get the document name. For a KSK this is everything from the @ to the first slash or the end of the key. For an SSK this is everything from the slash to the next slash or the end of the key. CHKs don't have a doc name, they only have meta strings.
  - getMetaString
```
public java.lang.String getMetaString()
```
    Get the first meta-string. This is just after the main part of the key and the doc name. Meta-strings are directory (manifest) lookups delimited by /'es after the main key and the doc name if any.
  - lastMetaString
```
public java.lang.String lastMetaString()
```
    Get the last meta string. Meta-strings are directory (manifest) lookups after the main key and the doc name if any. So the last meta string, if there is one, is from the last / to the end of the uri i.e. usually the filename.
  - getAllMetaStrings
```
public java.lang.String[] getAllMetaStrings()
```
    Get all the meta strings. Meta strings are directory (manifest) lookups after the main key and the doc name if any. Examples: CHK@blah,blah,blah/filename This has a routing key, a crypto key, extra bytes, no document name, and one meta string "filename" SSK@blah,blah,blah/docname/dir/subdir/filename This has a routing key, a crypto key, extra bytes, a document name, and three meta strings "dir", "subdir" and "filename". The SSK including the docname is turned into a low level Freenet key, which we fetch. This will produce a metadata document containing a manifest, within which we look up "dir". This either gives us another metadata document directly, or a redirect if the dir is inserted separately. And so on. If it's a container, the files will be stored, with the metadata, in the container (tar.bz2 or whatever); the metadata fetched by SSK@blah,blah,blah/docname will say that there is a container and explain how to fetch it. KSK@gpl.txt This has no routing key, no crypto key, and no meta strings (but KSKs *can* have meta strings), but it has a document name.
  - hasMetaStrings
```
public boolean hasMetaStrings()
```
    Are there any meta-strings?
  - getRoutingKey
```
public byte[] getRoutingKey()
```
    Get the routing key. This is the first part of the key after the @ for CHKs, SSKs and USKs. For purposes of FreenetURI, KSKs do not have a routing key. For CHKs, this is ultimately derived from the hash of the encrypted data; for SSKs it is the hash of the public key.
  - getCryptoKey
```
public byte[] getCryptoKey()
```
    Get the crypto key. This is the second part of the key after the @ for CHKs, SSKs and USKs. For purposes of FreenetURI, KSKs do not have a crypto key. For CHKs, this is derived from the hash of the *original* plaintext data; for SSKs it is a separate key for decryption. The crypto key is kept on the requesting node and is not sent over the network - but of course many freesites and other documents on the network include URIs which do include crypto keys.
  - getKeyType
```
public java.lang.String getKeyType()
```
    Get the key type. CHK, SSK, KSK or USK. Upper case, we normally use the constants.
  - popMetaString
```
public FreenetURI popMetaString()
```
    Returns a copy of this URI with the first meta string removed.
  - dropLastMetaStrings
```
public FreenetURI dropLastMetaStrings(int i)
```
    Create a new URI with the last few meta-strings dropped.
    
    Parameters:
    
    i - The number of meta-strings to drop.
    
    Returns:
    
    A new FreenetURI with the specified number of meta-strings removed from the end.
  - pushMetaString
```
public FreenetURI pushMetaString(java.lang.String name)
```
    Returns a copy of this URI with the given string appended as a meta-string.
  - addMetaStrings
```
public FreenetURI addMetaStrings(java.lang.String[] strs)
```
    Returns a copy of this URI with these meta strings appended.
  - addMetaStrings
```
public FreenetURI addMetaStrings(java.util.List<java.lang.String> metaStrings)
```
    Returns a copy of this URI with these meta strings appended.
  - setDocName
```
public FreenetURI setDocName(java.lang.String name)
```
    Returns a copy of this URI with a new Document name set.
  - setMetaString
```
public FreenetURI setMetaString(java.lang.String[] newMetaStr)
```
    Returns a copy of this URI with new meta-strings.
  - toString
```
public java.lang.String toString()
```
    toString() is equivalent to toString(false, false) but is cached.
    
    Overrides:
    
    toString in class java.lang.Object
  - toACIIString
```
@Deprecated
public java.lang.String toACIIString()
```
    Deprecated. Use toASCIIString() instead
  - toASCIIString
```
public java.lang.String toASCIIString()
```
    Get the FreenetURI as a pure ASCII string, any non-english characters as well as any dangerous characters are encoded.
    
    Returns:
  - toString
```
public java.lang.String toString(boolean prefix,
                                 boolean pureAscii)
```
    Get the FreenetURI as a string.
    
    Parameters:
    
    prefix - Whether to include the freenet: prefix.
    
    pureAscii - If true, encode any non-english characters. If false, only encode dangerous characters (slashes e.g.).
  - toShortString
```
public java.lang.String toShortString()
```
    Encode to a user-friendly, incomplete string with ... replacing some of the base64. Allow spaces, foreign chars etc.
  - main
```
public static void main(java.lang.String[] args)
                 throws java.lang.Exception
```
    Run this class to decompose the argument.
    
    Throws:
    
    java.lang.Exception
  - getExtra
```
public byte[] getExtra()
```
    Get the extra bytes. SSKs and CHKs have extra bytes, these come after the second comma, and specify encryption and hashing algorithms etc.
  - listMetaStrings
```
public java.util.ArrayList<java.lang.String> listMetaStrings()
```
    Get the meta strings as an ArrayList.
  - readFullBinaryKeyWithLength
```
public static FreenetURI readFullBinaryKeyWithLength(java.io.DataInputStream dis)
                                              throws java.io.IOException
```
    Read the binary form of a key, preceded by a short for its length.
    
    Throws:
    
    java.io.IOException
  - fromFullBinaryKey
```
public static FreenetURI fromFullBinaryKey(byte[] buf)
                                    throws java.io.IOException
```
    Create a FreenetURI from the binary form of the key.
    
    Throws:
    
    java.io.IOException
  - readFullBinaryKey
```
public static FreenetURI readFullBinaryKey(java.io.DataInputStream dis)
                                    throws java.io.IOException
```
    Create a FreenetURI from the binary form of the key, read from a stream, with no length.
    
    Throws:
    
    java.net.MalformedURLException - If there was a format error in the data.
    
    java.io.IOException - If a read error occurred
  - writeFullBinaryKeyWithLength
```
public static void writeFullBinaryKeyWithLength(FreenetURI uri,
                                                java.io.DataOutputStream dos)
                                         throws java.io.IOException
```
    Write either a null or a FreenetURI.
    
    Throws:
    
    java.io.IOException
  - writeFullBinaryKeyWithLength
```
public void writeFullBinaryKeyWithLength(java.io.DataOutputStream dos)
                                  throws java.io.IOException
```
    Write a binary representation of this URI, with a short length, so it can be passed over if necessary.
    
    Parameters:
    
    dos - The stream to write to.
    
    Throws:
    
    java.net.MalformedURLException - If the key could not be written because of inconsistencies or other problems in the key itself.
    
    java.io.IOException - If an error occurred while writing the key.
  - getSuggestedEdition
```
public long getSuggestedEdition()
```
    Get suggested edition. Only valid for USKs.
  - getPreferredFilename
```
public java.lang.String getPreferredFilename()
```
    Generate a suggested filename for the URI. This may be constructed from more than one part of the URI e.g. SSK@blah,blah,blah/sitename/ might return sitename. The returned string will already have been through FileUtil.sanitize().
  - setSuggestedEdition
```
public FreenetURI setSuggestedEdition(long newEdition)
```
    Returns a new FreenetURI with a new suggested edition number. Note that the suggested edition number is only valid for USKs.
  - setKeyType
```
public FreenetURI setKeyType(java.lang.String newKeyType)
```
    Returns a new FreenetURI with a new key type. Usually this will be invalid!
  - setRoutingKey
```
public FreenetURI setRoutingKey(byte[] newRoutingKey)
```
    Returns a new FreenetURI with a new routing key. KSKs do not have a routing key.
  - checkInsertURI
```
public void checkInsertURI()
                    throws InsertException
```
    Throw an InsertException if we have any meta-strings. They are not valid for inserts, you must insert a directory to create a directory structure.
    
    Throws:
    
    InsertException
  - checkInsertURI
```
public static void checkInsertURI(FreenetURI uri)
                           throws InsertException
```
    Throw an InsertException if the argument has any meta-strings. They are not valid for inserts, you must insert a directory to create a directory structure.
    
    Throws:
    
    InsertException
  - toRelativeURI
```
public java.net.URI toRelativeURI()
                           throws java.net.URISyntaxException
```
    Convert to a relative URI in the form of a URI (/KSK@gpl.txt etc).
    
    Throws:
    
    java.net.URISyntaxException
  - toURI
```
public java.net.URI toURI(java.lang.String basePath)
                   throws java.net.URISyntaxException
```
    Convert to a relative URI in the form of a URI, with the base path not necessarily /.
    
    Throws:
    
    java.net.URISyntaxException
  - isSSK
```
public boolean isSSK()
```
    Is this key an SSK?
  - isUSK
```
public boolean isUSK()
```
    Is this key a USK?
  - isCHK
```
public boolean isCHK()
```
    Is this key a CHK?
  - isKSK
```
public boolean isKSK()
```
    Is this key a KSK?
  - sskForUSK
```
public FreenetURI sskForUSK()
```
    Convert a USK into an SSK by appending "-" and the suggested edition to the document name and changing the key type.
  - isSSKForUSK
```
public boolean isSSKForUSK()
```
    Could this SSK be the result of sskForUSK()?
  - uskForSSK
```
public FreenetURI uskForSSK()
```
    Convert an SSK into a USK, if possible.
  - getEdition
```
public long getEdition()
```
    Get the edition number, if the key is a USK or a USK converted to an SSK.
  - compareTo
```
public int compareTo(FreenetURI o)
```
    Specified by:
    
    compareTo in interface java.lang.Comparable<FreenetURI>
  - deriveRequestURIFromInsertURI
```
public FreenetURI deriveRequestURIFromInsertURI()
                                         throws java.net.MalformedURLException
```
    If this object is a USK/SSK insert URI, this function computes the request URI which belongs to it. If it is a CHK/KSK, the original URI is returned as CHK/KSK do not have a private insert URI, they are their own "insert URI". If you want to give people access to content at an URI, you should always publish only the request URI. Never give away the insert URI, this allows anyone to insert under your URI!
    
    Returns:
    
    The request URI which belongs to this insert URI.
    
    Throws:
    
    java.net.MalformedURLException - If this object is a USK/SSK request URI already. NOT thrown for CHK/KSK URIs!
  - generateRandomCHK
```
public static FreenetURI generateRandomCHK(java.util.Random rand)
```

Class FreenetURI

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EMPTY_CHK_URI

URI_PREFIX

toStringCache

FAST_COMPARATOR

Constructor Detail

FreenetURI

FreenetURI

FreenetURI

FreenetURI

FreenetURI

FreenetURI

FreenetURI

FreenetURI

FreenetURI

FreenetURI

Method Detail

hashCode

equals

equalsKeypair

clone

intern

decompose

getGuessableKey

getDocName

getMetaString

lastMetaString

getAllMetaStrings

hasMetaStrings

getRoutingKey

getCryptoKey

getKeyType

popMetaString

dropLastMetaStrings

pushMetaString

addMetaStrings

addMetaStrings

setDocName

setMetaString

toString

toACIIString

toASCIIString

toString

toShortString

main

getExtra

listMetaStrings

readFullBinaryKeyWithLength

fromFullBinaryKey

readFullBinaryKey

writeFullBinaryKeyWithLength

writeFullBinaryKeyWithLength

getSuggestedEdition

getPreferredFilename

setSuggestedEdition

setKeyType

setRoutingKey

checkInsertURI

checkInsertURI

toRelativeURI

toURI

isSSK

isUSK

isCHK

isKSK

sskForUSK

isSSKForUSK

uskForSSK

getEdition

compareTo

deriveRequestURIFromInsertURI

generateRandomCHK