org.restlet.data

## Class ClientInfo

- java.lang.Object
- - 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

Constructors
Constructor and Description
`ClientInfo()` Constructor.
`ClientInfo(java.util.List<? extends Variant> variants)` Constructor from a list of variants.
`ClientInfo(MediaType mediaType)` Constructor from a media type.

### Method Summary

Methods
`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 immediate client's IP address.
`java.util.List<java.lang.String>` `getAddresses()` Deprecated. Use the `getForwardedAddresses()` method instead.
`java.lang.String` `getAgent()` Returns the agent name (ex: "Restlet-Framework/2.0").
`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.
`java.util.List<Expectation>` `getExpectations()` Returns the client expectations.
`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.
`Product` `getMainAgentProduct()` Returns a Product object based on the name of the user agent.
`int` `getPort()` Returns the port number which sent the call.
`CharacterSet` `getPreferredCharacterSet(java.util.List<CharacterSet> supported)` Returns the preferred character set among a list of supported ones, based on the client preferences.
`Encoding` `getPreferredEncoding(java.util.List<Encoding> supported)` Returns the preferred encoding among a list of supported ones, based on the client preferences.
`Language` `getPreferredLanguage(java.util.List<Language> supported)` Returns the preferred language among a list of supported ones, based on the client preferences.
`MediaType` `getPreferredMediaType(java.util.List<MediaType> supported)` Returns the preferred media type among a list of supported ones, based on the client preferences.
`Variant` `getPreferredVariant(java.util.List<? extends Variant> variants, MetadataService metadataService)` Returns the best variant for a given resource according the the client preferences: accepted languages, accepted character sets, accepted media types and accepted encodings.
`Variant` `getPreferredVariant(Resource resource, MetadataService metadataService)` Deprecated. Used `getPreferredVariant(List, org.restlet.service.MetadataService)` instead.
`java.util.List<java.security.Principal>` `getPrincipals()` Returns the additional client principals.
`java.util.List<Role>` `getRoles()` Returns the authenticated user roles.
`java.lang.String` `getUpstreamAddress()` Returns the IP address of the upstream client component.
`User` `getUser()` Returns the authenticated user.
`boolean` `isAuthenticated()` Indicates if the identifier or principal has been authenticated.
`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)` Deprecated. See the `setForwardedAddresses(List)` method instead.
`void` `setAgent(java.lang.String agent)` Sets the agent name (ex: "Restlet-Framework/2.0").
`void` `setAgentAttributes(java.util.Map<java.lang.String,java.lang.String> agentAttributes)` Sets a list of attributes taken from the name of the user agent.
`void` `setAgentProducts(java.util.List<Product> agentProducts)` Sets the list of product tokens from the user agent name.
`void` `setAuthenticated(boolean authenticated)` Indicates if the identifier or principal has been authenticated.
`void` `setExpectations(java.util.List<Expectation> expectations)` Sets the client expectations.
`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.
`void` `setPrincipals(java.util.List<java.security.Principal> principals)` Sets the additional client principals.
`void` `setRoles(java.util.List<Role> roles)` Sets the authenticated user roles.
`void` `setUser(User user)` Sets the authenticated user.

### 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(java.util.List<? extends Variant> variants)

Constructor from a list of variants. Note that only media types are taken into account.

Parameters:
  `variants` - The variants corresponding to the accepted media types.

#### ClientInfo

    public ClientInfo(MediaType mediaType)

Constructor from a media type.

Parameters:
  `mediaType` - The preferred media type.

### 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.
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.

#### 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()`

#### getAddresses

    @Deprecated
    public java.util.List<java.lang.String> getAddresses()

Deprecated. Use the `getForwardedAddresses()` method instead.
Returns the 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: "Restlet-Framework/2.0"). Note that when used with HTTP connectors, this property maps to the "User-Agent" header.

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.
See Also:
  `getAgent()`

#### getAgentName

    public java.lang.String getAgentName()

Returns the name of the user agent.

Returns:
  The name of the user agent.
See Also:
  `getAgent()`

#### 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.
See Also:
  `getAgent()`

#### getAgentVersion

    public java.lang.String getAgentVersion()

Returns the version of the user agent.

Returns:
  The version of the user agent.
See Also:
  `getAgent()`

#### getExpectations

    public java.util.List<Expectation> getExpectations()

Returns the client expectations.

Returns:
  The client expectations.

#### 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.

#### 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.

#### getPreferredCharacterSet

    public CharacterSet getPreferredCharacterSet(java.util.List<CharacterSet> supported)

Returns the preferred character set among a list of supported ones, based on the client preferences.

Parameters:
  `supported` - The supported character sets.
Returns:
  The preferred character set.

#### getPreferredEncoding

    public Encoding getPreferredEncoding(java.util.List<Encoding> supported)

Returns the preferred encoding among a list of supported ones, based on the client preferences.

Parameters:
  `supported` - The supported encodings.
Returns:
  The preferred encoding.

#### getPreferredLanguage

    public Language getPreferredLanguage(java.util.List<Language> supported)

Returns the preferred language among a list of supported ones, based on the client preferences.

Parameters:
  `supported` - The supported languages.
Returns:
  The preferred language.

#### getPreferredMediaType

    public MediaType getPreferredMediaType(java.util.List<MediaType> supported)

Returns the preferred media type among a list of supported ones, based on the client preferences.

Parameters:
  `supported` - The supported media types.
Returns:
  The preferred media type.

#### getPreferredVariant

    public Variant getPreferredVariant(java.util.List<? extends Variant> variants,
                              MetadataService metadataService)

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.
  `metadataService` - The metadata service.
Returns:
  The best variant.
See Also:
  Apache content negotiation algorithm

#### getPreferredVariant

    @Deprecated
    public Variant getPreferredVariant(Resource resource,
                                         MetadataService metadataService)

Deprecated. Used `getPreferredVariant(List, org.restlet.service.MetadataService)` instead.
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.
  `metadataService` - The metadata service.
Returns:
  The best variant.
See Also:
  Apache content negotiation algorithm

#### getPrincipals

    public java.util.List<java.security.Principal> getPrincipals()

Returns the additional client principals. Note that `getUser()` and `getRoles()` methods already return user and role principals.

Returns:
  The additional client principals.

#### getRoles

    public java.util.List<Role> getRoles()

Returns the authenticated user roles.

Returns:
  The authenticated user roles.

#### getUpstreamAddress

    public java.lang.String getUpstreamAddress()

Returns the IP address of the upstream client component. In general this will correspond the the user agent IP address. This is useful if there are intermediary components like proxies and load balancers. If the supporting `getForwardedAddresses()` method returns a non empty list, the IP address will be the first element. Otherwise, the value of `getAddress()` will be returned.
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 most upstream IP address.
See Also:
  `getAddress()`, `getForwardedAddresses()`

#### getUser

    public User getUser()

Returns the authenticated user.

Returns:
  The authenticated user.

#### isAuthenticated

    public boolean isAuthenticated()

Indicates if the identifier or principal has been authenticated. The application is responsible for updating this property, relying on a `Guard` or manually.

Returns:
  True if the identifier or principal has been authenticated.

#### 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.

#### setAddress

    public void setAddress(java.lang.String address)

Sets the client's IP address.

Parameters:
  `address` - The client's IP address.

#### setAddresses

    @Deprecated
    public void setAddresses(java.util.List<java.lang.String> addresses)

Deprecated. See the `setForwardedAddresses(List)` method instead.
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: "Restlet-Framework/2.0"). Note that when used with HTTP connectors, this property maps to the "User-Agent" header.

Parameters:
  `agent` - The agent name.

#### setAgentAttributes

    public void setAgentAttributes(java.util.Map<java.lang.String,java.lang.String> agentAttributes)

Sets a list of attributes taken from the name of the user agent.

Parameters:
  `agentAttributes` - A list of attributes taken from the name of the user agent.

#### setAgentProducts

    public void setAgentProducts(java.util.List<Product> agentProducts)

Sets the list of product tokens from the user agent name.

Parameters:
  `agentProducts` - The list of product tokens from the user agent name.

#### setAuthenticated

    public void setAuthenticated(boolean authenticated)

Indicates if the identifier or principal has been authenticated. The application is responsible for updating this property, relying on a `Guard` or manually.

Parameters:
  `authenticated` - True if the identifier or principal has been authenticated.

#### setExpectations

    public void setExpectations(java.util.List<Expectation> expectations)

Sets the client expectations.

Parameters:
  `expectations` - The client expectations.

#### 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.

#### setPrincipals

    public void setPrincipals(java.util.List<java.security.Principal> principals)

Sets the additional client principals.

Parameters:
  `principals` - The additional client principals.
See Also:
  `getPrincipals()`

#### setRoles

    public void setRoles(java.util.List<Role> roles)

Sets the authenticated user roles.

Parameters:
  `roles` - The authenticated user roles.

#### setUser

    public void setUser(User user)

Sets the authenticated user.

Parameters:
  `user` - The authenticated user.