Client specific data related to a call. When extracted from a request, most of these data are directly taken from the underlying headers. There are some exceptions: agentAttributes and mainAgentProduct which are taken from the agent name (for example the "user-agent" header for HTTP requests).
As described by the HTTP specification, the "user-agent" can be seen as a ordered list of products name (ie a name and a version) and/or comments.
Each HTTP client (mainly browsers and web crawlers) defines its own "user-agent" header which can be seen as the "signature" of the client. Unfortunately, there is no rule to identify clearly a kind a client and its version (let's say Firefox 2.x, Internet Explorer IE 7.0, Opera, etc) according to its signature. Each signature follow its own rules which may vary according to the version of the client.
In order to help retrieving interesting data such as product name (Firefox, IE, etc), version, operating system, Restlet users has the ability to define their own way to extract data from the "user-agent" header. It is based on a list of templates declared in a file called "agent.properties" and located in the classpath in the sub directory "org/restlet/data". Each template describes a typical user-agent string and allows to use predefined variables that help to retrieve the content of the agent name, version, operating system.
The "user-agent" string is confronted to the each template from the beginning of the property file to the end. The loop stops at the first matched template.
Here is a sample of such template:
#Firefox for Windows Mozilla/{mozillaVersion} (Windows; U; {agentOs}; {osData}; rv:{releaseVersion}) Gecko/{geckoReleaseDate} {agentName}/{agentVersion} This template matches the "user-agent" string of the Firefox client for windows:
Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1) Gecko/20060918 Firefox/2.0
At this time, six predefined variables are used:
| Name | Description |
| agentName | Name of the user agent (i.e.: Firefox) |
| agentVersion | Version of the user agent |
| agentOs | Operating system of the user agent |
| agentComment | Comment string, that is to say a sequence of characters enclosed "(", or ")" |
| commentAttribute | A sequence of characters enclosed by ";", "(", or ")" |
| facultativeData | A sequence of characters that can be empty |
These variables are used to generate a {@link Product} instance with the maindata (name, version, comment). This instance is accessible via the {@link ClientInfo#getMainAgentProduct()} method. All other variables used inthe template aims at catching a sequence of characters and are accessible via the {@link ClientInfo#getAgentAttributes()} method.
@author Jerome Louvel