Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
WebObjects

NAME

WebObjects - abstraction for world wide web objects

SYNOPSIS

CONST doCache = 0; privatCache = 1; noCache = 2; noStore = 3;
CONST noTransform = 4; mustRevalidate = 5; proxyRevalidate = 6;
CONST cacheMechanisms = 7;
TYPE Object = POINTER TO ObjectRec;
TYPE ObjectRec =
   RECORD
      (Services.ObjectRec)
   END;
TYPE Handle = POINTER TO HandleRec;
TYPE HandleRec =
   RECORD
      (Disciplines.ObjectRec)
      object: Object;
      error: BOOLEAN;
   END;



TYPE CreateHandleProc = PROCEDURE (VAR handle: Handle; object: Object; 
                                   search, body: Streams.Stream;
                                   errors: RelatedEvents.Object): BOOLEAN;
TYPE GetChallengeProc = PROCEDURE (handle: Handle;
                                   VAR scheme, realm, param: ARRAY OF CHAR);
TYPE AuthenticateProc = PROCEDURE (handle: Handle;
                                   scheme, param: Streams.Stream): BOOLEAN;
TYPE GetMD5HashValueProc = PROCEDURE (handle: Handle;
                                      VAR value: OneWayHashes.Value);
TYPE GetLanguagesProc = PROCEDURE (handle: Handle; VAR languages: ARRAY OF CHAR);
TYPE GetEncodingProc = PROCEDURE (handle: Handle; VAR encoding: ARRAY OF CHAR);
TYPE GetCharsetProc = PROCEDURE (handle: Handle; VAR charset: ARRAY OF CHAR);
TYPE GetMediaTypeProc = PROCEDURE (handle: Handle; 
                                   VAR type, subtype, param: ARRAY OF CHAR);
TYPE GetUserAgentProc = PROCEDURE (handle: Handle;
                                   VAR userAgent: ARRAY OF CHAR);
TYPE GetLengthProc = PROCEDURE (handle: Handle; VAR length: LONGINT);
TYPE GetBaseProc = PROCEDURE (handle: Handle; VAR base: InetURLs.URL);
TYPE GetLocationProc = PROCEDURE (handle: Handle; VAR location: InetURLs.URL);
TYPE GetCacheMechanismProc = PROCEDURE (handle: Handle; VAR mechanism: SET);
TYPE GetEntityTagProc = PROCEDURE (handle: Handle;
                                   VAR eTag: ARRAY OF CHAR; VAR weak: BOOLEAN);
TYPE GetExpireDateProc = PROCEDURE (handle: Handle; VAR date: Times.Time);
TYPE GetLastModifiedDateProc = PROCEDURE (handle: Handle; VAR date: Times.Time);
TYPE SetRangeProc = PROCEDURE (handle: Handle;
                               begin, end: Streams.Count): BOOLEAN;
TYPE WriteBodyProc = PROCEDURE (handle: Handle; body: Streams.Stream);



TYPE Interface = POINTER TO InterfaceRec;
TYPE InterfaceRec = 
   RECORD
      (Objects.ObjectRec)
      createHandle: CreateHandleProc;
      getChallenge: GetChallengeProc;
      authenticate: AuthenticateProc;
      getMD5HashValue: GetMD5HashValueProc;
      getLanguages: GetLanguagesProc;
      getEncoding: GetEncodingProc;
      getCharset: GetCharsetProc;
      getMediaType: GetMediaTypeProc;
      getUserAgent: GetUserAgentProc;
      getLength: GetLengthProc;
      getBase: GetBaseProc;
      getLocation: GetLocationProc;
      getCacheMechanism: GetCacheMechanismProc;
      getEntityTag: GetEntityTagProc;
      getExpireDate: GetExpireDateProc;
      getLastModifiedDate: GetLastModifiedDateProc;
      setRange: SetRangeProc;
      writeBody: WriteBodyProc;
   END;



CONST createHandleCap = 0;
CONST clientAuthenicateCap = 1;
CONST getMD5HashValueCap = 2;
CONST getLanguagesCap = 3;
CONST getEncodingCap = 4;
CONST getCharsetCap = 5;
CONST getMediaTypeCap = 6;
CONST getUserAgentCap = 7;
CONST getLengthCap = 8;
CONST getBaseCap =9;
CONST getLocationCap = 10;
CONST getCacheMechanismCap = 11;
CONST getEntityTagCap = 12;
CONST getExpireDateCap = 13;
CONST getLastModifiedDateCap = 14;
CONST setRangeCap = 15;
CONST writeBodyCap = 16;
CONST allCaps = {createHandleCap .. writeBodyCap};
CONST strictCaps = {createHandleCap, writeBodyCap};
TYPE Capability = SHORTINT;
TYPE CapabilitySet = SET; (* of Capability *)



PROCEDURE Init(object: Object; if: Interface; caps: CapabilitySet);
PROCEDURE Capabilities(object: Object): CapabilitySet;
PROCEDURE CreateHandle(VAR handle: Handle; object: Object; 
                       search, body: Streams.Stream;
                       errors: RelatedEvents.Object): BOOLEAN;
PROCEDURE GetChallenge(handle: Handle;
                       VAR scheme, realm, param: ARRAY OF CHAR);
PROCEDURE Authenticate(handle: Handle;
                       scheme, param: Streams.Stream): BOOLEAN;
PROCEDURE GetMD5HashValue(handle: Handle; VAR value: OneWayHashes.Value);
PROCEDURE GetLanguages(handle: Handle; VAR languages: ARRAY OF CHAR);
PROCEDURE GetEncoding(handle: Handle; VAR encoding: ARRAY OF CHAR);
PROCEDURE GetCharset(handle: Handle; VAR charset: ARRAY OF CHAR);
PROCEDURE GetMediaType(handle: Handle; 
                       VAR type, subtype, param: ARRAY OF CHAR);
PROCEDURE GetUserAgent(handle: Handle; VAR userAgent: ARRAY OF CHAR);
PROCEDURE GetLength(handle: Handle; VAR length: LONGINT);
PROCEDURE GetBase(handle: Handle; VAR base: InetURLs.URL);
PROCEDURE GetLocation(handle: Handle; VAR location: InetURLs.URL);
PROCEDURE GetCacheMechanism(handle: Handle; VAR mechanism: SET);
PROCEDURE GetEntityTag(handle: Handle;
                       VAR eTag: ARRAY OF CHAR; VAR weak: BOOLEAN);
PROCEDURE GetExpireDate(handle: Handle; VAR date: Times.Time);
PROCEDURE GetLastModifiedDate(handle: Handle; VAR date: Times.Time);
PROCEDURE SetRange(handle: Handle; begin, end: LONGINT): BOOLEAN;
PROCEDURE WriteBody(handle: Handle; body: Streams.Stream);

DESCRIPTION

WebObjects defines an abstraction for objects that may be represented as pages in the WWW. Web objects are mainly accessed by WebHandlers which processes access requests that are represented by handles in this abstraction. Access to individual objects can be controlled by an authentication scheme.

Providing Web Objects

Implementations must initialize new instances of web objects using Init, specifying a set of capabilities (caps) and an interface (if) containing interface procedures. At least createHandle and writeBody are to be implemented. All other procedures are optional. All interface procedures have the same semantics as their counter parts described below.

Note that web objects may be accessed in parallel by multiple parties, each using its own handle. Hence, state maintaining web objects have to take care of synchronisation.

The error flag of the handle is initially set to FALSE and must be set to TRUE by any of the interface procedures that detects errors and generates error events which must be related to handle.

Using Web Objects

Capabilities returns the capabilities of object. Note that all operations may be called even if they are not implemented (and not included in the set of capabilities). In this case reasonable default values will be returned.

For each new access to be processed, a handle has to be created by CreateHandle. Parameters may be passed via the search stream representing the associated part in the URL (see, for example, InetHTTPURLs) and as POST message via body. Both streams may be set to NIL indicating an empty text.

GetChallenge returns the scheme, realm (without quotes) and further parameters (param) to build the challenge of a response. If you don't need an authentication to access the data of the object, scheme is empty, realm and param are undefined.

Authenticate returns TRUE if the Authentication for scheme and param is correct. Both parameters are read from position 0.

GetMD5HashValue returns, if supported, a MD5 hash value of the byte stream WriteBody would return. value is set to NIL otherwise.

GetLanguages returns the language of the intended audience in languages in conformance to RFC 1766. An empty string represents an unrestricted audience.

GetEncoding returns the encoding (e.g. gzip, compress) of the object. An empty string means there is no encoding.

GetCharset returns the charset of the object. An empty value means that the standard charset ISO 8859-1 is used.

GetMediaType returns the media type of the object including the sub type and optional parameters. Note that the media type may be empty indicating that the interpretation of the contents is left up to the receiver of the message body.

GetUserAgent returns the user agent the message body is intended for. An empty value means that the message body is open for all user agents.

GetLength returns the length of the body. Negative values may be returned if the length of the message body cannot be computed in advance.

GetBase returns the base (absolute URL) for relative URLs in the body or NIL if undefined.

GetLocation returns, if defined, the location of the resource as URL, and NIL otherwise.

GetCacheMechanism gives a recommendation how a cache should treat the data. Mechanism is a set of doCache (the response may be cached even if it normally wouldn't be cached), privatCache (the response must not be cached in shared caches), noCache (the response must not be cached), noStore (caches should not store the data in non-volatile storage), noTransform (caches are not allowed to transform the message), mustRevalidate (caches must revalidate stale cache entries) and proxyRevalidate (shared caches, like proxies must revalidate stale cache entries).

GetEntityTag provides an entity-tag to support caches. If it is a weak tag the parameter weak will be TRUE. If there is no entity-tag for the object, an empty string will be returned in eTag.

GetExpireDate returns, if defined, a date after which a response should be considered as stale, and NIL otherwise.

GetLastModifiedDate returns the date the resource was last modified or NIL if undefined.

SetRange limits the result of WriteBody to an interval starting at position begin (including) and ending with end (excluding). SetRange will return FALSE if it is not possible to handle ranges with that object. Note that GetLength is not affected by such a limitation.

WriteBody writes the object body to stream body, possibly limited by a former call of SetRange.

DIAGNOSTICS

WebObjects does not generate error events by itself. Underlying implementations, however, are expected to relate their error events to handle or to errors in case of CreateHandle (see RelatedEvents),

Additionally, the error component of a handle is set to TRUE in case of errors.

AUTHOR

Manfred Rueß, University of Ulm,
the revisions are due to Andreas Borchert.

Edited by: borchert, last change: 1998/04/24, revision: 1.1, converted to HTML: 1998/04/24