Package org.restlet.service

Class TunnelService

  • public class TunnelService
extends Service
    Application service tunneling request method or client preferences. The tunneling can use query parameters, file-like extensions and specific headers. 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:
    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 or the full character set name For GET requests, replaces the accepted character set by the given value.
    encodingParameter encoding Use extension names defined in MetadataService or the full encoding name For GET requests, replaces the accepted encoding by the given value.
    languageParameter language Use extension names defined in MetadataService or the full language name For GET requests, replaces the accepted language by the given value.
    mediaTypeParameter media Use extension names defined in MetadataService or the full media type name For GET requests, replaces the accepted media type set by the given value.
    methodHeader X-HTTP-Method-Override Name of non-standard header. It is a good practice to prefix it with "X-". For POST requests, let you specify the actual method to use (DELETE, PUT, MOVE, etc.).

    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. Check the isUserAgentTunnel() 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 it equals to the value of the "acceptOld" property or if the "acceptOld" property is empty, then the preferences will be updated. This can be 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

      Constructors 
      Constructor Description
      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 that enables the header tunneling.
      TunnelService​(boolean enabled, boolean methodTunnel, boolean preferencesTunnel, boolean queryTunnel, boolean extensionsTunnel, boolean userAgentTunnel, boolean headersTunnel)
      Constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean allowClient​(ClientInfo client)
      Indicates if the request from a given client can be tunneled.
      Filter createInboundFilter​(Context context)
      Create the filter that should be invoked for incoming calls.
      java.lang.String getCharacterSetParameter()
      Returns the character set parameter name.
      java.lang.String getEncodingParameter()
      Returns the name of the parameter containing the accepted encoding.
      java.lang.String getLanguageParameter()
      Returns the name of the parameter containing the accepted language.
      java.lang.String getMediaTypeParameter()
      Returns the name of the parameter containing the accepted media type.
      java.lang.String getMethodHeader()
      Returns the name of the header containing the method name.
      java.lang.String getMethodParameter()
      Returns the method parameter name.
      boolean isExtensionsTunnel()
      Indicates if the client preferences can be tunneled via the extensions.
      boolean isHeadersTunnel()
      Indicates if the method can be tunneled via the header.
      boolean isMethodTunnel()
      Indicates if the method name can be tunneled.
      boolean isPreferencesTunnel()
      Indicates if the client preferences can be tunneled via the query parameters or via file extensions.
      boolean isQueryTunnel()
      Indicates if the method and client preferences can be tunneled via query parameters or file extensions.
      boolean isUserAgentTunnel()
      Indicates if the client preferences can be tunneled according to the user agent.
      void setCharacterSetParameter​(java.lang.String parameterName)
      Sets the character set parameter name.
      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 tunneled via the extensions.
      void setHeadersTunnel​(boolean headersTunnel)
      Indicates if the method can be tunneled via the header.
      void setLanguageParameter​(java.lang.String parameterName)
      Sets the name of the parameter containing the accepted language.
      void setMediaTypeParameter​(java.lang.String parameterName)
      Sets the name of the parameter containing the accepted media type.
      void setMethodHeader​(java.lang.String methodHeader)
      Sets the name of the header containing the method name.
      void setMethodParameter​(java.lang.String parameterName)
      Sets the method parameter name.
      void setMethodTunnel​(boolean methodTunnel)
      Indicates if the method name can be tunneled.
      void setPreferencesTunnel​(boolean preferencesTunnel)
      Indicates if the client preferences can be tunneled via the query parameters.
      void setQueryTunnel​(boolean queryTunnel)
      Indicates if the method and client preferences can be tunneled via query parameters.
      void setUserAgentTunnel​(boolean userAgentTunnel)
      Indicates if the client preferences can be tunneled according to the user agent.

      • 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 tunneled.
        preferencesTunnel - Indicates if the client preferences can be tunneled 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 tunneled.
        preferencesTunnel - Indicates if the client preferences can be tunneled 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 tunneled using a query parameter.
        preferencesTunnel - Indicates if the client preferences can be tunneled 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 that enables the header tunneling.
        Parameters:
        enabled - True if the service has been enabled.
        methodTunnel - Indicates if the method can be tunneled using a query parameter.
        preferencesTunnel - Indicates if the client preferences can be tunneled 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.

      • TunnelService

        public TunnelService​(boolean enabled,
                     boolean methodTunnel,
                     boolean preferencesTunnel,
                     boolean queryTunnel,
                     boolean extensionsTunnel,
                     boolean userAgentTunnel,
                     boolean headersTunnel)
        Constructor.
        Parameters:
        enabled - True if the service has been enabled.
        methodTunnel - Indicates if the method can be tunneled using a query parameter.
        preferencesTunnel - Indicates if the client preferences can be tunneled 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.
        headersTunnel - Indicates if method can be tunneled via a specific header.

    • Method Detail

      • allowClient

        public boolean allowClient​(ClientInfo client)
        Indicates if the request from a given client can be tunneled. 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 tunneled.

      • createInboundFilter

        public Filter createInboundFilter​(Context context)
        Description copied from class: Service
        Create the filter that should be invoked for incoming calls.
        Overrides:
        createInboundFilter in class Service
        Parameters:
        context - The current context.
        Returns:
        The new filter or null.

      • getCharacterSetParameter

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

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

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

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

      • getMethodHeader

        public java.lang.String getMethodHeader()
        Returns the name of the header containing the method name.
        Returns:
        the name of the header containing the method name.

      • 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 tunneled via the extensions. Returns false by default.
        Returns:
        True if the client preferences can be tunneled via the extensions
        See Also:
        Request.getOriginalRef()

      • isHeadersTunnel

        public boolean isHeadersTunnel()
        Indicates if the method can be tunneled via the header. Returns true by default.
        Returns:
        True if the method can be tunneled via the header.

      • isMethodTunnel

        public boolean isMethodTunnel()
        Indicates if the method name can be tunneled. Returns true by default.
        Returns:
        True if the method name can be tunneled.

      • isPreferencesTunnel

        public boolean isPreferencesTunnel()
        Indicates if the client preferences can be tunneled via the query parameters or via file extensions. Returns true by default.
        Returns:
        True if the client preferences can be tunneled.

      • isQueryTunnel

        public boolean isQueryTunnel()
        Indicates if the method and client preferences can be tunneled via query parameters or file extensions. Returns true by default.
        Returns:
        True if the method and client preferences can be tunneled.

      • isUserAgentTunnel

        public boolean isUserAgentTunnel()
        Indicates if the client preferences can be tunneled according to the user agent. Returns false by default.
        Returns:
        True if the client preferences can be tunneled according to the user agent.

      • setCharacterSetParameter

        public void setCharacterSetParameter​(java.lang.String parameterName)
        Sets the character set parameter name.
        Parameters:
        parameterName - The character set parameter name.

      • 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 tunneled via the extensions.
        Parameters:
        extensionTunnel - True if the client preferences can be tunneled via the extensions.
        See Also:
        Request.getOriginalRef()

      • setHeadersTunnel

        public void setHeadersTunnel​(boolean headersTunnel)
        Indicates if the method can be tunneled via the header.
        Parameters:
        headersTunnel - True if the method can be tunneled via the header.

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

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

      • setMethodHeader

        public void setMethodHeader​(java.lang.String methodHeader)
        Sets the name of the header containing the method name.
        Parameters:
        methodHeader - The name of the header containing the method name.

      • 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 tunneled.
        Parameters:
        methodTunnel - True if the method name can be tunneled.

      • setPreferencesTunnel

        public void setPreferencesTunnel​(boolean preferencesTunnel)
        Indicates if the client preferences can be tunneled via the query parameters.
        Parameters:
        preferencesTunnel - True if the client preferences can be tunneled via the query parameters.

      • setQueryTunnel

        public void setQueryTunnel​(boolean queryTunnel)
        Indicates if the method and client preferences can be tunneled via query parameters.
        Parameters:
        queryTunnel - True if the method and client preferences can be tunneled via query parameters.

      • setUserAgentTunnel

        public void setUserAgentTunnel​(boolean userAgentTunnel)
        Indicates if the client preferences can be tunneled according to the user agent.
        Parameters:
        userAgentTunnel - True if the client preferences can be tunneled according to the user agent.