Package com.helger.servlet.response

Class UnifiedResponse

  • @NotThreadSafe
public class UnifiedResponse
extends Object
    This class encapsulates all things required to build a HTTP response. It offer warnings and consistency checks if something is missing.
    Author:
    Philip Helger

    • Field Detail

      • DEFAULT_ALLOW_CONTENT_ON_REDIRECT

        public static final boolean DEFAULT_ALLOW_CONTENT_ON_REDIRECT
        By default content is not allowed on redirect
        See Also:
        Constant Field Values

      • DEFAULT_ALLOW_CONTENT_ON_STATUS_CODE

        public static final boolean DEFAULT_ALLOW_CONTENT_ON_STATUS_CODE
        By default content is not allowed for status codes
        See Also:
        Constant Field Values

      • DEFAULT_CONTENT_DISPOSITION_TYPE

        public static final EContentDispositionType DEFAULT_CONTENT_DISPOSITION_TYPE
        Default content disposition type is Attachment

      • DEFAULT_WARN_ON_DUPLICATE_COOKIES

        public static final boolean DEFAULT_WARN_ON_DUPLICATE_COOKIES
        By default a warning is emitted on duplicate cookies
        Since:
        6.0.5
        See Also:
        Constant Field Values

      • MAX_CSS_KB_FOR_IE

        public static final int MAX_CSS_KB_FOR_IE
        Maximum KB a CSS file might have in IE
        See Also:
        Constant Field Values

    • Constructor Detail

      • UnifiedResponse

        public UnifiedResponse​(@Nonnull
                       com.helger.http.EHttpVersion eHttpVersion,
                       @Nonnull
                       com.helger.commons.http.EHttpMethod eHttpMethod,
                       @Nonnull
                       jakarta.servlet.http.HttpServletRequest aHttpRequest)
        Constructor
        Parameters:
        eHttpVersion - HTTP version of this request (1.0 or 1.1)
        eHttpMethod - HTTP method of this request (GET, POST, ...)
        aHttpRequest - The main HTTP request

    • Method Detail

      • isSilentMode

        public static boolean isSilentMode()

      • setSilentMode

        public static boolean setSilentMode​(boolean bSilentMode)

      • getRequestURL

        @Nonnull
@Nonempty
protected final String getRequestURL()

      • showRequestInfo

        protected final void showRequestInfo()

      • getHttpVersion

        @Nonnull
public final com.helger.http.EHttpVersion getHttpVersion()
        Returns:
        The HTTP version of the request. Never null.

      • getHttpMethod

        @Nonnull
public final com.helger.commons.http.EHttpMethod getHttpMethod()
        Returns:
        The HTTP method of the request. Never null.

      • getRequestBrowserInfo

        @Nullable
public final com.helger.useragent.browser.BrowserInfo getRequestBrowserInfo()
        Returns:
        The browser info of the request. Never null.

      • setRequestBrowserInfo

        @Nonnull
public final UnifiedResponse setRequestBrowserInfo​(@Nullable
                                                   com.helger.useragent.browser.BrowserInfo aRequestBrowserInfo)

      • isAllowContentOnRedirect

        public final boolean isAllowContentOnRedirect()
        Returns:
        true if content is allowed even if a redirect is present.

      • setAllowContentOnRedirect

        @Nonnull
public final UnifiedResponse setAllowContentOnRedirect​(boolean bAllowContentOnRedirect)

      • isAllowContentOnStatusCode

        public final boolean isAllowContentOnStatusCode()
        Returns:
        true if content is allowed even if a status code is present.

      • setAllowContentOnStatusCode

        @Nonnull
public final UnifiedResponse setAllowContentOnStatusCode​(boolean bAllowContentOnStatusCode)

      • getMimeType

        @Nullable
public final com.helger.commons.mime.IMimeType getMimeType()

      • hasContent

        public final boolean hasContent()
        Returns:
        true if a content was already set, false if not.

      • setEmptyContent

        @Nonnull
public final UnifiedResponse setEmptyContent()
        Utility method to set an empty response content.
        Returns:
        this

      • setContentAndCharset

        @Nonnull
public final UnifiedResponse setContentAndCharset​(@Nonnull
                                                  String sContent,
                                                  @Nonnull
                                                  Charset aCharset)
        Utility method to set content and charset at once.
        Parameters:
        sContent - The response content string. May not be null.
        aCharset - The charset to use. May not be null.
        Returns:
        this

      • setContent

        @Nonnull
public final UnifiedResponse setContent​(@Nonnull
                                        byte[] aContent)
        Set the response content. To return an empty response pass in a new empty array, but not null.
        Parameters:
        aContent - The content to be returned. Is not copied inside! May not be null but maybe empty.
        Returns:
        this

      • setContent

        @Nonnull
public final UnifiedResponse setContent​(@Nonnull
                                        byte[] aContent,
                                        @Nonnegative
                                        int nOfs,
                                        @Nonnegative
                                        int nLen)
        Set the response content. To return an empty response pass in a new empty array, but not null.
        Parameters:
        aContent - The content to be returned. Is not copied inside! May not be null but maybe empty.
        nOfs - The content offset to start at. Must be ≥ 0.
        nLen - The content length to use. Must be ≥ 0 and ≤ than the content length!
        Returns:
        this

      • setContent

        @Nonnull
public final UnifiedResponse setContent​(@Nonnull
                                        com.helger.commons.io.IHasInputStream aISP)
        Set the response content provider.
        Parameters:
        aISP - The content provider to be used. May not be null.
        Returns:
        this

      • setETag

        @Nonnull
public final UnifiedResponse setETag​(@Nonnull @Nonempty
                                     String sETag)
        Set an ETag for the response. The ETag must be a quoted value (being surrounded by double quotes).
        Parameters:
        sETag - The quoted ETag to be set. May neither be null nor empty.
        Returns:
        this

      • setETagIfApplicable

        @Nonnull
public final UnifiedResponse setETagIfApplicable​(@Nonnull @Nonempty
                                                 String sETag)
        Set an ETag for the response if this is an HTTP/1.1 response. HTTP/1.0 does not support ETags. The ETag must be a quoted value (being surrounded by double quotes).
        Parameters:
        sETag - The quoted ETag to be set. May neither be null nor empty.
        Returns:
        this

      • setContentDispositionFilename

        @Nonnull
public final UnifiedResponse setContentDispositionFilename​(@Nonnull @Nonempty
                                                           String sFilename)
        Set the content disposition filename for attachment download.
        Parameters:
        sFilename - The filename for attachment download to use. May neither be null nor empty.
        Returns:
        this
        See Also:
        removeContentDispositionFilename()

      • getContentDispositionFilename

        @Nullable
public final String getContentDispositionFilename()
        Returns:
        The current content disposition filename. May be null if not set.

      • removeContentDispositionFilename

        @Nonnull
public final UnifiedResponse removeContentDispositionFilename()
        Remove the current content disposition filename. This method can be called if a filename is set or not.
        Returns:
        this

      • setDownloadFilename

        @Nonnull
public final UnifiedResponse setDownloadFilename​(@Nonnull @Nonempty
                                                 String sFilename)
        Utility method for setting the MimeType application/force-download and set the respective content disposition filename.
        Parameters:
        sFilename - The filename to be used.
        Returns:
        this

      • cacheControl

        @Nullable
@ReturnsMutableObject
public final com.helger.http.CacheControlBuilder cacheControl()

      • responseHeaderMap

        @Nonnull
@ReturnsMutableObject
protected final com.helger.commons.http.HttpHeaderMap responseHeaderMap()
        Returns:
        The non-null header map.

      • removeCaching

        @Nonnull
public final UnifiedResponse removeCaching()
        Remove all settings and headers relevant to caching.
        Returns:
        this for chaining

      • disableCaching

        @Nonnull
public final UnifiedResponse disableCaching()
        A utility method that disables caching for this response.
        Returns:
        this

      • enableCaching

        @Nonnull
public final UnifiedResponse enableCaching​(@Nonnegative
                                           int nSeconds)
        Enable caching of this resource for the specified number of seconds.
        Parameters:
        nSeconds - The number of seconds caching is allowed. Must be > 0.
        Returns:
        this

      • isStatusCodeDefined

        public final boolean isStatusCodeDefined()
        Returns:
        true if a status code is defined, false if not.

      • getStatusCode

        public final int getStatusCode()
        Returns:
        The HTTP status code defined or CGlobal.ILLEGAL_UINT if undefined.
        See Also:
        isStatusCodeDefined()

      • setStatus

        @Nonnull
public final UnifiedResponse setStatus​(@Nonnegative
                                       int nStatusCode)
        Set the status code to be returned from the response.
        Parameters:
        nStatusCode - The status code to be set. Must be a valid HTTP response code.
        Returns:
        this

      • setStatusUnauthorized

        @Nonnull
public final UnifiedResponse setStatusUnauthorized​(@Nullable
                                                   String sAuthenticate)
        Special handling for returning status code 401 UNAUTHORIZED.
        Parameters:
        sAuthenticate - The string to be used for the CHttpHeader.WWW_AUTHENTICATE response header. May be null or empty.
        Returns:
        this

      • isRedirectDefined

        public final boolean isRedirectDefined()

      • isWarnOnDuplicateCookies

        public final boolean isWarnOnDuplicateCookies()
        Returns:
        true if warning on duplicated cookies is enabled, false if it is disabled.
        Since:
        6.0.5

      • setWarnOnDuplicateCookies

        @Nonnull
public final UnifiedResponse setWarnOnDuplicateCookies​(boolean bWarnOnDuplicateCookies)
        Enable or disable warning message on duplicated cookie names.
        Parameters:
        bWarnOnDuplicateCookies - true to enable warnings, false to disable them.
        Returns:
        this
        Since:
        6.0.5

      • addCookie

        @Nonnull
public final UnifiedResponse addCookie​(@Nonnull
                                       jakarta.servlet.http.Cookie aCookie)
        Add the passed cookie.
        Parameters:
        aCookie - The cookie to be added. May not be null.
        Returns:
        this

      • removeCookie

        @Nonnull
public final UnifiedResponse removeCookie​(@Nullable
                                          String sName)
        Remove the cookie with the specified name.
        Parameters:
        sName - The name of the cookie to be removed. May be null.
        Returns:
        this

      • removeAllCookies

        @Nonnull
public final com.helger.commons.state.EChange removeAllCookies()
        Remove all cookies.
        Returns:
        EChange.CHANGED if at least one cookie was removed.
        Since:
        6.0.5

      • hasCookies

        public final boolean hasCookies()
        Returns:
        true if at least one cookie is present.
        Since:
        6.0.5

      • getAllCookies

        @Nonnull
@ReturnsMutableCopy
public final com.helger.commons.collection.impl.ICommonsOrderedMap<String,​jakarta.servlet.http.Cookie> getAllCookies()
        Returns:
        A copy of all contained cookies. Never null but maybe empty.
        Since:
        6.0.5

      • setHttpHeaderValuesUnified

        @Nonnull
public final UnifiedResponse setHttpHeaderValuesUnified​(boolean bHttpHeaderValuesUnified)
        Enable or disable the unification of HTTP header values.
        Parameters:
        bHttpHeaderValuesUnified - true to enable it, false to disable it.
        Returns:
        this for chaining
        Since:
        9.1.4

      • setHttpHeaderValuesQuoteIfNecessary

        @Nonnull
public final UnifiedResponse setHttpHeaderValuesQuoteIfNecessary​(boolean bHttpHeaderValuesQuoteIfNecessary)
        Enable or disable the automatic quoting of HTTP header values. This only takes effect, if the unification is enabled.
        Parameters:
        bHttpHeaderValuesQuoteIfNecessary - true to enable it, false to disable it.
        Returns:
        this for chaining
        Since:
        9.1.4
        See Also:
        setHttpHeaderValuesUnified(boolean)

      • setAllowMimeSniffing

        @Nonnull
public final UnifiedResponse setAllowMimeSniffing​(boolean bAllow)
        When specifying false, this method uses a special response header to prevent certain browsers from MIME-sniffing a response away from the declared content-type. When passing true, that header is removed.
        Parameters:
        bAllow - Whether or not sniffing should be allowed (default is true).
        Returns:
        this

      • setEnableXSSFilter

        @Nonnull
public final UnifiedResponse setEnableXSSFilter​(boolean bEnable)
        This header enables the Cross-site scripting (XSS) filter built into most recent web browsers. It's usually enabled by default anyway, so the role of this header is to re-enable the filter for this particular website if it was disabled by the user. This header is supported in IE 8+, and in Chrome (not sure which versions). The anti-XSS filter was added in Chrome 4. Its unknown if that version honored this header.
        Parameters:
        bEnable - true to enable the header, false to disable it.
        Returns:
        this
        Since:
        6.0.5

      • setStrictTransportSecurity

        @Nonnull
public final UnifiedResponse setStrictTransportSecurity​(int nMaxAgeSeconds,
                                                        boolean bIncludeSubdomains)
        When specifying false, this method uses a special response header to prevent certain browsers from MIME-sniffing a response away from the declared content-type. When passing true, that header is removed.
        Parameters:
        nMaxAgeSeconds - number of seconds, after the reception of the STS header field, during which the UA regards the host (from whom the message was received) as a Known HSTS Host.
        bIncludeSubdomains - if enabled, this signals the UA that the HSTS Policy applies to this HSTS Host as well as any sub-domains of the host's domain name.
        Returns:
        this

      • removeStrictTransportSecurity

        @Nonnull
public final UnifiedResponse removeStrictTransportSecurity()
        Remove the X-Frame-Options HTTP header if it is present.
        Returns:
        this
        Since:
        6.0.5

      • setXFrameOptions

        @Nonnull
public final UnifiedResponse setXFrameOptions​(@Nonnull
                                              EXFrameOptionType eType,
                                              @Nullable
                                              com.helger.commons.url.ISimpleURL aDomain)
        The X-Frame-Options HTTP response header can be used to indicate whether or not a browser should be allowed to render a page in a <frame>, <iframe> or <object> . Sites can use this to avoid clickjacking attacks, by ensuring that their content is not embedded into other sites. Example: 
         X-Frame-Options: DENY
 X-Frame-Options: SAMEORIGIN
 X-Frame-Options: ALLOW-FROM https://example.com/
        Parameters:
        eType - The X-Frame-Options type to be set. May not be null.
        aDomain - The domain URL to be used in "ALLOW-FROM". May be null for the other cases.
        Returns:
        this
        Since:
        6.0.5

      • removeXFrameOptions

        @Nonnull
public final UnifiedResponse removeXFrameOptions()
        Remove the X-Frame-Options HTTP header if it is present.
        Returns:
        this
        Since:
        6.0.5

      • addCustomResponseHeader

        public final void addCustomResponseHeader​(@Nonnull @Nonempty
                                          String sName,
                                          @Nonnull @Nonempty
                                          String sValue)
        Adds a response header to the response according to the passed name and value. If an existing header with the same is present, the value is added to the list so that the header is emitted more than once.
        ATTENTION: You should only use the APIs that UnifiedResponse directly offers. Use this method only in emergency and make sure you validate the header field and allowed value!
        Parameters:
        sName - Name of the header. May neither be null nor empty.
        sValue - Value of the header. May neither be null nor empty.

      • addCustomResponseHeaders

        public final void addCustomResponseHeaders​(@Nullable
                                           com.helger.commons.http.HttpHeaderMap aOther)
        Add many custom headers at once.
        Parameters:
        aOther - The headers to be added. May be null.

      • setCustomResponseHeader

        public final void setCustomResponseHeader​(@Nonnull @Nonempty
                                          String sName,
                                          @Nonnull @Nonempty
                                          String sValue)
        Sets a response header to the response according to the passed name and value. An existing header entry with the same name is overridden.
        ATTENTION: You should only use the APIs that UnifiedResponse directly offers. Use this method only in emergency and make sure you validate the header field and allowed value!
        Parameters:
        sName - Name of the header. May neither be null nor empty.
        sValue - Value of the header. May neither be null nor empty.

      • setCustomResponseHeaders

        public final void setCustomResponseHeaders​(@Nullable
                                           com.helger.commons.http.HttpHeaderMap aOther)
        Set many custom headers at once. All existing headers are unconditionally removed.
        Parameters:
        aOther - The headers to be set. May be null.

      • removeCustomResponseHeaders

        @Nonnull
public final com.helger.commons.state.EChange removeCustomResponseHeaders​(@Nonnull @Nonempty
                                                                          String sName)
        Removes the response headers matching the passed name from the response.
        ATTENTION: You should only use the APIs that UnifiedResponse directly offers. Use this method only in emergency and make sure you validate the header field and allowed value!
        Parameters:
        sName - Name of the header to be removed. May neither be null nor empty.
        Returns:
        EChange.CHANGED in header was removed.

      • applyToResponse

        public final void applyToResponse​(@Nonnull
                                  jakarta.servlet.http.HttpServletResponse aHttpResponse)
                           throws IOException
        Throws:
        IOException

      • createSimple

        @Nonnull
public static UnifiedResponse createSimple​(@Nonnull
                                           jakarta.servlet.http.HttpServletRequest aHttpRequest)
        Factory method
        Parameters:
        aHttpRequest - The main HTTP request. May not be null.
        Returns:
        New UnifiedResponse. Never null.
        Since:
        8.8.0