org.restlet.data
Class ClientInfo

java.lang.Object
  extended by org.restlet.data.ClientInfo

public final class ClientInfo
extends java.lang.Object

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 Product instance with the main data (name, version, comment). This instance is accessible via the getMainAgentProduct() method. All other variables used in the template aims at catching a sequence of characters and are accessible via the getAgentAttributes() method.

Author:
Jerome Louvel

Constructor Summary
ClientInfo()
          Constructor.
 
Method Summary
 java.util.List<Preference<CharacterSet>> getAcceptedCharacterSets()
          Returns the modifiable list of character set preferences.
 java.util.List<Preference<Encoding>> getAcceptedEncodings()
          Returns the modifiable list of encoding preferences.
 java.util.List<Preference<Language>> getAcceptedLanguages()
          Returns the modifiable list of language preferences.
 java.util.List<Preference<MediaType>> getAcceptedMediaTypes()
          Returns the modifiable list of media type preferences.
 java.lang.String getAddress()
          Returns the client's IP address which is the first address in the list of client addresses, if this list exists and isn't empty.
 java.util.List<java.lang.String> getAddresses()
          Returns the modifiable list of client IP addresses.

The first address is the one of the immediate client component as returned by the getClientAdress() method and the last address should correspond to the origin client (frequently a user agent).

This is useful when the user agent is separated from the origin server by a chain of intermediary components.
 java.lang.String getAgent()
          Returns the agent name (ex: "Noelios-Restlet-Engine/1.1").
 java.util.Map<java.lang.String,java.lang.String> getAgentAttributes()
          Returns a list of attributes taken from the name of the user agent.
 java.lang.String getAgentName()
          Returns the name of the user agent.
 java.util.List<Product> getAgentProducts()
          Returns the list of product tokens from the user agent name.
 java.lang.String getAgentVersion()
          Returns the version of the user agent.
 Product getMainAgentProduct()
          Returns a Product object based on the name of the user agent.
 int getPort()
          Returns the port number which sent the call.
 Variant getPreferredVariant(java.util.List<Variant> variants, Language defaultLanguage)
          Returns the best variant for a given resource according the the client preferences: accepted languages, accepted character sets, accepted media types and accepted encodings.
A default language is provided in case the variants don't match the client preferences.
 Variant getPreferredVariant(Resource resource, Language defaultLanguage)
          Returns the best variant for a given resource according the the client preferences.
A default language is provided in case the resource's variants don't match the client preferences.
 void setAcceptedCharacterSets(java.util.List<Preference<CharacterSet>> acceptedCharacterSets)
          Sets the character set preferences.
 void setAcceptedEncodings(java.util.List<Preference<Encoding>> acceptedEncodings)
          Sets the encoding preferences.
 void setAcceptedLanguages(java.util.List<Preference<Language>> acceptedLanguages)
          Sets the language preferences.
 void setAcceptedMediaTypes(java.util.List<Preference<MediaType>> acceptedMediaTypes)
          Sets the media type preferences.
 void setAddress(java.lang.String address)
          Sets the client's IP address.
 void setAddresses(java.util.List<java.lang.String> addresses)
          Sets the list of client IP addresses.
 void setAgent(java.lang.String agent)
          Sets the agent name (ex: "Noelios Restlet Engine/1.1").
 void setPort(int port)
          Sets the port number which sent the call.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ClientInfo

public ClientInfo()
Constructor.

Method Detail

getAcceptedCharacterSets

public java.util.List<Preference<CharacterSet>> getAcceptedCharacterSets()
Returns the modifiable list of character set preferences. Creates a new instance if no one has been set.

Returns:
The character set preferences.

getAcceptedEncodings

public java.util.List<Preference<Encoding>> getAcceptedEncodings()
Returns the modifiable list of encoding preferences. Creates a new instance if no one has been set.

Returns:
The encoding preferences.

getAcceptedLanguages

public java.util.List<Preference<Language>> getAcceptedLanguages()
Returns the modifiable list of language preferences. Creates a new instance if no one has been set.

Returns:
The language preferences.

getAcceptedMediaTypes

public java.util.List<Preference<MediaType>> getAcceptedMediaTypes()
Returns the modifiable list of media type preferences. Creates a new instance if no one has been set.

Returns:
The media type preferences.

getAddress

public java.lang.String getAddress()
Returns the client's IP address which is the first address in the list of client addresses, if this list exists and isn't empty.

Returns:
The client's IP address.

getAddresses

public java.util.List<java.lang.String> getAddresses()
Returns the modifiable list of client IP addresses.

The first address is the one of the immediate client component as returned by the getClientAdress() method and the last address should correspond to the origin client (frequently a user agent).

This is useful when the user agent is separated from the origin server by a chain of intermediary components. Creates a new instance if no one has been set.

Returns:
The client IP addresses.

getAgent

public java.lang.String getAgent()
Returns the agent name (ex: "Noelios-Restlet-Engine/1.1").

Returns:
The agent name.

getAgentAttributes

public java.util.Map<java.lang.String,java.lang.String> getAgentAttributes()
Returns a list of attributes taken from the name of the user agent.

Returns:
A list of attributes taken from the name of the user agent.

getAgentName

public java.lang.String getAgentName()
Returns the name of the user agent.

Returns:
The name of the user agent.

getAgentProducts

public java.util.List<Product> getAgentProducts()
Returns the list of product tokens from the user agent name.

Returns:
The list of product tokens from the user agent name.

getAgentVersion

public java.lang.String getAgentVersion()
Returns the version of the user agent.

Returns:
The version of the user agent.

getMainAgentProduct

public Product getMainAgentProduct()
Returns a Product object based on the name of the user agent.

Returns:
A Product object based on name of the user agent.

getPort

public int getPort()
Returns the port number which sent the call. If no port is specified, -1 is returned.

Returns:
The port number which sent the call.

getPreferredVariant

public Variant getPreferredVariant(java.util.List<Variant> variants,
                                   Language defaultLanguage)
Returns the best variant for a given resource according the the client preferences: accepted languages, accepted character sets, accepted media types and accepted encodings.
A default language is provided in case the variants don't match the client preferences.

Parameters:
variants - The list of variants to compare.
defaultLanguage - The default language.
Returns:
The best variant.
See Also:
Apache content negotiation algorithm

getPreferredVariant

public Variant getPreferredVariant(Resource resource,
                                   Language defaultLanguage)
Returns the best variant for a given resource according the the client preferences.
A default language is provided in case the resource's variants don't match the client preferences.

Parameters:
resource - The resource for which the best representation needs to be set.
defaultLanguage - The default language.
Returns:
The best variant.
See Also:
Apache content negotiation algorithm

setAcceptedCharacterSets

public void setAcceptedCharacterSets(java.util.List<Preference<CharacterSet>> acceptedCharacterSets)
Sets the character set preferences.

Parameters:
acceptedCharacterSets - The character set preferences.

setAcceptedEncodings

public void setAcceptedEncodings(java.util.List<Preference<Encoding>> acceptedEncodings)
Sets the encoding preferences.

Parameters:
acceptedEncodings - The encoding preferences.

setAcceptedLanguages

public void setAcceptedLanguages(java.util.List<Preference<Language>> acceptedLanguages)
Sets the language preferences.

Parameters:
acceptedLanguages - The language preferences.

setAcceptedMediaTypes

public void setAcceptedMediaTypes(java.util.List<Preference<MediaType>> acceptedMediaTypes)
Sets the media type preferences.

Parameters:
acceptedMediaTypes - The media type preferences.

setAddress

public void setAddress(java.lang.String address)
Sets the client's IP address.

Parameters:
address - The client's IP address.

setAddresses

public void setAddresses(java.util.List<java.lang.String> addresses)
Sets the list of client IP addresses.

Parameters:
addresses - The list of client IP addresses.

setAgent

public void setAgent(java.lang.String agent)
Sets the agent name (ex: "Noelios Restlet Engine/1.1").

Parameters:
agent - The agent name.

setPort

public void setPort(int port)
Sets the port number which sent the call.

Parameters:
port - The port number which sent the call.


Copyright © 2005-2008 Noelios Technologies.