|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.restlet.data.ClientInfo
public final class ClientInfo
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.0At 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 |
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.
Constructor Summary | |
---|---|
ClientInfo()
Constructor. |
|
ClientInfo(List<? extends Variant> variants)
Constructor from a list of variants. |
|
ClientInfo(MediaType mediaType)
Constructor from a media type. |
Method Summary | ||
---|---|---|
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. |
|
List<Preference<CharacterSet>> |
getAcceptedCharacterSets()
Returns the modifiable list of character set preferences. |
|
List<Preference<Encoding>> |
getAcceptedEncodings()
Returns the modifiable list of encoding preferences. |
|
List<Preference<Language>> |
getAcceptedLanguages()
Returns the modifiable list of language preferences. |
|
List<Preference<MediaType>> |
getAcceptedMediaTypes()
Returns the modifiable list of media type preferences. |
|
String |
getAddress()
Returns the immediate client's IP address. |
|
String |
getAgent()
Returns the agent name (ex: "Restlet-Framework/2.0"). |
|
Map<String,String> |
getAgentAttributes()
Returns a list of attributes taken from the name of the user agent. |
|
String |
getAgentName()
Returns the name of the user agent. |
|
List<Product> |
getAgentProducts()
Returns the list of product tokens from the user agent name. |
|
String |
getAgentVersion()
Returns the version of the user agent. |
|
List<Certificate> |
getCertificates()
Returns the client certificates. |
|
String |
getCipherSuite()
Returns the SSL Cipher Suite, if available and accessible. |
|
List<Expectation> |
getExpectations()
Returns the client expectations. |
|
List<String> |
getForwardedAddresses()
Returns the list of forwarded IP addresses. |
|
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(List<CharacterSet> supported)
Returns the preferred character set among a list of supported ones, based on the client preferences. |
|
Encoding |
getPreferredEncoding(List<Encoding> supported)
Returns the preferred encoding among a list of supported ones, based on the client preferences. |
|
Language |
getPreferredLanguage(List<Language> supported)
Returns the preferred language among a list of supported ones, based on the client preferences. |
|
MediaType |
getPreferredMediaType(List<MediaType> supported)
Returns the preferred media type among a list of supported ones, based on the client preferences. |
|
static
|
getPreferredMetadata(List<T> supported,
List<Preference<T>> preferences)
Returns the preferred metadata taking into account both metadata supported by the server and client preferences. |
|
Variant |
getPreferredVariant(List<? extends Variant> variants)
Deprecated. Use ConnegService instead. |
|
Variant |
getPreferredVariant(List<? extends Variant> variants,
MetadataService metadataService)
Deprecated. Use the getPreferredVariant(List) method instead. |
|
List<Principal> |
getPrincipals()
Returns the additional client principals. |
|
List<Role> |
getRoles()
Returns the authenticated user roles. |
|
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(List<Preference<CharacterSet>> acceptedCharacterSets)
Sets the character set preferences. |
|
void |
setAcceptedEncodings(List<Preference<Encoding>> acceptedEncodings)
Sets the encoding preferences. |
|
void |
setAcceptedLanguages(List<Preference<Language>> acceptedLanguages)
Sets the language preferences. |
|
void |
setAcceptedMediaTypes(List<Preference<MediaType>> acceptedMediaTypes)
Sets the media type preferences. |
|
void |
setAddress(String address)
Sets the client's IP address. |
|
void |
setAgent(String agent)
Sets the agent name (ex: "Restlet-Framework/2.0"). |
|
void |
setAgentAttributes(Map<String,String> agentAttributes)
Sets a list of attributes taken from the name of the user agent. |
|
void |
setAgentProducts(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 |
setCertificates(List<Certificate> certificates)
Sets the new client certificates. |
|
void |
setCipherSuite(String cipherSuite)
Sets the SSL Cipher Suite, if available and accessible. |
|
void |
setExpectations(List<Expectation> expectations)
Sets the client expectations. |
|
void |
setForwardedAddresses(List<String> forwardedAddresses)
Sets the list of forwarded IP addresses. |
|
void |
setFrom(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(List<Principal> principals)
Sets the additional client principals. |
|
void |
setRoles(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 |
---|
public ClientInfo()
public ClientInfo(List<? extends Variant> variants)
variants
- The variants corresponding to the accepted media types.public ClientInfo(MediaType mediaType)
mediaType
- The preferred media type.Method Detail |
---|
public static <T extends Metadata> T getPreferredMetadata(List<T> supported, List<Preference<T>> preferences)
supported
- The metadata supported by the server.preferences
- The client preferences.
public void accept(Metadata... metadata)
metadata
- The metadata to accept.public void accept(Metadata metadata, float quality)
metadata
- The metadata to accept.quality
- The quality to set.public List<Preference<CharacterSet>> getAcceptedCharacterSets()
public List<Preference<Encoding>> getAcceptedEncodings()
public List<Preference<Language>> getAcceptedLanguages()
public List<Preference<MediaType>> getAcceptedMediaTypes()
public String getAddress()
getUpstreamAddress()
,
getForwardedAddresses()
public String getAgent()
public Map<String,String> getAgentAttributes()
getAgent()
public String getAgentName()
getAgent()
public List<Product> getAgentProducts()
getAgent()
public String getAgentVersion()
getAgent()
public List<Certificate> getCertificates()
SSLSession
public String getCipherSuite()
SSLSession
public List<Expectation> getExpectations()
public List<String> getForwardedAddresses()
getUpstreamAddress()
,
Wikipedia
page for the "X-Forwarded-For" HTTP headerpublic String getFrom()
public Product getMainAgentProduct()
public int getPort()
public CharacterSet getPreferredCharacterSet(List<CharacterSet> supported)
supported
- The supported character sets.
public Encoding getPreferredEncoding(List<Encoding> supported)
supported
- The supported encodings.
public Language getPreferredLanguage(List<Language> supported)
supported
- The supported languages.
public MediaType getPreferredMediaType(List<MediaType> supported)
supported
- The supported media types.
@Deprecated public Variant getPreferredVariant(List<? extends Variant> variants)
ConnegService
instead.
ConnegService
and
MetadataService
of the parent application are first looked up. If
no parent application is found, a new instance of those services is
created and the
ConnegService.getPreferredVariant(List, Request, org.restlet.service.MetadataService)
method is called.
variants
- The list of variants to compare.
@Deprecated public Variant getPreferredVariant(List<? extends Variant> variants, MetadataService metadataService)
getPreferredVariant(List)
method instead.
ConnegService
of the parent
application is first looked up. If no parent application is found, a new
instance is created and the
ConnegService.getPreferredVariant(List, Request, org.restlet.service.MetadataService)
method is called.
variants
- The list of variants to compare.metadataService
- The metadata service.
public List<Principal> getPrincipals()
getUser()
and getRoles()
methods already return user and role principals.
public List<Role> getRoles()
public String getUpstreamAddress()
getForwardedAddresses()
method returns a non
empty list, the IP address will be the first element. Otherwise, the
value of getAddress()
will be returned.
getAddress()
,
getForwardedAddresses()
public User getUser()
public boolean isAuthenticated()
Authenticator
or manually.
public void setAcceptedCharacterSets(List<Preference<CharacterSet>> acceptedCharacterSets)
acceptedCharacterSets
- The character set preferences.public void setAcceptedEncodings(List<Preference<Encoding>> acceptedEncodings)
acceptedEncodings
- The encoding preferences.public void setAcceptedLanguages(List<Preference<Language>> acceptedLanguages)
acceptedLanguages
- The language preferences.public void setAcceptedMediaTypes(List<Preference<MediaType>> acceptedMediaTypes)
acceptedMediaTypes
- The media type preferences.public void setAddress(String address)
address
- The client's IP address.public void setAgent(String agent)
agent
- The agent name.public void setAgentAttributes(Map<String,String> agentAttributes)
agentAttributes
- A list of attributes taken from the name of the user agent.public void setAgentProducts(List<Product> agentProducts)
agentProducts
- The list of product tokens from the user agent name.public void setAuthenticated(boolean authenticated)
Authenticator
or manually.
authenticated
- True if the identifier or principal has been authenticated.public void setCertificates(List<Certificate> certificates)
certificates
- The client certificates.getCertificates()
public void setCipherSuite(String cipherSuite)
cipherSuite
- The SSL Cipher Suite, if available and accessible.public void setExpectations(List<Expectation> expectations)
expectations
- The client expectations.public void setForwardedAddresses(List<String> forwardedAddresses)
forwardedAddresses
- The list of forwarded IP addresses.getForwardedAddresses()
public void setFrom(String from)
from
- The email address of the human user controlling the user
agent.public void setPort(int port)
port
- The port number which sent the call.public void setPrincipals(List<Principal> principals)
principals
- The additional client principals.getPrincipals()
public void setRoles(List<Role> roles)
roles
- The authenticated user roles.public void setUser(User user)
user
- The authenticated user.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |