org.restlet.service
Class TunnelService

java.lang.Object
  extended by org.restlet.service.Service
      extended by org.restlet.service.TunnelService

public class TunnelService
extends Service

Service tunneling request method or client preferences. The tunneling can use query parameters and file-like extensions. This is particularly useful for browser-based applications that can't fully control the HTTP requests sent.

Here is the list of the default parameter names supported:

Property Default name Value type Description
methodParameter method See values in Method For POST requests, let you specify the actual method to use (DELETE, PUT, MOVE, etc.). For GET requests, let you specify OPTIONS as the actual method to use.
characterSetParameter charset Use extension names defined in MetadataService For GET requests, replaces the accepted character set by the given value.
encodingParameter encoding Use extension names defined in MetadataService For GET requests, replaces the accepted encoding by the given value.
languageParameter language Use extension names defined in MetadataService For GET requests, replaces the accepted language by the given value.
mediaTypeParameter media Use extension names defined in MetadataService For GET requests, replaces the accepted media type set by the given value.

The client preferences can also be updated based on the extensions available in the last path segment. The syntax is similar to file extensions by allows several extensions to be present, in any particular order: e.g. "/path/foo.fr.txt"). This mechanism relies on the mapping between an extension and a metadata (e.g. "txt" => "text/plain") declared by the MetadataService.

The client preferences can also be updated according to the user agent properties (its name, version, operating system, or other) available via the ClientInfo.getAgentAttributes() method.

The list of new media type preferences is loaded from a property file called "accept.properties" located in the classpath in the sub directory "org/restlet/service". This property file is composed of blocks of properties. One "block" of properties starts either with the beginning of the properties file or with the end of the previous block. One block ends with the "acceptNew" property which contains the value of the new accept header. Here is a sample block.
 agentName: firefox
 acceptOld: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,\*\/\*;q=0.5
 acceptNew: application/xhtml+xml,text/html,text/xml;q=0.9,application/xml;q=0.9,text/plain;q=0.8,image/png,\*\/\*;q=0.5
 
Each declared property is a condition that must be filled in order to update the client preferences. For example "agentName: firefox" expresses the fact this block concerns only "firefox" clients.

The "acceptOld" property allows to check the value of the current "Accept" header. If the latest equals to the value of the "acceptOld" property then the preferences will be updated. This is useful for Ajax clients which looks like their browser (same agentName, agentVersion, etc.) but can provide their own "Accept" header.

Author:
Jerome Louvel

Constructor Summary
TunnelService(boolean methodTunnel, boolean preferencesTunnel)
          Constructor that enables the query tunnel and disables the extensions and user agent tunnels.
TunnelService(boolean enabled, boolean methodTunnel, boolean preferencesTunnel)
          Constructor that enables the query tunnel and disables the extensions and user agent tunnels.
TunnelService(boolean enabled, boolean methodTunnel, boolean preferencesTunnel, boolean queryTunnel, boolean extensionsTunnel)
          Constructor that disables the user agent tunnel.
TunnelService(boolean enabled, boolean methodTunnel, boolean preferencesTunnel, boolean queryTunnel, boolean extensionsTunnel, boolean userAgentTunnel)
          Constructor.
 
Method Summary
 boolean allowClient(ClientInfo client)
          Indicates if the request from a given client can be tunnelled.
 java.lang.String getCharacterSetAttribute()
          Deprecated. Use getCharacterSetParameter instead.
 java.lang.String getCharacterSetParameter()
          Returns the character set parameter name.
 java.lang.String getEncodingAttribute()
          Deprecated. Use getEncodingParameter instead.
 java.lang.String getEncodingParameter()
          Returns the name of the parameter containing the accepted encoding.
 java.lang.String getLanguageAttribute()
          Deprecated. Use getLanguageParameter instead.
 java.lang.String getLanguageParameter()
          Returns the name of the parameter containing the accepted language.
 java.lang.String getMediaTypeAttribute()
          Deprecated. Use getMediaTypeParameter instead.
 java.lang.String getMediaTypeParameter()
          Returns the name of the parameter containing the accepted media type.
 java.lang.String getMethodParameter()
          Returns the method parameter name.
 boolean isExtensionsTunnel()
          Indicates if the client preferences can be tunnelled via the extensions.
 boolean isMethodTunnel()
          Indicates if the method name can be tunnelled.
 boolean isPreferencesTunnel()
          Indicates if the client preferences can be tunnelled via the query parameters or file extensions.
 boolean isQueryTunnel()
          Indicates if the method and client preferences can be tunnelled via query parameters or file extensions.
 boolean isUserAgentTunnel()
          Indicates if the client preferences can be tunnelled according to the user agent.
 void setCharacterSetAttribute(java.lang.String parameterName)
          Deprecated. Use setCharacterSetParameter instead.
 void setCharacterSetParameter(java.lang.String parameterName)
          Sets the character set parameter name.
 void setEncodingAttribute(java.lang.String parameterName)
          Deprecated. Use setEncodingParameter instead.
 void setEncodingParameter(java.lang.String parameterName)
          Sets the name of the parameter containing the accepted encoding.
 void setExtensionsTunnel(boolean extensionTunnel)
          Indicates if the client preferences can be tunnelled via the extensions.
 void setLanguageAttribute(java.lang.String parameterName)
          Deprecated. Use setLanguageParameter instead.
 void setLanguageParameter(java.lang.String parameterName)
          Sets the name of the parameter containing the accepted language.
 void setMediaTypeAttribute(java.lang.String parameterName)
          Deprecated. Use setMediaTypeParameter instead.
 void setMediaTypeParameter(java.lang.String parameterName)
          Sets the name of the parameter containing the accepted media type.
 void setMethodParameter(java.lang.String parameterName)
          Sets the method parameter name.
 void setMethodTunnel(boolean methodTunnel)
          Indicates if the method name can be tunnelled.
 void setPreferencesTunnel(boolean preferencesTunnel)
          Indicates if the client preferences can be tunnelled via the query parameters.
 void setQueryTunnel(boolean queryTunnel)
          Indicates if the method and client preferences can be tunnelled via query parameters.
 void setUserAgentTunnel(boolean userAgentTunnel)
          Indicates if the client preferences can be tunnelled according to the user agent.
 
Methods inherited from class org.restlet.service.Service
isEnabled, isStarted, isStopped, setEnabled, start, stop
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TunnelService

public TunnelService(boolean methodTunnel,
                     boolean preferencesTunnel)
Constructor that enables the query tunnel and disables the extensions and user agent tunnels.

Parameters:
methodTunnel - Indicates if the method name can be tunnelled.
preferencesTunnel - Indicates if the client preferences can be tunnelled by query parameters or file-like extensions or user agent string.

TunnelService

public TunnelService(boolean enabled,
                     boolean methodTunnel,
                     boolean preferencesTunnel)
Constructor that enables the query tunnel and disables the extensions and user agent tunnels.

Parameters:
enabled - True if the service has been enabled.
methodTunnel - Indicates if the method name can be tunnelled.
preferencesTunnel - Indicates if the client preferences can be tunnelled by query parameters or file-like extensions or user agent string.

TunnelService

public TunnelService(boolean enabled,
                     boolean methodTunnel,
                     boolean preferencesTunnel,
                     boolean queryTunnel,
                     boolean extensionsTunnel)
Constructor that disables the user agent tunnel.

Parameters:
enabled - True if the service has been enabled.
methodTunnel - Indicates if the method can be tunnelled using a query parameter.
preferencesTunnel - Indicates if the client preferences can be tunnelled using query parameters or file-like extensions or user agent string.
queryTunnel - Indicates if tunneling can use query parameters.
extensionsTunnel - Indicates if tunneling can use file-like extensions.

TunnelService

public TunnelService(boolean enabled,
                     boolean methodTunnel,
                     boolean preferencesTunnel,
                     boolean queryTunnel,
                     boolean extensionsTunnel,
                     boolean userAgentTunnel)
Constructor.

Parameters:
enabled - True if the service has been enabled.
methodTunnel - Indicates if the method can be tunnelled using a query parameter.
preferencesTunnel - Indicates if the client preferences can be tunnelled using query parameters or file-like extensions or user agent string.
queryTunnel - Indicates if tunneling can use query parameters.
extensionsTunnel - Indicates if tunneling can use file-like extensions.
userAgentTunnel - Indicates if tunneling can use user agent string.
Method Detail

allowClient

public boolean allowClient(ClientInfo client)
Indicates if the request from a given client can be tunnelled. The default implementation always return true. This could be customize to restrict the usage of the tunnel service.

Parameters:
client - The client to test.
Returns:
True if the request from a given client can be tunnelled.

getCharacterSetAttribute

@Deprecated
public java.lang.String getCharacterSetAttribute()
Deprecated. Use getCharacterSetParameter instead.

Returns the character set parameter name.

Returns:
The character set parameter name.

getCharacterSetParameter

public java.lang.String getCharacterSetParameter()
Returns the character set parameter name.

Returns:
The character set parameter name.

getEncodingAttribute

@Deprecated
public java.lang.String getEncodingAttribute()
Deprecated. Use getEncodingParameter instead.

Returns the name of the parameter containing the accepted encoding.

Returns:
The name of the parameter containing the accepted encoding.

getEncodingParameter

public java.lang.String getEncodingParameter()
Returns the name of the parameter containing the accepted encoding.

Returns:
The name of the parameter containing the accepted encoding.

getLanguageAttribute

@Deprecated
public java.lang.String getLanguageAttribute()
Deprecated. Use getLanguageParameter instead.

Returns the name of the parameter containing the accepted language.

Returns:
The name of the parameter containing the accepted language.

getLanguageParameter

public java.lang.String getLanguageParameter()
Returns the name of the parameter containing the accepted language.

Returns:
The name of the parameter containing the accepted language.

getMediaTypeAttribute

@Deprecated
public java.lang.String getMediaTypeAttribute()
Deprecated. Use getMediaTypeParameter instead.

Returns the name of the parameter containing the accepted media type.

Returns:
The name of the parameter containing the accepted media type.

getMediaTypeParameter

public java.lang.String getMediaTypeParameter()
Returns the name of the parameter containing the accepted media type.

Returns:
The name of the parameter containing the accepted media type.

getMethodParameter

public java.lang.String getMethodParameter()
Returns the method parameter name.

Returns:
The method parameter name.

isExtensionsTunnel

public boolean isExtensionsTunnel()
Indicates if the client preferences can be tunnelled via the extensions.

Returns:
True if the client preferences can be tunnelled via the extensions
See Also:
Request.getOriginalRef()

isMethodTunnel

public boolean isMethodTunnel()
Indicates if the method name can be tunnelled.

Returns:
True if the method name can be tunnelled.

isPreferencesTunnel

public boolean isPreferencesTunnel()
Indicates if the client preferences can be tunnelled via the query parameters or file extensions.

Returns:
True if the client preferences can be tunnelled.

isQueryTunnel

public boolean isQueryTunnel()
Indicates if the method and client preferences can be tunnelled via query parameters or file extensions.

Returns:
True if the method and client preferences can be tunnelled.

isUserAgentTunnel

public boolean isUserAgentTunnel()
Indicates if the client preferences can be tunnelled according to the user agent.

Returns:
True if the client preferences can be tunnelled according to the user agent.

setCharacterSetAttribute

@Deprecated
public void setCharacterSetAttribute(java.lang.String parameterName)
Deprecated. Use setCharacterSetParameter instead.

Sets the character set parameter name.

Parameters:
parameterName - The character set parameter name.

setCharacterSetParameter

public void setCharacterSetParameter(java.lang.String parameterName)
Sets the character set parameter name.

Parameters:
parameterName - The character set parameter name.

setEncodingAttribute

@Deprecated
public void setEncodingAttribute(java.lang.String parameterName)
Deprecated. Use setEncodingParameter instead.

Sets the name of the parameter containing the accepted encoding.

Parameters:
parameterName - The name of the parameter containing the accepted encoding.

setEncodingParameter

public void setEncodingParameter(java.lang.String parameterName)
Sets the name of the parameter containing the accepted encoding.

Parameters:
parameterName - The name of the parameter containing the accepted encoding.

setExtensionsTunnel

public void setExtensionsTunnel(boolean extensionTunnel)
Indicates if the client preferences can be tunnelled via the extensions.

Parameters:
extensionTunnel - True if the client preferences can be tunnelled via the extensions.
See Also:
Request.getOriginalRef()

setLanguageAttribute

@Deprecated
public void setLanguageAttribute(java.lang.String parameterName)
Deprecated. Use setLanguageParameter instead.

Sets the name of the parameter containing the accepted language.

Parameters:
parameterName - The name of the parameter containing the accepted language.

setLanguageParameter

public void setLanguageParameter(java.lang.String parameterName)
Sets the name of the parameter containing the accepted language.

Parameters:
parameterName - The name of the parameter containing the accepted language.

setMediaTypeAttribute

@Deprecated
public void setMediaTypeAttribute(java.lang.String parameterName)
Deprecated. Use setMediaTypeParameter instead.

Sets the name of the parameter containing the accepted media type.

Parameters:
parameterName - The name of the parameter containing the accepted media type.

setMediaTypeParameter

public void setMediaTypeParameter(java.lang.String parameterName)
Sets the name of the parameter containing the accepted media type.

Parameters:
parameterName - The name of the parameter containing the accepted media type.

setMethodParameter

public void setMethodParameter(java.lang.String parameterName)
Sets the method parameter name.

Parameters:
parameterName - The method parameter name.

setMethodTunnel

public void setMethodTunnel(boolean methodTunnel)
Indicates if the method name can be tunnelled.

Parameters:
methodTunnel - True if the method name can be tunnelled.

setPreferencesTunnel

public void setPreferencesTunnel(boolean preferencesTunnel)
Indicates if the client preferences can be tunnelled via the query parameters.

Parameters:
preferencesTunnel - True if the client preferences can be tunnelled via the query parameters.

setQueryTunnel

public void setQueryTunnel(boolean queryTunnel)
Indicates if the method and client preferences can be tunnelled via query parameters.

Parameters:
queryTunnel - True if the method and client preferences can be tunnelled via query parameters.

setUserAgentTunnel

public void setUserAgentTunnel(boolean userAgentTunnel)
Indicates if the client preferences can be tunnelled according to the user agent.

Parameters:
userAgentTunnel - True if the client preferences can be tunnelled according to the user agent.


Copyright © 2005-2008 Noelios Technologies.