Module Interface URI

SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST

# URI

This module provides the framework for an implementation of RFC 2396, Uniform Resource Locators (URI): Generic Syntax. It defined the abstract types URI, OpaqueURI, and HierarchicalURI, together with the abstract base types that represent the authority, query, and fragment component of an URI. Handling of the path part of a hierarchical URI is delegated to the implementation of URI:Scheme:Hierarchical.Generic. Additionally, this module defines the type Reference, which represents an URI reference.

Conversion of an URI string into an instance of the data type URI is done by URI:Parser.NewURI. Likewise, URI:Parser.NewReference translates a string into an instance of Reference.

The modules ``URI:Scheme:*`' implement concrete specializations of URI for various URI scheme identifiers. Modules named ``URI:Authority:*`', ``URI:Query:*`', and ``URI:Fragment:*`' implement concrete authority, query, and fragment instances.

### Import List

        ADT:StringBuffer
        Exception
        Exception
        IO
        Object
        Object
        TextRider
        URI:String

Class List
Authority | Authority component of an URI.
Fragment | Fragment identifier of an URI.
HierarchicalURI | Holds a hierachical URI.
OpaqueURI | Holds an opaque URI.
Query | Query component of an URI.
Reference |
URI | Abstract base type of all URI variants.

Class Summary: Authority [Detail]
      +--URI.Authority
Authority component of an URI. See URI:Authority:Unparsed, URI:Authority:ServerBased, or URI:Authority:RegistryBased for concrete examples.
Constructor Summary
InitAuthority(Authority)
Method Summary
Append(StringBuffer) Appends the textual representation of the authority component auth to the string sb.
Clone(): Authority Creates a deep copy of the authority component referenced by auth.
Copy(Authority) Copies contents of source auth to target dest.
ParseAuthority(CharsLatin1, Offset) Parses the authority component str of an hierarchical URI.
WriteXML(Writer) Writes an XML fragment describing the authority component to the writer w.

Class Summary: Fragment [Detail]
      +--URI.Fragment
Fragment identifier of an URI. See URI:Fragment:Unparsed for a concrete example.
Constructor Summary
InitFragment(Fragment)
Method Summary
Append(StringBuffer) Appends the textual representation of the fragment identifier frag to the string sb.
Clone(): Fragment Creates a deep copy of the fragment component referenced by frag.
Copy(Fragment) Copies contents of source frag to target dest.
ParseFragment(CharsLatin1, Offset) Parses the fragment component str of an URI.
WriteXML(Writer) Writes an XML fragment describing the fragment identifier to the writer w.

Class Summary: HierarchicalURI [Detail]
      +---Object.Object
           |
           +---URI.URI
                |
                +--URI.HierarchicalURI
Holds a hierachical URI.
Field Summary
authority-: Authority Authority component of the URI.
query-: Query Query component of the URI.
Inherited Fields
From URI.URI: schemeId
Constructor Summary
InitHierarchicalURI(HierarchicalURI, STRING, Authority, Query)
Method Summary
AppendPath(StringBuffer) Appends the textual representation of the path component of uri to the string sb.
AuthorityMandatory(): BOOLEAN If TRUE and the URI has a scheme component, then require that an authority is present when parsing the URI, and include an empty authority part when converting the URI to a string, if no authority is defined.
ClearPath() Sets the path component of uri to the empty path.
Copy(URI) Copies contents of source uri to target dest.
MakeRelative(HierarchicalURI): URI Converts uri into an URI relative to baseURI.
NewAuthority(): Authority Creates a new instance of the authority component of URI uri.
NewQuery(): Query Creates a new instance of the query component of URI uri.
ParsePath(CharsLatin1, BOOLEAN, Offset) Parses the path component str of an URI.
ResolveRelative(HierarchicalURI) Resolves the relative URI uri to an absolute URI.
SetAuthority(Authority) Sets the authority component of uri.
SetQuery(Query) Sets the query component of uri.
Inherited Methods
From Object.Object: Equals, HashCode From URI.URI: AppendScheme, Clone, Copy, GetChannel, MakeRelative, SetSchemeId, ToString, WriteXML

Class Summary: OpaqueURI [Detail]
      +---Object.Object
           |
           +---URI.URI
                |
                +--URI.OpaqueURI
Holds an opaque URI.
Inherited Fields
From URI.URI: schemeId
Constructor Summary
InitOpaqueURI(OpaqueURI, STRING)
Method Summary
ParseOpaquePart(CharsLatin1, Offset) Parses the opaque component str of an URI.
Inherited Methods
From Object.Object: Equals, HashCode From URI.URI: AppendScheme, Clone, Copy, GetChannel, MakeRelative, SetSchemeId, ToString, WriteXML

Class Summary: Query [Detail]
      +--URI.Query
Query component of an URI. See URI:Query:Unparsed for a concrete example.
Constructor Summary
InitQuery(Query)
Method Summary
Append(StringBuffer) Appends the textual representation of the query component query to the string sb.
Clone(): Query Creates a deep copy of the queryority component referenced by query.
Copy(Query) Copies contents of source query to target dest.
ParseQuery(CharsLatin1, Offset) Parses the query component str of an hierarchical URI.
WriteXML(Writer) Writes an XML fragment describing the query component to the writer w.

Class Summary: Reference [Detail]
      +--URI.Reference
Field Summary
fragment-: Fragment The fragment identifier of the URI reference.
uri-: URI The URI part of the URI reference.
Constructor Summary
NewReference(URI, Fragment): Reference
Method Summary
ToString(): String8 Converts the URI reference ref to its string representation.
WriteXML(Writer) Writes an XML fragment describing the URI reference ref to the writer w.

Class Summary: URI [Detail]
      +---Object.Object
           |
           +--URI.URI
Abstract base type of all URI variants. This class has one concrete (URI:Scheme:CurrentDoc.CurrentDoc) and two abstract specializations (HierarchicalURI and OpaqueURI) in this module. All concrete specializations should be in modules with the name prefix ``URI:Scheme:*`'.
Field Summary
schemeId-: STRING Scheme part of the URI.
Constructor Summary
GetScheme(STRING): URI Returns a prototype object for URI scheme name.
InitURI(URI, STRING)
Method Summary
AppendScheme(StringBuffer) Appends the scheme component of uri to the string sb.
Clone(): URI Creates a deep copy of the URI referenced by uri.
Copy(URI) Copies contents of source uri to target dest.
GetChannel(ChannelMode): ByteChannel Opens a channel to the resource indicated by URI uri.
MakeRelative(HierarchicalURI): URI Converts uri into an URI relative to baseURI.
SetSchemeId(STRING) Sets the scheme identifier of uri.
ToString(): String8 Converts the URI uri to its string representation.
WriteXML(Writer) Writes an XML fragment describing the URI uri to the writer w.
Inherited Methods
From Object.Object: Equals, HashCode, ToString

Type Summary
ChannelMode = SHORTINT This type is used to signal how URI.GetChannel should open a channel.
Offset = Offset A character offset.

Procedure Summary
RegisterScheme(URI) Registers a new prototype object scheme under the name ``scheme.schemeId^`' in the module's list of supported URI schemes.

Constant Summary
channelNew Open the channel on a new resource, truncating any existing resource of the same name.
channelOld Open the channel on an old resource.
channelTmp Open the channel on a new resource, but do not register the resource yet.

Class Detail: Authority

Constructor Detail

### InitAuthority

    PROCEDURE InitAuthority(auth: Authority)

Method Detail

### Append

    PROCEDURE (auth: Authority) Append(sb: StringBuffer)

> Appends the textual representation of the authority component auth to the string sb.

### Clone

    PROCEDURE (auth: Authority) Clone(): Authority

> Creates a deep copy of the authority component referenced by auth.

### Copy

    PROCEDURE (auth: Authority) Copy(dest: Authority)

> Copies contents of source auth to target dest.

> Pre-condition: The dynamic type of dest is an extension of the dynamic type of auth.

### ParseAuthority

    PROCEDURE (auth: Authority) ParseAuthority(str: CharsLatin1;
                             offset: Offset)
      RAISES ParseError;

> Parses the authority component str of an hierarchical URI. On success, the data is stored in the authority object auth and the result is NIL. In case of error, a message object is returned and auth is not modified. A character position in an error message refers to an index in str, incremented by the value of offset.

### WriteXML

    PROCEDURE (auth: Authority) WriteXML(w: Writer)

> Writes an XML fragment describing the authority component to the writer w.

Class Detail: Fragment

Constructor Detail

### InitFragment

    PROCEDURE InitFragment(frag: Fragment)

Method Detail

### Append

    PROCEDURE (frag: Fragment) Append(sb: StringBuffer)

> Appends the textual representation of the fragment identifier frag to the string sb.

### Clone

    PROCEDURE (frag: Fragment) Clone(): Fragment

> Creates a deep copy of the fragment component referenced by frag.

### Copy

    PROCEDURE (frag: Fragment) Copy(dest: Fragment)

> Copies contents of source frag to target dest.

> Pre-condition: The dynamic type of dest is an extension of the dynamic type of frag.

### ParseFragment

    PROCEDURE (frag: Fragment) ParseFragment(str: CharsLatin1;
                            offset: Offset)
      RAISES ParseError;

> Parses the fragment component str of an URI. On success, the data is stored in the fragment object frag and the result is NIL. In case of error, a message object is returned and frag is not modified. A character position in an error message refers to an index in str, incremented by the value of offset.

### WriteXML

    PROCEDURE (frag: Fragment) WriteXML(w: Writer)

> Writes an XML fragment describing the fragment identifier to the writer w.

Class Detail: HierarchicalURI

Field Detail

### authority

    FIELD authority-: Authority

> Authority component of the URI. If there is no authority component, this field is NIL.

### query

    FIELD query-: Query

> Query component of the URI. If the URI has no query component, this field is NIL.

Constructor Detail

### InitHierarchicalURI

    PROCEDURE InitHierarchicalURI(uri: HierarchicalURI;
                                  schemeId: STRING;
                                  authority: Authority;
                                  query: Query)

Method Detail

### AppendPath

    PROCEDURE (uri: HierarchicalURI) AppendPath(sb: StringBuffer)

> Appends the textual representation of the path component of uri to the string sb.

### AuthorityMandatory

    PROCEDURE (uri: HierarchicalURI) AuthorityMandatory(): BOOLEAN

> If TRUE and the URI has a scheme component, then require that an authority is present when parsing the URI, and include an empty authority part when converting the URI to a string, if no authority is defined.

> By default, this method returns FALSE.

### ClearPath

    PROCEDURE (uri: HierarchicalURI) ClearPath()

> Sets the path component of uri to the empty path. Unlike the authority or query component, an URI always includes a path component.

### Copy

    PROCEDURE (uri: HierarchicalURI) Copy(dest: URI)

> Copies contents of source uri to target dest.

> Pre-condition: The dynamic type of dest is an extension of the dynamic type of uri.

> [Description inherited from Copy]

> Redefines: Copy

### MakeRelative

    PROCEDURE (uri: HierarchicalURI) MakeRelative(baseURI: HierarchicalURI): URI

> Converts uri into an URI relative to baseURI. The result is uri itself, if

> - baseURI is NIL,

> - uri is not an extension of HierarchicalURI, or

> - uri and baseURI have no common base.

> Otherwise, a new URI is constructed that holds only those parts of uri, that cannot be derived from baseURI. The inverse transformation is done by HierarchicalURI.ResolveRelative.

> [Description inherited from MakeRelative]

> Redefines: MakeRelative

### NewAuthority

    PROCEDURE (uri: HierarchicalURI) NewAuthority(): Authority

> Creates a new instance of the authority component of URI uri. The new object is subsequently filled in by parsing the authority component of the URI string (see URI:Authority.ParseAuthority).

### NewQuery

    PROCEDURE (uri: HierarchicalURI) NewQuery(): Query

> Creates a new instance of the query component of URI uri. The new object is subsequently filled in by parsing the query component of the URI string (see URI:Query.ParseQuery).

### ParsePath

    PROCEDURE (uri: HierarchicalURI) ParsePath(str: CharsLatin1;
                        absolute: BOOLEAN;
                        offset: Offset)
      RAISES ParseError;

> Parses the path component str of an URI. The parameter absolute indicates, whether the path is absolute or relative. On success, the data is stored in the URI uri and the result is NIL. In case of error, an error message is returned and uri is not modified. A character position in an error message refers to an index in str, incremented by the value of offset.

### ResolveRelative

    PROCEDURE (uri: HierarchicalURI) ResolveRelative(baseURI: HierarchicalURI)

> Resolves the relative URI uri to an absolute URI. The missing parts of uri are taken from baseURI. This is the inverse transformation to URI.MakeRelative.

### SetAuthority

    PROCEDURE (uri: HierarchicalURI) SetAuthority(auth: Authority)

> Sets the authority component of uri. A value of NIL means that the URI has no authority component.

### SetQuery

    PROCEDURE (uri: HierarchicalURI) SetQuery(query: Query)

> Sets the query component of uri. A value of NIL means that the URI has no query component.

Class Detail: OpaqueURI

Constructor Detail

### InitOpaqueURI

    PROCEDURE InitOpaqueURI(uri: OpaqueURI;
                            schemeId: STRING)

Method Detail

### ParseOpaquePart

    PROCEDURE (uri: OpaqueURI) ParseOpaquePart(str: CharsLatin1;
                              offset: Offset)
      RAISES ParseError;

> Parses the opaque component str of an URI. On success, the data is stored in the URI uri and the result is NIL. In case of error, e.g., because str contains characters that are not allowed in an URI, an error message is returned and uri is not modified. A character position in an error message refers to an index in str, incremented by the value of offset.

Class Detail: Query

Constructor Detail

### InitQuery

    PROCEDURE InitQuery(query: Query)

Method Detail

### Append

    PROCEDURE (query: Query) Append(sb: StringBuffer)

> Appends the textual representation of the query component query to the string sb.

### Clone

    PROCEDURE (query: Query) Clone(): Query

> Creates a deep copy of the queryority component referenced by query.

### Copy

    PROCEDURE (query: Query) Copy(dest: Query)

> Copies contents of source query to target dest.

> Pre-condition: The dynamic type of dest is an extension of the dynamic type of query.

### ParseQuery

    PROCEDURE (query: Query) ParseQuery(str: CharsLatin1;
                         offset: Offset)
      RAISES ParseError;

> Parses the query component str of an hierarchical URI. On success, the data is stored in the query object query and the result is NIL. In case of error, a message object is returned and query is not modified. A character position in an error message refers to an index in str, incremented by the value of offset.

### WriteXML

    PROCEDURE (query: Query) WriteXML(w: Writer)

> Writes an XML fragment describing the query component to the writer w.

Class Detail: Reference

Field Detail

### fragment

    FIELD fragment-: Fragment

> The fragment identifier of the URI reference. If the reference has no fragment identifier, then this field is NIL.

### uri

    FIELD uri-: URI

> The URI part of the URI reference. This field is never NIL.

Constructor Detail

### NewReference

    PROCEDURE NewReference(uri: URI;
                           fragment: Fragment): Reference

Method Detail

### ToString

    PROCEDURE (ref: Reference) ToString(): String8

> Converts the URI reference ref to its string representation. Reserved characters in the URI and fragment identifier are escaped where necessary.

### WriteXML

    PROCEDURE (ref: Reference) WriteXML(w: Writer)

> Writes an XML fragment describing the URI reference ref to the writer w.

Class Detail: URI

Field Detail

### schemeId

    FIELD schemeId-: STRING

> Scheme part of the URI. For a relative URI (and all instances of URI:Scheme:CurrentDoc.CurrentDoc), this field is NIL.

Constructor Detail

### GetScheme

    PROCEDURE GetScheme(name: STRING): URI

> Returns a prototype object for URI scheme name. If no matching scheme was registered previously with RegisterScheme, NIL is returned.

### InitURI

    PROCEDURE InitURI(uri: URI;
                      schemeId: STRING)

Method Detail

### AppendScheme

    PROCEDURE (uri: URI) AppendScheme(sb: StringBuffer)

> Appends the scheme component of uri to the string sb.

### Clone

    PROCEDURE (uri: URI) Clone(): URI

> Creates a deep copy of the URI referenced by uri. That is, it creates a new instance of uri and calls URI.Copy on it.

### Copy

    PROCEDURE (uri: URI) Copy(dest: URI)

> Copies contents of source uri to target dest.

> Pre-condition: The dynamic type of dest is an extension of the dynamic type of uri.

### GetChannel

    PROCEDURE (uri: URI) GetChannel(mode: ChannelMode): ByteChannel
      RAISES Error;

> Opens a channel to the resource indicated by URI uri. Depending on mode, one of these operations is performed:

> channelNew | Opens a channel to a new instance of the resource. If the resource exists, it is truncated. The channel is opened for both read and write access.
> channelTmp | Opens a channel to a new instance of the resource, but does not register the resource within its naming service. The channel is opened for both read and write access. Please note that some channel operations do not support this operation. For those that do, registration of the resource in the naming service depends on the channel implementation.
> channelOld | Opens a channel to an existing resource. Only read access is enabled.

> On success, a channel instance is returned. On failure, an exception of type IO.Error is raised.

> Note: Currently, only the ``file`' URI (URI:Scheme:File) and the ``http`' URI (URI:Scheme:HTTP) support this method.

### MakeRelative

    PROCEDURE (uri: URI) MakeRelative(baseURI: HierarchicalURI): URI

> Converts uri into an URI relative to baseURI. The result is uri itself, if

> - baseURI is NIL,

> - uri is not an extension of HierarchicalURI, or

> - uri and baseURI have no common base.

> Otherwise, a new URI is constructed that holds only those parts of uri, that cannot be derived from baseURI. The inverse transformation is done by HierarchicalURI.ResolveRelative.

### SetSchemeId

    PROCEDURE (uri: URI) SetSchemeId(schemeId: STRING)

> Sets the scheme identifier of uri. If schemeId is NIL, then uri is a relative URI.

### ToString

    PROCEDURE (uri: URI) ToString(): String8

> Converts the URI uri to its string representation. Reserved characters in the URI and characters that may not appear in a valid URI are escaped where necessary.

> Redefines: ToString

### WriteXML

    PROCEDURE (uri: URI) WriteXML(w: Writer)

> Writes an XML fragment describing the URI uri to the writer w.

Type Detail

### ChannelMode

    TYPE ChannelMode = SHORTINT

> This type is used to signal how URI.GetChannel should open a channel. It must be one of channelNew, channelTmp, or channelOld.

### Offset

    TYPE Offset = Offset

> A character offset.

Procedure Detail

### RegisterScheme

    PROCEDURE RegisterScheme(scheme: URI)

> Registers a new prototype object scheme under the name ``scheme.schemeId^`' in the module's list of supported URI schemes. If a previously registered scheme of the same name exists, it is replaced with scheme. Note that case is not distinguished for scheme names.

Constant Detail

### channelNew

    CONST channelNew

> Open the channel on a new resource, truncating any existing resource of the same name. Both read and write access is enabled.

### channelOld

    CONST channelOld

> Open the channel on an old resource. Only read access is enabled.

### channelTmp

    CONST channelTmp

> Open the channel on a new resource, but do not register the resource yet. Both read and write access is enabled.