location - HTTP URL
The HTTP URL (location) is part of the OHTTP request and defines the location for the required action. It follows the server and port specification in a HTTP request:
http://server:port/location[?arameter]
parameter - Several request types support parameters, which are well-defined keywords for controlling the behavior of the request. Supported parameters depend on request type. Following parameters are supported:
parameter := 'insert' | 'replace' | 'delete' | 'noinsert' | 'noreplace'
location - The syntax for location is as follows:
location := property_reference(*)
property_reference := '/' name [ '/' [locator] ]
locator:= '*' | key | skey | number
skey := '"' key '"'
key:= string [ key_component(*) ]
key_component:= '|' string
name - is a property name. The name in the first property name reference is, typically, an extent name (global collection) or LOID (collection of all instances in the database). In order to address namespace extents, the property name may be scoped (e.g. Person::Persons). The LOID property provides kind of short cut to instances that are, otherwise, accessible via hierarchical path, only. names for further property references must be defined in the context of the preceding property's data type. The property in the last property reference is the source property for the required operation.
locator - is either a key value or a number (position or LOID). The locator defines a key or position for locating an instance. When locator is not a number, it is interpreted as key value for the main key of the collection (defined in the data model). When locator is a number, it is interpreted as position or LOID. In order to pass a number as key, it must be put in quotation marks. For single references, typically 0 (position) is passed as locator. For LOID an LOID value previously retrieved may be passed. The locator for the last property reference is optional. A URL referring to a collection is called collection URL. The behavior of the response in case of collection URLs depends on the request type.
In order to indicate a collection iterator, '*' could be defined as locator. Usually, collection iterators are used to iterate through a collection property. In order to skip the locator, an empty locator may be passed (//). Skipping locators becomes necessary, when calling property functions (e.g. Person::Persons/P1001/children//count)
Elementary data type attributes and MEMO or BLOB references (elementary property reference) do not require a locator. For array attributes, one may pass an array index as locator in order to refer to a single element in the array. In order to refer to an attribute within a complex attribute (e.g. city in address), a position 0 has to be passed (address/0/city)
skey - a string key is a key within quotation marks. Usually, quotation marks may be omitted (as long as the key value is not recognized as number). When, however, the key value is a number, quotation marks are required in order to distinguish it from a position.
key - may be passed as locator, when the name refers to a collection property with a unique key. Components for a component key are separated by '|'.
A number (position or index) may be passed to any kind of property. In case of elementary properties (simple attributes, MEMO, BLOB), the number must be 0. For collection properties or attribute arrays the number ranges from 0 to maximum dimension -1. For LOID, number is interpreted as value for the local object identifier (LOID) similar to a key value.
Syntactical details for string, number and name are describes below in topic Values, formats and encodings below.
Several characters must not appear in an URL. In general, URLs must not contain slash in names or key values. When it becomes necessary passing a key value containing '/', OSI requests may be used instead. Other forbidden characters may be pass as hexadecimal values preceded by '%'. Following characters must be passed hexadecimal:
- # -> %23
- ? -> %3F
- \ -> %5C
URL data is expected to be UTF8 encoded.