javax.ws.rs.core

## Class Response.ResponseBuilder

- java.lang.Object
- - javax.ws.rs.core.Response.ResponseBuilder

- Direct Known Subclasses:
    ResponseBuilderImpl
  Enclosing class:
    Response

      public abstract static class Response.ResponseBuilder
      extends Object

  A class used to build Response instances that contain metadata instead of or in addition to an entity. An initial instance may be obtained via static methods of the Response class, instance methods provide the ability to set metadata. E.g. to create a response that indicates the creation of a new resource:

      @POST
       Response addWidget(...) {
         Widget w = ...
         URI widgetId = UriBuilder.fromResource(Widget.class)...
         return Response.created(widgetId).build();
       }

  Several methods have parameters of type URI, `UriBuilder` provides convenient methods to create such values as does `URI.create()`.

  Where multiple variants of the same method are provided, the type of the supplied parameter is retained in the metadata of the built `Response`.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Response.ResponseBuilder()` Protected constructor, use one of the static methods of `Response` to obtain an instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Response.ResponseBuilder` | `allow(Set<String> methods)` Set the list of allowed methods for the resource.
    `abstract Response.ResponseBuilder` | `allow(String... methods)` Set the list of allowed methods for the resource.
    `abstract Response` | `build()` Create a Response instance from the current ResponseBuilder.
    `abstract Response.ResponseBuilder` | `cacheControl(CacheControl cacheControl)` Set the cache control data of the message.
    `abstract Response.ResponseBuilder` | `clone()`
    `abstract Response.ResponseBuilder` | `contentLocation(URI location)` Set the content location.
    `abstract Response.ResponseBuilder` | `cookie(NewCookie... cookies)` Add cookies to the response message.
    `abstract Response.ResponseBuilder` | `encoding(String encoding)` Set the message entity content encoding.
    `abstract Response.ResponseBuilder` | `entity(Object entity)` Set the response entity in the builder.
    `abstract Response.ResponseBuilder` | `entity(Object entity, Annotation[] annotations)` Set the response entity in the builder.
    `abstract Response.ResponseBuilder` | `expires(Date expires)` Set the response expiration date.
    `abstract Response.ResponseBuilder` | `header(String name, Object value)` Add an arbitrary header.
    `abstract Response.ResponseBuilder` | `language(Locale language)` Set the message entity language.
    `abstract Response.ResponseBuilder` | `language(String language)` Set the message entity language.
    `abstract Response.ResponseBuilder` | `lastModified(Date lastModified)` Set the response entity last modification date.
    `abstract Response.ResponseBuilder` | `link(String uri, String rel)` Add a link header.
    `abstract Response.ResponseBuilder` | `link(URI uri, String rel)` Add a link header.
    `abstract Response.ResponseBuilder` | `links(Link... links)` Add one or more link headers.
    `abstract Response.ResponseBuilder` | `location(URI location)` Set the location.
    `protected static Response.ResponseBuilder` | `newInstance()` Create a new builder instance.
    `abstract Response.ResponseBuilder` | `replaceAll(MultivaluedMap<String,Object> headers)` Replaces all existing headers with the newly supplied headers.
    `abstract Response.ResponseBuilder` | `status(int status)` Set the status on the ResponseBuilder.
    `Response.ResponseBuilder` | `status(Response.Status status)` Set the status on the ResponseBuilder.
    `Response.ResponseBuilder` | `status(Response.StatusType status)` Set the status on the ResponseBuilder.
    `abstract Response.ResponseBuilder` | `tag(EntityTag tag)` Set a response entity tag.
    `abstract Response.ResponseBuilder` | `tag(String tag)` Set a strong response entity tag.
    `abstract Response.ResponseBuilder` | `type(MediaType type)` Set the message entity media type.
    `abstract Response.ResponseBuilder` | `type(String type)` Set the message entity media type.
    `abstract Response.ResponseBuilder` | `variant(Variant variant)` Set message entity representation metadata.
    `abstract Response.ResponseBuilder` | `variants(List<Variant> variants)` Add a Vary header that lists the available variants.
    `abstract Response.ResponseBuilder` | `variants(Variant... variants)` Add a Vary header that lists the available variants.

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Response.ResponseBuilder

          protected Response.ResponseBuilder()

      Protected constructor, use one of the static methods of `Response` to obtain an instance.

  - ### Method Detail

    - #### newInstance

          protected static Response.ResponseBuilder newInstance()

      Create a new builder instance.
      Returns:
        a new response builder.

    - #### build

          public abstract Response build()

      Create a Response instance from the current ResponseBuilder. The builder is reset to a blank state equivalent to calling the ok method.
      Returns:
        a Response instance.

    - #### clone

          public abstract Response.ResponseBuilder clone()

      Create a copy of the ResponseBuilder preserving its state.

      Overrides:
        `clone` in class `Object`
      Returns:
        a copy of the ResponseBuilder.

    - #### status

          public abstract Response.ResponseBuilder status(int status)

      Set the status on the ResponseBuilder.
      Parameters:
        `status` - the response status.
      Returns:
        the updated response builder.
      Throws:
        `IllegalArgumentException` - if status is less than `100` or greater than `599`.

    - #### status

          public Response.ResponseBuilder status(Response.StatusType status)

      Set the status on the ResponseBuilder.
      Parameters:
        `status` - the response status.
      Returns:
        the updated response builder.
      Throws:
        `IllegalArgumentException` - if status is `null`.
      Since:
        1.1

    - #### status

          public Response.ResponseBuilder status(Response.Status status)

      Set the status on the ResponseBuilder.
      Parameters:
        `status` - the response status.
      Returns:
        the updated response builder.
      Throws:
        `IllegalArgumentException` - if status is `null`.

    - #### entity

          public abstract Response.ResponseBuilder entity(Object entity)

      Set the response entity in the builder.

      Any Java type instance for a response entity, that is supported by the runtime can be passed. It is the callers responsibility to wrap the actual entity with `GenericEntity` if preservation of its generic type is required. Note that the entity can be also set as an `input stream`.

      A specific entity media type can be set using one of the `type(...)` methods.
      Parameters:
        `entity` - the request entity.
      Returns:
        updated response builder instance.
      See Also:
        `entity(java.lang.Object, java.lang.annotation.Annotation[])`, `type(javax.ws.rs.core.MediaType)`, `type(java.lang.String)`

    - #### entity

          public abstract Response.ResponseBuilder entity(Object entity,
                                        Annotation[] annotations)

      Set the response entity in the builder.

      Any Java type instance for a response entity, that is supported by the runtime can be passed. It is the callers responsibility to wrap the actual entity with `GenericEntity` if preservation of its generic type is required. Note that the entity can be also set as an `input stream`.

      A specific entity media type can be set using one of the `type(...)` methods.
      Parameters:
        `entity` - the request entity.
        `annotations` - annotations that will be passed to the `MessageBodyWriter`.
      Returns:
        updated response builder instance.
      Since:
        2.0
      See Also:
        `entity(java.lang.Object)`, `type(javax.ws.rs.core.MediaType)`, `type(java.lang.String)`

    - #### allow

          public abstract Response.ResponseBuilder allow(String... methods)

      Set the list of allowed methods for the resource. Any duplicate method names will be truncated to a single entry.
      Parameters:
        `methods` - the methods to be listed as allowed for the resource, if `null` any existing allowed method list will be removed.
      Returns:
        the updated response builder.
      Since:
        2.0

    - #### allow

          public abstract Response.ResponseBuilder allow(Set<String> methods)

      Set the list of allowed methods for the resource.
      Parameters:
        `methods` - the methods to be listed as allowed for the resource, if `null` any existing allowed method list will be removed.
      Returns:
        the updated response builder.
      Since:
        2.0

    - #### cacheControl

          public abstract Response.ResponseBuilder cacheControl(CacheControl cacheControl)

      Set the cache control data of the message.
      Parameters:
        `cacheControl` - the cache control directives, if `null` any existing cache control directives will be removed.
      Returns:
        the updated response builder.

    - #### encoding

          public abstract Response.ResponseBuilder encoding(String encoding)

      Set the message entity content encoding.
      Parameters:
        `encoding` - the content encoding of the message entity, if `null` any existing value for content encoding will be removed.
      Returns:
        the updated response builder.
      Since:
        2.0

    - #### header

          public abstract Response.ResponseBuilder header(String name,
                                        Object value)

      Add an arbitrary header.
      Parameters:
        `name` - the name of the header
        `value` - the value of the header, the header will be serialized using a `RuntimeDelegate.HeaderDelegate` if one is available via `RuntimeDelegate.createHeaderDelegate(java.lang.Class)` for the class of `value` or using its `toString` method if a header delegate is not available. If `value` is `null` then all current headers of the same name will be removed.
      Returns:
        the updated response builder.

    - #### replaceAll

          public abstract Response.ResponseBuilder replaceAll(MultivaluedMap<String,Object> headers)

      Replaces all existing headers with the newly supplied headers.
      Parameters:
        `headers` - new headers to be set, if `null` all existing headers will be removed.
      Returns:
        the updated response builder.
      Since:
        2.0

    - #### language

          public abstract Response.ResponseBuilder language(String language)

      Set the message entity language.
      Parameters:
        `language` - the language of the message entity, if `null` any existing value for language will be removed.
      Returns:
        the updated response builder.

    - #### language

          public abstract Response.ResponseBuilder language(Locale language)

      Set the message entity language.
      Parameters:
        `language` - the language of the message entity, if `null` any existing value for type will be removed.
      Returns:
        the updated response builder.

    - #### type

          public abstract Response.ResponseBuilder type(MediaType type)

      Set the message entity media type.
      Parameters:
        `type` - the media type of the message entity. If `null`, any existing value for type will be removed.
      Returns:
        the updated response builder.

    - #### type

          public abstract Response.ResponseBuilder type(String type)

      Set the message entity media type.
      Parameters:
        `type` - the media type of the message entity. If `null`, any existing value for type will be removed.
      Returns:
        the updated response builder.

    - #### variant

          public abstract Response.ResponseBuilder variant(Variant variant)

      Set message entity representation metadata.

      Equivalent to setting the values of content type, content language, and content encoding separately using the values of the variant properties.
      Parameters:
        `variant` - metadata of the message entity, a `null` value is equivalent to a variant with all `null` properties.
      Returns:
        the updated response builder.
      Since:
        2.0
      See Also:
        `encoding(java.lang.String)`, `language(java.util.Locale)`, `type(javax.ws.rs.core.MediaType)`

    - #### contentLocation

          public abstract Response.ResponseBuilder contentLocation(URI location)

      Set the content location.
      Parameters:
        `location` - the content location. Relative or absolute URIs may be used for the value of content location. If `null` any existing value for content location will be removed.
      Returns:
        the updated response builder.

    - #### cookie

          public abstract Response.ResponseBuilder cookie(NewCookie... cookies)

      Add cookies to the response message.
      Parameters:
        `cookies` - new cookies that will accompany the response. A `null` value will remove all cookies, including those added via the `header(java.lang.String, java.lang.Object)` method.
      Returns:
        the updated response builder.

    - #### expires

          public abstract Response.ResponseBuilder expires(Date expires)

      Set the response expiration date.
      Parameters:
        `expires` - the expiration date, if `null` removes any existing expires value.
      Returns:
        the updated response builder.

    - #### lastModified

          public abstract Response.ResponseBuilder lastModified(Date lastModified)

      Set the response entity last modification date.
      Parameters:
        `lastModified` - the last modified date, if `null` any existing last modified value will be removed.
      Returns:
        the updated response builder.

    - #### location

          public abstract Response.ResponseBuilder location(URI location)

      Set the location.
      Parameters:
        `location` - the location. If a relative URI is supplied it will be converted into an absolute URI by resolving it relative to the base URI of the application (see `UriInfo.getBaseUri()`). If `null` any existing value for location will be removed.
      Returns:
        the updated response builder.

    - #### tag

          public abstract Response.ResponseBuilder tag(EntityTag tag)

      Set a response entity tag.
      Parameters:
        `tag` - the entity tag, if `null` any existing entity tag value will be removed.
      Returns:
        the updated response builder.

    - #### tag

          public abstract Response.ResponseBuilder tag(String tag)

      Set a strong response entity tag.

      This is a shortcut for `tag(new EntityTag(value))`.
      Parameters:
        `tag` - the string content of a strong entity tag. The JAX-RS runtime will quote the supplied value when creating the header. If `null` any existing entity tag value will be removed.
      Returns:
        the updated response builder.

    - #### variants

          public abstract Response.ResponseBuilder variants(Variant... variants)

      Add a Vary header that lists the available variants.
      Parameters:
        `variants` - a list of available representation variants, a `null` value will remove an existing value for Vary header.
      Returns:
        the updated response builder.
      Since:
        2.0

    - #### variants

          public abstract Response.ResponseBuilder variants(List<Variant> variants)

      Add a Vary header that lists the available variants.
      Parameters:
        `variants` - a list of available representation variants, a `null` value will remove an existing value for Vary header.
      Returns:
        the updated response builder.

    - #### links

          public abstract Response.ResponseBuilder links(Link... links)

      Add one or more link headers.
      Parameters:
        `links` - links to be added to the message as headers, a `null` value will remove any existing Link headers.
      Returns:
        the updated response builder.
      Since:
        2.0

    - #### link

          public abstract Response.ResponseBuilder link(URI uri,
                                      String rel)

      Add a link header.
      Parameters:
        `uri` - underlying URI for link header.
        `rel` - value of "rel" parameter.
      Returns:
        the updated response builder.
      Since:
        2.0

    - #### link

          public abstract Response.ResponseBuilder link(String uri,
                                      String rel)

      Add a link header.
      Parameters:
        `uri` - underlying URI for link header.
        `rel` - value of "rel" parameter.
      Returns:
        the updated response builder.
      Since:
        2.0

Copyright © 2014. All Rights Reserved.