Package org.jboss.resteasy.reactive

Class RestResponse.ResponseBuilder<T>

  • Direct Known Subclasses:
    AbstractRestResponseBuilder
    Enclosing class:
    RestResponse<T>
    public abstract static class RestResponse.ResponseBuilder<T>
extends Object
    A class used to build RestResponse instances that contain metadata instead of or in addition to an entity. An initial instance may be obtained via static methods of the RestResponse.ResponseBuilder class, instance methods provide the ability to set metadata. E.g. to create a response that indicates the creation of a new resource: 
     @POST
 RestResponse<Void> addWidget(...) {
   Widget w = ...
   URI widgetId = UriBuilder.fromResource(Widget.class)...
   return RestResponse.ResponseBuilder.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 RestResponse.

    • Constructor Detail

      • ResponseBuilder

        protected ResponseBuilder()
        Protected constructor, use one of the static methods of RestResponse to obtain an instance.

    • Method Detail

      • newInstance

        protected static <T> RestResponse.ResponseBuilder<T> newInstance()
        Create a new builder instance.
        Returns:
        a new response builder.

      • build

        public abstract RestResponse<T> build()
        Create a RestResponse instance from the current ResponseBuilder. The builder is reset to a blank state equivalent to calling the ok method.
        Returns:
        a RestResponse instance.

      • status

        public abstract <Ret extends T> RestResponse.ResponseBuilder<Ret> 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 abstract <Ret extends T> RestResponse.ResponseBuilder<Ret> status​(int status,
                                                                         String reasonPhrase)
        Set the status on the ResponseBuilder.
        Parameters:
        status - the response status.
        reasonPhrase - the reason phrase.
        Returns:
        the updated response builder.
        Throws:
        IllegalArgumentException - if status is less than 100 or greater than 599.

      • status

        public <Ret extends T> RestResponse.ResponseBuilder<Ret> status​(javax.ws.rs.core.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.

      • entity

        public abstract RestResponse.ResponseBuilder<T> entity​(T 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, (in addition to any annotations declared directly on a resource method that returns the built response).
        Returns:
        updated response builder instance.
        See Also:
        entity(java.lang.Object), type(javax.ws.rs.core.MediaType), type(java.lang.String)

      • allow

        public abstract RestResponse.ResponseBuilder<T> 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.

      • allow

        public abstract RestResponse.ResponseBuilder<T> 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.

      • cacheControl

        public abstract RestResponse.ResponseBuilder<T> cacheControl​(javax.ws.rs.core.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 RestResponse.ResponseBuilder<T> 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.

      • header

        public abstract RestResponse.ResponseBuilder<T> 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 RestResponse.ResponseBuilder<T> replaceAll​(javax.ws.rs.core.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.

      • language

        public abstract RestResponse.ResponseBuilder<T> 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 RestResponse.ResponseBuilder<T> 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 RestResponse.ResponseBuilder<T> type​(javax.ws.rs.core.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 RestResponse.ResponseBuilder<T> 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.

      • contentLocation

        public abstract RestResponse.ResponseBuilder<T> 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 RestResponse.ResponseBuilder<T> cookie​(javax.ws.rs.core.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 RestResponse.ResponseBuilder<T> 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 RestResponse.ResponseBuilder<T> 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 RestResponse.ResponseBuilder<T> 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 RestResponse.ResponseBuilder<T> tag​(javax.ws.rs.core.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 RestResponse.ResponseBuilder<T> 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 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 RestResponse.ResponseBuilder<T> variants​(javax.ws.rs.core.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.

      • variants

        public abstract RestResponse.ResponseBuilder<T> variants​(List<javax.ws.rs.core.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 RestResponse.ResponseBuilder<T> links​(javax.ws.rs.core.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.

      • link

        public abstract RestResponse.ResponseBuilder<T> 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.

      • link

        public abstract RestResponse.ResponseBuilder<T> 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.

      • fromResponse

        public static <T> RestResponse.ResponseBuilder<T> fromResponse​(RestResponse<T> response)
        Create a new ResponseBuilder by performing a shallow copy of an existing Response.

        The returned builder has its own response headers but the header values are shared with the original RestResponse instance. The original response entity instance reference is set in the new response builder.

        Note that if the entity is backed by an un-consumed input stream, the reference to the stream is copied. In such case make sure to buffer the entity stream of the original response instance before passing it to this method.

        Parameters:
        response - a Response from which the status code, entity and response headers will be copied.
        Returns:
        a new response builder.

      • create

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> create​(javax.ws.rs.core.Response.StatusType status)
        Create a new ResponseBuilder with the supplied status.
        Parameters:
        status - the response status.
        Returns:
        a new response builder.
        Throws:
        IllegalArgumentException - if status is null.

      • create

        public static <T> RestResponse.ResponseBuilder<T> create​(javax.ws.rs.core.Response.StatusType status,
                                                         T entity)
        Create a new ResponseBuilder with the supplied status.
        Parameters:
        status - the response status.
        Returns:
        a new response builder.
        Throws:
        IllegalArgumentException - if status is null.

      • create

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> create​(int status)
        Create a new ResponseBuilder with the supplied status.
        Parameters:
        status - the response status.
        Returns:
        a new response builder.
        Throws:
        IllegalArgumentException - if status is less than 100 or greater than 599.

      • create

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> create​(int status,
                                                                     String reasonPhrase)
        Create a new ResponseBuilder with the supplied status and reason phrase.
        Parameters:
        status - the response status.
        reasonPhrase - the reason phrase.
        Returns:
        the updated response builder.
        Throws:
        IllegalArgumentException - if status is less than 100 or greater than 599.

      • ok

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> ok()
        Create a new ResponseBuilder with an OK status.
        Returns:
        a new response builder.

      • ok

        public static <T> RestResponse.ResponseBuilder<T> ok​(T entity)
        Create a new ResponseBuilder that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.
        Parameters:
        entity - the representation entity data.
        Returns:
        a new response builder.

      • ok

        public static <T> RestResponse.ResponseBuilder<T> ok​(T entity,
                                                     javax.ws.rs.core.MediaType type)
        Create a new ResponseBuilder that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.
        Parameters:
        entity - the representation entity data.
        type - the media type of the entity.
        Returns:
        a new response builder.

      • ok

        public static <T> RestResponse.ResponseBuilder<T> ok​(T entity,
                                                     String type)
        Create a new ResponseBuilder that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.
        Parameters:
        entity - the representation entity data.
        type - the media type of the entity.
        Returns:
        a new response builder.

      • ok

        public static <T> RestResponse.ResponseBuilder<T> ok​(T entity,
                                                     javax.ws.rs.core.Variant variant)
        Create a new ResponseBuilder that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.
        Parameters:
        entity - the representation entity data.
        variant - representation metadata.
        Returns:
        a new response builder.

      • serverError

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> serverError()
        Create a new ResponseBuilder with an server error status.
        Returns:
        a new response builder.

      • created

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> created​(URI location)
        Create a new ResponseBuilder for a created resource, set the location header using the supplied value.
        Parameters:
        location - the URI of the new resource. If a relative URI is supplied it will be converted into an absolute URI by resolving it relative to the request URI (see UriInfo.getRequestUri()).
        Returns:
        a new response builder.
        Throws:
        IllegalArgumentException - if location is null.

      • accepted

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> accepted()
        Create a new ResponseBuilder with an ACCEPTED status.
        Returns:
        a new response builder.

      • accepted

        public static <T> RestResponse.ResponseBuilder<T> accepted​(T entity)
        Create a new ResponseBuilder with an ACCEPTED status that contains a representation. It is the callers responsibility to wrap the actual entity with GenericEntity if preservation of its generic type is required.
        Parameters:
        entity - the representation entity data.
        Returns:
        a new response builder.

      • noContent

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> noContent()
        Create a new ResponseBuilder for an empty response.
        Returns:
        a new response builder.

      • notModified

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> notModified()
        Create a new ResponseBuilder with a not-modified status.
        Returns:
        a new response builder.

      • notModified

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> notModified​(javax.ws.rs.core.EntityTag tag)
        Create a new ResponseBuilder with a not-modified status.
        Parameters:
        tag - a tag for the unmodified entity.
        Returns:
        a new response builder.
        Throws:
        IllegalArgumentException - if tag is null.

      • notModified

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> notModified​(String tag)
        Create a new ResponseBuilder with a not-modified status and a strong entity tag. This is a shortcut for notModified(new EntityTag(value)).
        Parameters:
        tag - the string content of a strong entity tag. The runtime will quote the supplied value when creating the header.
        Returns:
        a new response builder.
        Throws:
        IllegalArgumentException - if tag is null.

      • seeOther

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> seeOther​(URI location)
        Create a new ResponseBuilder for a redirection. Used in the redirect-after-POST (aka POST/redirect/GET) pattern.
        Parameters:
        location - the redirection URI. 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()).
        Returns:
        a new response builder.
        Throws:
        IllegalArgumentException - if location is null.

      • temporaryRedirect

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> temporaryRedirect​(URI location)
        Create a new ResponseBuilder for a temporary redirection.
        Parameters:
        location - the redirection URI. 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()).
        Returns:
        a new response builder.
        Throws:
        IllegalArgumentException - if location is null.

      • notAcceptable

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> notAcceptable​(List<javax.ws.rs.core.Variant> variants)
        Create a new ResponseBuilder for a not acceptable response.
        Parameters:
        variants - list of variants that were available, a null value is equivalent to an empty list.
        Returns:
        a new response builder.

      • notFound

        public static <IGNORED> RestResponse.ResponseBuilder<IGNORED> notFound()
        Create a new ResponseBuilder for a not found response.
        Returns:
        a new response builder.