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
    RT0
    TextRider
    URI:String
 
Class List
AuthorityAuthority component of an URI.
FragmentFragment identifier of an URI.
HierarchicalURIHolds a hierachical URI.
OpaqueURIHolds an opaque URI.
QueryQuery component of an URI.
Reference
URIAbstract 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]
  +---RT0.Object
       |
       +---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 RT0.Object:

          Finalize

From Object.Object:

          Equals, HashCode

From URI.URI:

          AppendScheme, Clone, Copy, GetChannel, MakeRelative, SetSchemeId, ToString, WriteXML

 
Class Summary: OpaqueURI [Detail]
  +---RT0.Object
       |
       +---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 RT0.Object:

          Finalize

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]
  +---RT0.Object
       |
       +---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 RT0.Object:

          Finalize

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

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

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.