ClientInfo (Restlet API 2.4.4 - Google Web Toolkit)

java.lang.Object
- org.restlet.client.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 ClientInfo#getMainAgentProduct() method. All other variables used in the template aims at catching a sequence of characters and are accessible via the ClientInfo#getAgentAttributes() method.

Author:: Jerome Louvel

Constructor Summary

Constructors
Constructor and Description

ClientInfo()
Constructor.

ClientInfo(MediaType mediaType)
Constructor from a media type.

Constructors
Constructor and Description
`ClientInfo()` Constructor.
`ClientInfo(MediaType mediaType)` Constructor from a media type.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`accept(Metadata... metadata)` Updates the client preferences to accept the given metadata (media types, character sets, etc.) with a 1.0 quality in addition to existing ones.
`void`	`accept(Metadata metadata, float quality)` Updates the client preferences to accept the given metadata (media types, character sets, etc.) with a given quality in addition to existing ones.
`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.util.List<Preference<MediaType>>`	`getAcceptedPatches()` Returns the modifiable list of patch preferences.
`java.lang.String`	`getAddress()` Returns the immediate client's IP address.
`java.lang.String`	`getAgent()` Returns the agent name (ex: "Restlet-Framework/2.0").
`java.util.List<java.lang.String>`	`getForwardedAddresses()` Returns the list of forwarded IP addresses.
`java.lang.String`	`getFrom()` Returns the email address of the human user controlling the user agent.
`int`	`getPort()` Returns the port number which sent the call.
`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`	`setAcceptedPatches(java.util.List<Preference<MediaType>> acceptedPatches)` Sets the patch preferences.
`void`	`setAddress(java.lang.String address)` Sets the client's IP address.
`void`	`setAgent(java.lang.String agent)` Sets the agent name (ex: "Restlet-Framework/2.0").
`void`	`setForwardedAddresses(java.util.List<java.lang.String> forwardedAddresses)` Sets the list of forwarded IP addresses.
`void`	`setFrom(java.lang.String from)` Sets the email address of the human user controlling the user agent.
`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.
  - ClientInfo
```
public ClientInfo(MediaType mediaType)
```
    Constructor from a media type.
    
    Parameters:
    
    mediaType - The preferred media type.
- Method Detail
  - accept
```
public void accept(Metadata... metadata)
```
    Updates the client preferences to accept the given metadata (media types, character sets, etc.) with a 1.0 quality in addition to existing ones.
    
    Parameters:
    
    metadata - The metadata to accept.
  - accept
```
public void accept(Metadata metadata,
                   float quality)
```
    Updates the client preferences to accept the given metadata (media types, character sets, etc.) with a given quality in addition to existing ones.
    
    Parameters:
    
    metadata - The metadata to accept.
    
    quality - The quality to set.
  - 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.
    
    Note that when used with HTTP connectors, this property maps to the "Accept-Charset" header.
    
    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.
    
    Note that when used with HTTP connectors, this property maps to the "Accept-Encoding" header.
    
    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.
    
    Note that when used with HTTP connectors, this property maps to the "Accept-Language" header.
    
    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.
    
    Note that when used with HTTP connectors, this property maps to the "Accept" header.
    
    Returns:
    
    The media type preferences.
  - getAcceptedPatches
```
public java.util.List<Preference<MediaType>> getAcceptedPatches()
```
    Returns the modifiable list of patch preferences. Creates a new instance if no one has been set.
    
    Note that when used with HTTP connectors, this property maps to the "Accept-Patch" header.
    
    Returns:
    
    The patch preferences.
  - getAddress
```
public java.lang.String getAddress()
```
    Returns the immediate client's IP address. If the real client is separated from the server by a proxy server, this will return the IP address of the proxy.
    
    Returns:
    
    The immediate client's IP address.
    
    See Also:
    
    #getUpstreamAddress(), getForwardedAddresses()
  - getAgent
```
public java.lang.String getAgent()
```
    Returns the agent name (ex: "Restlet-Framework/2.0"). Note that when used with HTTP connectors, this property maps to the "User-Agent" header.
    
    Returns:
    
    The agent name.
  - getForwardedAddresses
```
public java.util.List<java.lang.String> getForwardedAddresses()
```
    Returns the list of forwarded IP addresses. 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.
    
    The first address is the one of the immediate client component and the last address should correspond to the origin client (frequently a user agent).
    
    This information is only safe for intermediary components within your local network. Other addresses could easily be changed by setting a fake header and should not be trusted for serious security checks.
    
    Note that your HTTP server connectors need to have a special "useForwardedForHeader" parameter explicitly set to "true" in order to activate this feature, due to potential security issues.
    
    Returns:
    
    The list of forwarded IP addresses.
    
    See Also:
    
    #getUpstreamAddress(), Wikipedia page for the "X-Forwarded-For" HTTP header
  - getFrom
```
public java.lang.String getFrom()
```
    Returns the email address of the human user controlling the user agent. Default value is null.
    
    Returns:
    
    The email address of the human user controlling 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.
  - setAcceptedCharacterSets
```
public void setAcceptedCharacterSets(java.util.List<Preference<CharacterSet>> acceptedCharacterSets)
```
    Sets the character set preferences. Note that when used with HTTP connectors, this property maps to the "Accept-Charset" header.
    
    Parameters:
    
    acceptedCharacterSets - The character set preferences.
  - setAcceptedEncodings
```
public void setAcceptedEncodings(java.util.List<Preference<Encoding>> acceptedEncodings)
```
    Sets the encoding preferences. Note that when used with HTTP connectors, this property maps to the "Accept-Encoding" header.
    
    Parameters:
    
    acceptedEncodings - The encoding preferences.
  - setAcceptedLanguages
```
public void setAcceptedLanguages(java.util.List<Preference<Language>> acceptedLanguages)
```
    Sets the language preferences. Note that when used with HTTP connectors, this property maps to the "Accept-Language" header.
    
    Parameters:
    
    acceptedLanguages - The language preferences.
  - setAcceptedMediaTypes
```
public void setAcceptedMediaTypes(java.util.List<Preference<MediaType>> acceptedMediaTypes)
```
    Sets the media type preferences. Note that when used with HTTP connectors, this property maps to the "Accept" header.
    
    Parameters:
    
    acceptedMediaTypes - The media type preferences.
  - setAcceptedPatches
```
public void setAcceptedPatches(java.util.List<Preference<MediaType>> acceptedPatches)
```
    Sets the patch preferences. Note that when used with HTTP connectors, this property maps to the "Accept-Patch" header.
    
    Parameters:
    
    acceptedPatches - 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.
  - setAgent
```
public void setAgent(java.lang.String agent)
```
    Sets the agent name (ex: "Restlet-Framework/2.0"). Note that when used with HTTP connectors, this property maps to the "User-Agent" header.
    
    Parameters:
    
    agent - The agent name.
  - setForwardedAddresses
```
public void setForwardedAddresses(java.util.List<java.lang.String> forwardedAddresses)
```
    Sets the list of forwarded IP addresses.
    
    Parameters:
    
    forwardedAddresses - The list of forwarded IP addresses.
    
    See Also:
    
    getForwardedAddresses()
  - setFrom
```
public void setFrom(java.lang.String from)
```
    Sets the email address of the human user controlling the user agent.
    
    Parameters:
    
    from - The email address of the human user controlling the user agent.
  - setPort
```
public void setPort(int port)
```
    Sets the port number which sent the call.
    
    Parameters:
    
    port - The port number which sent the call.

Class ClientInfo

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ClientInfo

ClientInfo

Method Detail

accept

accept

getAcceptedCharacterSets

getAcceptedEncodings

getAcceptedLanguages

getAcceptedMediaTypes

getAcceptedPatches

getAddress

getAgent

getForwardedAddresses

getFrom

getPort

setAcceptedCharacterSets

setAcceptedEncodings

setAcceptedLanguages

setAcceptedMediaTypes

setAcceptedPatches

setAddress

setAgent

setForwardedAddresses

setFrom

setPort