Package ratpack.core.handling

Interface ByContentSpec

  • All Known Subinterfaces:
    GroovyByContentSpec
    All Known Implementing Classes:
    DefaultGroovyByContentSpec
    public interface ByContentSpec
    A specification of how to respond to a request, based on the requested content type (i.e. the request's Accept header). This is useful when a given handler can provide content of more than one type (i.e. content negotiation).

    The handler to use will be selected based on parsing the "Accept" header, respecting quality weighting and wildcard matching. The order that types are specified is significant for wildcard matching. The earliest registered type that matches the wildcard will be used. 

    
 import ratpack.test.embed.EmbeddedApp;
 import ratpack.core.http.client.ReceivedResponse;

 import static org.junit.jupiter.api.Assertions.*;

 public class Example {
   public static void main(String[] args) throws Exception {
     EmbeddedApp.fromHandler(ctx -> {
       String message = "hello!";
       ctx.byContent(m -> m
         .json(() -> ctx.render("{\"msg\": \"" + message + "\"}"))
         .html(() -> ctx.render("<p>" + message + "</p>"))
       );
     }).test(httpClient -> {
       ReceivedResponse response = httpClient.requestSpec(s -> s.getHeaders().add("Accept", "application/json")).get();
       assertEquals("{\"msg\": \"hello!\"}", response.getBody().getText());
       assertEquals("application/json", response.getBody().getContentType().getType());

       response = httpClient.requestSpec(s -> s.getHeaders().add("Accept", "text/plain; q=1.0, text/html; q=0.8, application/json; q=0.7")).get();
       assertEquals("<p>hello!</p>", response.getBody().getText());
       assertEquals("text/html", response.getBody().getContentType().getType());
     });
   }
 }

    If there is no type registered, or if the client does not accept any of the given types, the "noMatch" handler will be used. By default, the "noMatch" handler will issue a 406 error via Context.clientError(int). If you want a different behavior, use noMatch(ratpack.func.Block).

    If the request lacks a usable Accept header (header not present or has an empty value), the "unspecified" handler will be used. By default, the "unspecified" handler will use the handler for the first registered content type. If you want a different behavior, use unspecified(ratpack.func.Block).

    Only the last specified handler for a type will be used. That is, adding a subsequent handler for the same type will replace the previous.

    See Also:
    Context.byContent(ratpack.func.Action), RFC 7231: Accept, RFC 7231: 406 Not Acceptable

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      ByContentSpec html​(Class<? extends Handler> handlerType)
      Specifies that the given handler should be used if the client wants content of type "text/html".
      ByContentSpec html​(Handler handler)
      Specifies that the given handler should be used if the client wants content of type "text/html".
      default ByContentSpec html​(Block block)
      Specifies that the given handler should be used if the client wants content of type "text/html".
      ByContentSpec json​(Class<? extends Handler> handlerType)
      Specifies that the given handler should be used if the client wants content of type "application/json".
      ByContentSpec json​(Handler handler)
      Specifies that the given handler should be used if the client wants content of type "application/json".
      default ByContentSpec json​(Block block)
      Specifies that the given handler should be used if the client wants content of type "application/json".
      ByContentSpec noMatch​(Class<? extends Handler> handlerType)
      Specifies that the given handler should be used if the client's requested content type cannot be matched with any of the other handlers.
      ByContentSpec noMatch​(String mimeType)
      Specifies that the handler for the specified content type should be used if the client's requested content type cannot be matched with any of the other handlers.
      ByContentSpec noMatch​(Handler handler)
      Specifies that the given handler should be used if the client's requested content type cannot be matched with any of the other handlers.
      default ByContentSpec noMatch​(Block block)
      Specifies that the given handler should be used if the client's requested content type cannot be matched with any of the other handlers.
      ByContentSpec plainText​(Class<? extends Handler> handlerType)
      Specifies that the given handler should be used if the client wants content of type "text/plain".
      ByContentSpec plainText​(Handler handler)
      Specifies that the given handler should be used if the client wants content of type "text/plain".
      default ByContentSpec plainText​(Block block)
      Specifies that the given handler should be used if the client wants content of type "text/plain".
      ByContentSpec type​(CharSequence mimeType, Class<? extends Handler> handlerType)
      Specifies that the given handler should be used if the client wants content of the given MIME type.
      ByContentSpec type​(CharSequence mimeType, Handler handler)
      Specifies that the given handler should be used if the client wants content of the given MIME type.
      default ByContentSpec type​(CharSequence mimeType, Block block)
      Specifies that the given handler should be used if the client wants content of the given MIME type.
      ByContentSpec type​(String mimeType, Class<? extends Handler> handlerType)
      Specifies that the given handler should be used if the client wants content of the given MIME type.
      ByContentSpec type​(String mimeType, Handler handler)
      Specifies that the given handler should be used if the client wants content of the given MIME type.
      default ByContentSpec type​(String mimeType, Block block)
      Specifies that the given handler should be used if the client wants content of the given MIME type.
      ByContentSpec unspecified​(Class<? extends Handler> handlerType)
      Specifies that the given handler should be used if the client did not provide a usable "Accept" header in the request.
      ByContentSpec unspecified​(String mimeType)
      Specifies that the handler for the specified content type should be used if the client did not provide a usable "Accept" header in the request.
      ByContentSpec unspecified​(Handler handler)
      Specifies that the given handler should be used if the client did not provide a usable "Accept" header in the request.
      default ByContentSpec unspecified​(Block block)
      Specifies that the given handler should be used if the client did not provide a usable "Accept" header in the request.
      ByContentSpec xml​(Class<? extends Handler> handlerType)
      Specifies that the given handler should be used if the client wants content of type "application/xml".
      ByContentSpec xml​(Handler handler)
      Specifies that the given handler should be used if the client wants content of type "application/xml".
      default ByContentSpec xml​(Block block)
      Specifies that the given handler should be used if the client wants content of type "application/xml".

    • Method Detail

      • type

        default ByContentSpec type​(String mimeType,
                           Block block)
        Specifies that the given handler should be used if the client wants content of the given MIME type. This only supports fully-specified content types (no "*" wildcards).
        Parameters:
        mimeType - the MIME type to register for
        block - the code to invoke if the content type matches
        Returns:
        this

      • type

        default ByContentSpec type​(CharSequence mimeType,
                           Block block)
        Specifies that the given handler should be used if the client wants content of the given MIME type. This only supports fully-specified content types (no "*" wildcards).
        Parameters:
        mimeType - the MIME type to register for
        block - the code to invoke if the content type matches
        Returns:
        this
        Since:
        1.6

      • type

        ByContentSpec type​(String mimeType,
                   Handler handler)
        Specifies that the given handler should be used if the client wants content of the given MIME type. This only supports fully-specified content types (no "*" wildcards).
        Parameters:
        mimeType - the MIME type to register for
        handler - the handler to invoke if the content type matches
        Returns:
        this
        Since:
        1.5

      • type

        ByContentSpec type​(CharSequence mimeType,
                   Handler handler)
        Specifies that the given handler should be used if the client wants content of the given MIME type. This only supports fully-specified content types (no "*" wildcards).
        Parameters:
        mimeType - the MIME type to register for
        handler - the handler to invoke if the content type matches
        Returns:
        this
        Since:
        1.6

      • type

        ByContentSpec type​(String mimeType,
                   Class<? extends Handler> handlerType)
        Specifies that the given handler should be used if the client wants content of the given MIME type. This only supports fully-specified content types (no "*" wildcards).
        Parameters:
        mimeType - the MIME type to register for
        handlerType - the type of handler to retrieve from the registry and use
        Returns:
        this
        Since:
        1.5

      • type

        ByContentSpec type​(CharSequence mimeType,
                   Class<? extends Handler> handlerType)
        Specifies that the given handler should be used if the client wants content of the given MIME type. This only supports fully-specified content types (no "*" wildcards).
        Parameters:
        mimeType - the MIME type to register for
        handlerType - the type of handler to retrieve from the registry and use
        Returns:
        this
        Since:
        1.6

      • plainText

        default ByContentSpec plainText​(Block block)
        Specifies that the given handler should be used if the client wants content of type "text/plain".
        Parameters:
        block - the code to invoke if the content type matches
        Returns:
        this

      • plainText

        ByContentSpec plainText​(Handler handler)
        Specifies that the given handler should be used if the client wants content of type "text/plain".
        Parameters:
        handler - the handler to invoke if the content type matches
        Returns:
        this
        Since:
        1.5

      • plainText

        ByContentSpec plainText​(Class<? extends Handler> handlerType)
        Specifies that the given handler should be used if the client wants content of type "text/plain".
        Parameters:
        handlerType - the type of handler to retrieve from the registry and use
        Returns:
        this
        Since:
        1.5

      • html

        default ByContentSpec html​(Block block)
        Specifies that the given handler should be used if the client wants content of type "text/html".
        Parameters:
        block - the code to invoke if the content type matches
        Returns:
        this

      • html

        ByContentSpec html​(Handler handler)
        Specifies that the given handler should be used if the client wants content of type "text/html".
        Parameters:
        handler - the handler to invoke if the content type matches
        Returns:
        this
        Since:
        1.5

      • html

        ByContentSpec html​(Class<? extends Handler> handlerType)
        Specifies that the given handler should be used if the client wants content of type "text/html".
        Parameters:
        handlerType - the type of handler to retrieve from the registry and use
        Returns:
        this
        Since:
        1.5

      • json

        default ByContentSpec json​(Block block)
        Specifies that the given handler should be used if the client wants content of type "application/json".
        Parameters:
        block - the code to invoke if the content type matches
        Returns:
        this

      • json

        ByContentSpec json​(Handler handler)
        Specifies that the given handler should be used if the client wants content of type "application/json".
        Parameters:
        handler - the handler to invoke if the content type matches
        Returns:
        this
        Since:
        1.5

      • json

        ByContentSpec json​(Class<? extends Handler> handlerType)
        Specifies that the given handler should be used if the client wants content of type "application/json".
        Parameters:
        handlerType - the type of handler to retrieve from the registry and use
        Returns:
        this
        Since:
        1.5

      • xml

        default ByContentSpec xml​(Block block)
        Specifies that the given handler should be used if the client wants content of type "application/xml".
        Parameters:
        block - the code to invoke if the content type matches
        Returns:
        this

      • xml

        ByContentSpec xml​(Handler handler)
        Specifies that the given handler should be used if the client wants content of type "application/xml".
        Parameters:
        handler - the handler to invoke if the content type matches
        Returns:
        this
        Since:
        1.5

      • xml

        ByContentSpec xml​(Class<? extends Handler> handlerType)
        Specifies that the given handler should be used if the client wants content of type "application/xml".
        Parameters:
        handlerType - the type of handler to retrieve from the registry and use
        Returns:
        this
        Since:
        1.5

      • noMatch

        default ByContentSpec noMatch​(Block block)
        Specifies that the given handler should be used if the client's requested content type cannot be matched with any of the other handlers.
        Parameters:
        block - the code to invoke if the content type doesn't match
        Returns:
        this

      • noMatch

        ByContentSpec noMatch​(Handler handler)
        Specifies that the given handler should be used if the client's requested content type cannot be matched with any of the other handlers.
        Parameters:
        handler - the handler to invoke if the content type matches
        Returns:
        this
        Since:
        1.5

      • noMatch

        ByContentSpec noMatch​(Class<? extends Handler> handlerType)
        Specifies that the given handler should be used if the client's requested content type cannot be matched with any of the other handlers.
        Parameters:
        handlerType - the type of handler to retrieve from the registry and use
        Returns:
        this
        Since:
        1.5

      • noMatch

        ByContentSpec noMatch​(String mimeType)
        Specifies that the handler for the specified content type should be used if the client's requested content type cannot be matched with any of the other handlers. Effectively, this treats the request as if the user requested the specified MIME type. If the specified mimeType doesn't have a registered block, it will result in a server error for applicable requests.
        Parameters:
        mimeType - the MIME type to use as a fallback if the requested type can't be matched
        Returns:
        this

      • unspecified

        default ByContentSpec unspecified​(Block block)
        Specifies that the given handler should be used if the client did not provide a usable "Accept" header in the request.
        Parameters:
        block - the code to invoke if no usable "Accept" header is present in the request.
        Returns:
        this
        Since:
        1.5

      • unspecified

        ByContentSpec unspecified​(Handler handler)
        Specifies that the given handler should be used if the client did not provide a usable "Accept" header in the request.
        Parameters:
        handler - the handler to invoke if if no usable "Accept" header is present in the request.
        Returns:
        this
        Since:
        1.5

      • unspecified

        ByContentSpec unspecified​(Class<? extends Handler> handlerType)
        Specifies that the given handler should be used if the client did not provide a usable "Accept" header in the request.
        Parameters:
        handlerType - the type of handler to retrieve from the registry and use if no usable "Accept" header is present in the request.
        Returns:
        this
        Since:
        1.5

      • unspecified

        ByContentSpec unspecified​(String mimeType)
        Specifies that the handler for the specified content type should be used if the client did not provide a usable "Accept" header in the request. Effectively, this treats the request as if the user requested the specified MIME type. If the specified mimeType doesn't have a registered block, it will result in a server error for applicable requests.
        Parameters:
        mimeType - the MIME type to use as a fallback if no type is requested
        Returns:
        this
        Since:
        1.5