OSGi 8.1.0 · org.osgi.service.dmt.Uri · APIdia, the JavaDoc alternative

This class contains static utility methods to manipulate DMT URIs.

Syntax of valid DMT URIs:

A slash ('/' \u002F) is the separator of the node names. Slashes used in node name must therefore be escaped using a backslash slash ( "\/"). The backslash must be escaped with a double backslash sequence. A backslash found must be ignored when it is not followed by a slash or backslash.
The node name can be constructed using full Unicode character set (except the Supplementary code, not being supported by CLDC/CDC). However, using the full Unicode character set for node names is discouraged because the encoding in the underlying storage as well as the encoding needed in communications can create significant performance and memory usage overhead. Names that are restricted to the URI set [-a-zA-Z0-9_.!~*'()] are most efficient.
URIs used in the DMT must be treated and interpreted as case sensitive.
No End Slash: URI must not end with the delimiter slash ('/' \u002F). This implies that the root node must be denoted as "." and not "./".
No parent denotation: URI must not be constructed using the character sequence "../" to traverse the tree upwards.
Single Root: The character sequence "./" must not be used anywhere else but in the beginning of a URI.

Field Summary

Modifier and Type	Field and Description
private static final char[]	BASE_64_TABLE
public static final String	PATH_SEPARATOR This constant stands for a string identifying the path separator in the DmTree ("/").
public static final char	PATH_SEPARATOR_CHAR This constant stands for a char identifying the path separator in the DmTree ('/').
public static final String	ROOT_NODE This constant stands for a string identifying the root of the DmTree (".").
public static final char	ROOT_NODE_CHAR This constant stands for a char identifying the root of the DmTree ('.').

Constructor Summary

Access	Constructor and Description
private	Uri() A private constructor to suppress the default public constructor.

Method Summary

Modifier and Type	Method and Description
public static String	Returns: the decoded node name decode(String the node name to be decoded nodeName) Decode the node name so that back slash and forward slash are unescaped from a back slash.
public static String	Returns: the encoded node name encode(String the node name to be encoded nodeName) Encode the node name so that back slash and forward slash are escaped with a back slash.
private static String	getHash(String from)
private static int	Returns: URI segment length getSegmentLength(String the URI segment segment) This method returns the length of a URI segment.
public static boolean	Returns: whether the specified URI is absolute isAbsoluteUri(String the URI to be checked, must not be `null` and must contain a valid URI uri) Checks whether the specified URI is an absolute URI.
public static boolean	Returns: whether the specified URI is valid isValidUri(String the URI to be validated uri) Checks whether the specified URI is valid.
public static String	Returns: the normalized node name that is valid for tree operations mangle(String the node name to be mangled (if necessary), must not be `null` or empty nodeName) Returns a node name that is valid for the tree operation methods, based on the given node name.
pack-priv static String	mangle(String nodeName, int limit)
public static String[]	Returns: an array of URI segments created by splitting the specified URI toPath(String the URI to be split, must not be `null` uri) Split the specified URI along the path separator '/' characters and return an array of URI segments.
public static String	Returns: the URI created from the specified segments toUri(String[] a possibly empty array of URI segments, must not be `null` path) Construct a URI from the specified URI segments.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

BASE_64_TABLE	back to summary
private static final char[] BASE_64_TABLE

PATH_SEPARATOR	back to summary
public static final String PATH_SEPARATOR This constant stands for a string identifying the path separator in the DmTree ("/"). Since 2.0

PATH_SEPARATOR

back to summary

public static final String PATH_SEPARATOR

This constant stands for a string identifying the path separator in the DmTree ("/").

Since: 2.0

PATH_SEPARATOR_CHAR	back to summary
public static final char PATH_SEPARATOR_CHAR This constant stands for a char identifying the path separator in the DmTree ('/'). Since 2.0

PATH_SEPARATOR_CHAR

back to summary

public static final char PATH_SEPARATOR_CHAR

This constant stands for a char identifying the path separator in the DmTree ('/').

Since: 2.0

ROOT_NODE	back to summary
public static final String ROOT_NODE This constant stands for a string identifying the root of the DmTree ("."). Since 2.0

ROOT_NODE

back to summary

public static final String ROOT_NODE

This constant stands for a string identifying the root of the DmTree (".").

Since: 2.0

ROOT_NODE_CHAR	back to summary
public static final char ROOT_NODE_CHAR This constant stands for a char identifying the root of the DmTree ('.'). Since 2.0

ROOT_NODE_CHAR

back to summary

public static final char ROOT_NODE_CHAR

This constant stands for a char identifying the root of the DmTree ('.').

Since: 2.0

Constructor Detail

Uri	back to summary
private Uri() A private constructor to suppress the default public constructor.

Method Detail

decode	back to summary
public static String decode(String nodeName) Decode the node name so that back slash and forward slash are unescaped from a back slash. Parameters nodeName:String the node name to be decoded Returns:String the decoded node name Since 2.0

decode

back to summary

public static String decode(String nodeName)

Decode the node name so that back slash and forward slash are unescaped from a back slash.

Parameters

nodeName:String: the node name to be decoded

Returns:String

the decoded node name

Since

2.0

encode back to summary

encode	back to summary
public static String encode(String nodeName) Encode the node name so that back slash and forward slash are escaped with a back slash. This method is the reverse of `decode(String)`. Parameters nodeName:String the node name to be encoded Returns:String the encoded node name Since 2.0

public static String encode(String nodeName)

Encode the node name so that back slash and forward slash are escaped with a back slash. This method is the reverse of decode(String).

Parameters

nodeName:String: the node name to be encoded

Returns:String

the encoded node name

Since

2.0

getHash	back to summary
private static String getHash(String from)

getSegmentLength back to summary

getSegmentLength	back to summary
private static int getSegmentLength(String segment) This method returns the length of a URI segment. The length of the URI segment is defined as the number of bytes in the unescaped, UTF-8 encoded representation of the segment. The method verifies that the URI segment is well-formed. Parameters segment:String the URI segment Returns:int URI segment length Exceptions NullPointerException: if the specified segment is `null` IllegalArgumentException: if the specified URI segment is malformed

private static int getSegmentLength(String segment)

This method returns the length of a URI segment. The length of the URI segment is defined as the number of bytes in the unescaped, UTF-8 encoded representation of the segment.

The method verifies that the URI segment is well-formed.

Parameters

segment:String: the URI segment

Returns:int

URI segment length

Exceptions

NullPointerException:: if the specified segment is null
IllegalArgumentException:: if the specified URI segment is malformed

isAbsoluteUri back to summary

isAbsoluteUri	back to summary
public static boolean isAbsoluteUri(String uri) Checks whether the specified URI is an absolute URI. An absolute URI contains the complete path to a node in the DMT starting from the DMT root ("."). Parameters uri:String the URI to be checked, must not be `null` and must contain a valid URI Returns:boolean whether the specified URI is absolute Exceptions NullPointerException: if the specified URI is `null` IllegalArgumentException: if the specified URI is malformed

public static boolean isAbsoluteUri(String uri)

Checks whether the specified URI is an absolute URI. An absolute URI contains the complete path to a node in the DMT starting from the DMT root (".").

Parameters

uri:String: the URI to be checked, must not be null and must contain a valid URI

Returns:boolean

whether the specified URI is absolute

Exceptions

NullPointerException:: if the specified URI is null
IllegalArgumentException:: if the specified URI is malformed

isValidUri back to summary

isValidUri	back to summary
public static boolean isValidUri(String uri) Checks whether the specified URI is valid. A URI is considered valid if it meets the following constraints: the URI is not `null`; the URI follows the syntax defined for valid DMT URIs; The exact definition of the length of a URI and its segments is given in the descriptions of the `getMaxUriLength()` and `getMaxSegmentNameLength()` methods. Parameters uri:String the URI to be validated Returns:boolean whether the specified URI is valid

public static boolean isValidUri(String uri)

Checks whether the specified URI is valid. A URI is considered valid if it meets the following constraints:

the URI is not null;
the URI follows the syntax defined for valid DMT URIs;

The exact definition of the length of a URI and its segments is given in the descriptions of the getMaxUriLength() and getMaxSegmentNameLength() methods.

Parameters

uri:String: the URI to be validated

Returns:boolean

whether the specified URI is valid

mangle back to summary

mangle	back to summary
public static String mangle(String nodeName) Returns a node name that is valid for the tree operation methods, based on the given node name. This transformation is not idempotent, so it must not be called with a parameter that is the result of a previous `mangle` method call. Node name mangling is needed in the following cases: if the name contains '/' or '\' characters A node name that does not suffer from either of these problems is guaranteed to remain unchanged by this method. Therefore the client may skip the mangling if the node name is known to be valid (though it is always safe to call this method). The method returns the normalized `nodeName` as described below. Invalid node names are normalized in different ways, depending on the cause. If the name contains '/' or '\' characters, then these are simply escaped by inserting an additional '\' before each occurrence. If the length of the name does exceed the limit, the following mechanism is used to normalize it: the SHA-1 digest of the name is calculated the digest is encoded with the base 64 algorithm all '/' characters in the encoded digest are replaced with '_' trailing '=' signs are removed Parameters nodeName:String the node name to be mangled (if necessary), must not be `null` or empty Returns:String the normalized node name that is valid for tree operations Exceptions NullPointerException: if `nodeName` is `null` IllegalArgumentException: if `nodeName` is empty

public static String mangle(String nodeName)

Returns a node name that is valid for the tree operation methods, based on the given node name. This transformation is not idempotent, so it must not be called with a parameter that is the result of a previous mangle method call.

Node name mangling is needed in the following cases:

if the name contains '/' or '\' characters

A node name that does not suffer from either of these problems is guaranteed to remain unchanged by this method. Therefore the client may skip the mangling if the node name is known to be valid (though it is always safe to call this method).

The method returns the normalized nodeName as described below. Invalid node names are normalized in different ways, depending on the cause. If the name contains '/' or '\' characters, then these are simply escaped by inserting an additional '\' before each occurrence. If the length of the name does exceed the limit, the following mechanism is used to normalize it:

the SHA-1 digest of the name is calculated
the digest is encoded with the base 64 algorithm
all '/' characters in the encoded digest are replaced with '_'
trailing '=' signs are removed

Parameters

nodeName:String: the node name to be mangled (if necessary), must not be null or empty

Returns:String

the normalized node name that is valid for tree operations

Exceptions

NullPointerException:: if nodeName is null
IllegalArgumentException:: if nodeName is empty

mangle	back to summary
pack-priv static String mangle(String nodeName, int limit)

toPath back to summary

toPath	back to summary
public static String[] toPath(String uri) Split the specified URI along the path separator '/' characters and return an array of URI segments. Special characters in the returned segments are escaped. The returned array may be empty if the specified URI was empty. Parameters uri:String the URI to be split, must not be `null` Returns:String[] an array of URI segments created by splitting the specified URI Exceptions NullPointerException: if the specified URI is `null` IllegalArgumentException: if the specified URI is malformed

public static String[] toPath(String uri)

Split the specified URI along the path separator '/' characters and return an array of URI segments. Special characters in the returned segments are escaped. The returned array may be empty if the specified URI was empty.

Parameters

uri:String: the URI to be split, must not be null

Returns:String[]

an array of URI segments created by splitting the specified URI

Exceptions

NullPointerException:: if the specified URI is null
IllegalArgumentException:: if the specified URI is malformed

toUri back to summary

toUri	back to summary
public static String toUri(String[] path) Construct a URI from the specified URI segments. The segments must already be mangled. If the specified path is an empty array then an empty URI (`""`) is returned. Parameters path:String[] a possibly empty array of URI segments, must not be `null` Returns:String the URI created from the specified segments Exceptions NullPointerException: if the specified path or any of its segments are `null` IllegalArgumentException: if the specified path contains too many or malformed segments or the resulting URI is too long

public static String toUri(String[] path)

Construct a URI from the specified URI segments. The segments must already be mangled.

If the specified path is an empty array then an empty URI ("") is returned.

Parameters

path:String[]: a possibly empty array of URI segments, must not be null

Returns:String

the URI created from the specified segments

Exceptions

NullPointerException:: if the specified path or any of its segments are null
IllegalArgumentException:: if the specified path contains too many or malformed segments or the resulting URI is too long

public final Class Uri

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail