; authority path-abempty ) | path-absolute | path-rootless | path-empty authority = [ user-info "@" ] host-domain [ ":" host-port ] relative-reference = relative-part [ "?" query ] [ "#" fragment ] relative-part = ( "//" authority path-abempty ) | path-absolute | path-noscheme | path-empty path-abempty = begins with "/" or is empty path-absolute = begins with "/" but not "//" path-noscheme = begins with a non-colon segment path-rootless = begins with a segment path-empty = zero characters
Note that this class doesn't encode or decode the reserved characters. It assumes that the URIs or the URI parts passed in are properly encoded using the standard URI encoding mechanism. You can use the static "encode()" and "decode()" methods for this purpose. Note that if an invalid URI character is detected by the constructor or one of the setters, a trace will be logged and the character will be automatically encoded.
The fundamental point to underline is the difference between an URI "reference" and an URI. Contrary to an URI (the target identifier of a REST resource), an URI reference can be relative (with or without query and fragment part). This relative URI reference can then be resolved against a base reference via the getTargetRef() method which will return a new resolved Reference instance, an absolute URI reference with no base reference and with no dot-segments (the path segments "." and "..").
You can also apply the getTargetRef() method on absolute references in order to solve the dot-segments. Note that applying the getRelativeRef() method on an absolute reference returns the current reference relatively to a base reference, if any, and solves the dot-segments.
The Reference stores its data as a single string, the one passed to the constructor. This string can always be obtained using the toString() method. A couple of integer indexes are maintained to improve the extraction time of various reference properties (URI components).
When you modify a specific component of the URI reference, via the setPath() method for example, the internal string is simply regenerated by updating only the relevant part. We try as much as possible to protect the bytes given to the Reference class instead of transparently parsing and normalizing the URI data. Our idea is to protect encodings and special characters in all case and reduce the memory size taken by this class while making Reference instances mutable.
Because the base reference is only a property of the Reference ("baseRef"). When you use the "Reference(base, path)" constructor, it is equivalent to doing:
ref = new Reference(path);
ref.setBaseRef(base);
The base ref is not automatically resolved or "merged" with the rest of the reference information (the path here). For example, this let's you reuse a single reference as the base of several relative references. If you modify the base reference, all relative references are still accurate.
Note that the name and value properties are thread safe, stored in volatile members.
@author Jerome Louvel
@see
RFC 3986