< System Fundamentals
spacer

10320/loc Handle Type

For handles with multiple URL values, the Proxy Server (or web browser plug-in) simply selects the first URL value in the list of values returned by the handle resolution. Because the order of that list is nondeterministic, there is no intelligent selection of a URL to which the client would be redirected. The 10320/loc handle value type was developed to improve the selection of specific resource URLs and to add features to the handle-to-URL resolution process. (Note that the prefix '10320' has been set aside by the Handle System administrator for handle application types.)

Type 10320/loc specifies an XML-formatted handle value that contains a list of locations. Each location has a set of associated attributes that help determine if or when that location is used. The overall list of locations can include hints for how the resolving client should select a location, including an ordered set of selection methods. Resolvers can apply each known selection method, in order, to choose a location based on the resolver's context (the HTTP request in the case of the proxy server) and the attributes of each location.

The attributes for the set of locations, as well as each location entry in the set, are open-ended to allow for future capabilities to be added in a backwards-compatible way. A small number of attributes have been defined as "standard" that all resolvers should understand.

At the top level of the XML structure are the following defined attributes:

chooseby (optional)
The chooseby attribute identifies a comma-delimited list of selection methods. If no chooseby attribute is specified then the default (currently "locatt,country,weighted") is assumed.

For each location the following attributes are defined:

href (required)
The URL for the location.
weight (optional)
The weight (from zero to one) that should apply to this location when performing a random selection. Setting the weight attribute to zero results in the location not being selected unless a) it is explicitly referenced by another attribute; b) there are no other suitable locations; or c) the location is selected based on one of the other selection methods, such as country or language. If a location has no weight attribute then it is assumed to have a weight of one.

The currently defined selection methods are:

locatt
Select only locations from an attribute passed in the proxy/handle-URI link. If someone constructs a link as hdl:123/456?locatt=id:1 then the resolver will return the locations that have an "id" attribute of 1 (i.e., the second location in the resolution example below). The locatt mechanism also handles content negotiation.
country
Selects only locations that have a 'country' attribute matching the country of the client. If no matching locations are found then this selects locations that have no country attribute (i.e., not a mismatch). The Proxy determines the country of the client using a GeoIP lookup.
weight
Selects a single location based on a random choice. The Proxy will observe the 'weight' attribute for each location, which should be a floating point non-negative number. The weighting allows for a very basic load balancing, but is also a way to ensure that some locations can only be addressed directly (for example by country or locatt/attributes). If the weighted selection method is applied to locations that all have non-positive weights, then this selects one of the remaining locations randomly while disregarding location weights.

The Proxy will iterate over the known selection methods, in order, until a single location has been selected. After each iteration the Proxy will take one of four steps:

  • if there is only one remaining location element, it is returned as a redirect;
  • if there are no remaining location elements, the Proxy reverts to the location elements as they were before the last method was applied;
  • if there are multiple location elements the Proxy will apply the remaining selection methods to those locations;
  • if there are no more selection methods to try, the weighted random selection method is applied, which is guaranteed to return a single location. In a sense, the weighted random is always the "fallback".
 

Content Negotiation

The proxy supports HTTP content negotiation by observing the client's "Accept:" and "Accept-Language:" headers and translating their contents into a list of "locatt" parameters, which then filter the available locations in turn. These generated "locatt" parameters are considered to follow the parameters directly supplied in the query string of the request; thus the query parameters will filter the locations before content negotiation headers take effect.

First, the "Accept:" header is parsed into a list a mime-types sorted by client preference. If the most preferred mime-type is a standard browser mime-type (e.g. text/html) then the "Accept:" header is ignored. Otherwise "locatt=http_role:conneg" is added, followed by "locatt=ctype:mime-type" for each mime-type in order. Thus a <location> element can use http_role="conneg" to handle all atypical mime-type conneg requests, or ctype="mime-type" to handle a particular mime-type.

Next, the "Accept-Language" header is parsed into a list of languages sorted by client preference. For each language "locatt=language:language" is added. The languages are coerced to lower case.

For example the following headers

Accept: application/rdf+xml, application/xml;q=0.6
Accept-Language: en-US, en;q=0.5

would result in these "locatt" parameters:

locatt=http_role:conneg&locatt=ctype:application/rdf+xml&locatt=ctype:application/xml&locatt=language:en-us&locatt=language:en

 

Example

For handle 123/456, with a value type 10320/loc that has this list of location attributes:

  <locations>
    <location id="0" href="http://uk.example.com/" country="gb" weight="0" />
    <location id="1" href="http://www1.example.com/" weight="1" />
    <location id="2" href="http://www2.example.com/" weight="1" />
  </locations>

the following selections could be made:

Reference: 123/456 from a client located in the UK
Result: The "country" selection method selects the first location based on the 'country' attribute of the first location and the client's position.

Reference: 123/456 from a client located outside the UK
Result: The "country" selection method removes the first location from consideration based on its 'country' attribute and chooses one of the last two locations using the "weighted" random selection method.

Reference: 123/456?locatt=id:1
Result: The second location is used based on the "locatt" selection method and the 'id' attribute.

Reference: 123/456?locatt=id:0
Result: The first location is used based on the "locatt" selection method and the 'id' attribute. The resolver never gets to the "country" selection method as the "locatt" selection method resulted in only a single matching location.

Reference: 123/456?locatt=country:uk
Result: The first location is used based on the "locatt" selection method and the 'country' attribute.

Reference: 123/456?locatt=country:us
Result: The "country" selection method removes the first location from consideration based on its 'country' attribute, finds no US-specific location, and chooses one of the last two locations using the "weighted" random selection method.

spacer