/*
 * Copyright (c) 2010, 2019 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package jakarta.ws.rs;

import jakarta.ws.rs.core.Response;

Runtime exception for applications.

This exception may be thrown by a resource method, provider or StreamingOutput implementation if a specific HTTP error response needs to be produced. Only effective if thrown prior to the response being committed.

Author:Paul Sandoz, Marek Potociar
Since:1.0
/** * Runtime exception for applications. * <p> * This exception may be thrown by a resource method, provider or {@link jakarta.ws.rs.core.StreamingOutput} * implementation if a specific HTTP error response needs to be produced. Only effective if thrown prior to the response * being committed. * * @author Paul Sandoz * @author Marek Potociar * @since 1.0 */
public class WebApplicationException extends RuntimeException { private static final long serialVersionUID = 8273970399584007146L; private final Response response;
Construct a new instance with a default HTTP status code of 500 and a default message generated from the HTTP status code and the associated HTTP status reason phrase.
/** * Construct a new instance with a default HTTP status code of 500 and a default message generated from the HTTP status * code and the associated HTTP status reason phrase. */
public WebApplicationException() { this((Throwable) null, Response.Status.INTERNAL_SERVER_ERROR); }
Construct a new instance with the supplied message and a default HTTP status code of 500.
Params:
Since:2.0
/** * Construct a new instance with the supplied message and a default HTTP status code of 500. * * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method). * @since 2.0 */
public WebApplicationException(final String message) { this(message, null, Response.Status.INTERNAL_SERVER_ERROR); }
Construct a new instance using the supplied response and a default message generated from the response's HTTP status code and the associated HTTP status reason phrase.
Params:
  • response – the response that will be returned to the client, a value of null will be replaced with an internal server error response (status code 500).
/** * Construct a new instance using the supplied response and a default message generated from the response's HTTP status * code and the associated HTTP status reason phrase. * * @param response the response that will be returned to the client, a value of null will be replaced with an internal * server error response (status code 500). */
public WebApplicationException(final Response response) { this((Throwable) null, response); }
Construct a new instance using the supplied message and response.
Params:
  • message – the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
  • response – the response that will be returned to the client, a value of null will be replaced with an internal server error response (status code 500).
Since:2.0
/** * Construct a new instance using the supplied message and response. * * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method). * @param response the response that will be returned to the client, a value of null will be replaced with an internal * server error response (status code 500). * @since 2.0 */
public WebApplicationException(final String message, final Response response) { this(message, null, response); }
Construct a new instance with the supplied HTTP status code and a default message generated from the HTTP status code and the associated HTTP status reason phrase.
Params:
  • status – the HTTP status code that will be returned to the client.
/** * Construct a new instance with the supplied HTTP status code and a default message generated from the HTTP status code * and the associated HTTP status reason phrase. * * @param status the HTTP status code that will be returned to the client. */
public WebApplicationException(final int status) { this((Throwable) null, status); }
Construct a new instance with a supplied message and HTTP status code.
Params:
  • message – the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
  • status – the HTTP status code that will be returned to the client.
Since:2.0
/** * Construct a new instance with a supplied message and HTTP status code. * * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method). * @param status the HTTP status code that will be returned to the client. * @since 2.0 */
public WebApplicationException(final String message, final int status) { this(message, null, status); }
Construct a new instance with the supplied HTTP status and a default message generated from the HTTP status code and the associated HTTP status reason phrase.
Params:
  • status – the HTTP status code that will be returned to the client.
Throws:
/** * Construct a new instance with the supplied HTTP status and a default message generated from the HTTP status code and * the associated HTTP status reason phrase. * * @param status the HTTP status code that will be returned to the client. * @throws IllegalArgumentException if status is {@code null}. */
public WebApplicationException(final Response.Status status) { this((Throwable) null, status); }
Construct a new instance with the supplied message and HTTP status.
Params:
  • message – the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
  • status – the HTTP status code that will be returned to the client.
Throws:
Since:2.0
/** * Construct a new instance with the supplied message and HTTP status. * * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method). * @param status the HTTP status code that will be returned to the client. * @throws IllegalArgumentException if status is {@code null}. * @since 2.0 */
public WebApplicationException(final String message, final Response.Status status) { this(message, null, status); }
Construct a new instance with the supplied root cause, default HTTP status code of 500 and a default message generated from the HTTP status code and the associated HTTP status reason phrase.
Params:
  • cause – the underlying cause of the exception.
/** * Construct a new instance with the supplied root cause, default HTTP status code of 500 and a default message * generated from the HTTP status code and the associated HTTP status reason phrase. * * @param cause the underlying cause of the exception. */
public WebApplicationException(final Throwable cause) { this(cause, Response.Status.INTERNAL_SERVER_ERROR); }
Construct a new instance with the supplied message, root cause and default HTTP status code of 500.
Params:
  • message – the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
  • cause – the underlying cause of the exception.
Since:2.0
/** * Construct a new instance with the supplied message, root cause and default HTTP status code of 500. * * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method). * @param cause the underlying cause of the exception. * @since 2.0 */
public WebApplicationException(final String message, final Throwable cause) { this(message, cause, Response.Status.INTERNAL_SERVER_ERROR); }
Construct a new instance with the supplied root cause, response and a default message generated from the response's HTTP status code and the associated HTTP status reason phrase.
Params:
  • response – the response that will be returned to the client, a value of null will be replaced with an internal server error response (status code 500).
  • cause – the underlying cause of the exception.
/** * Construct a new instance with the supplied root cause, response and a default message generated from the response's * HTTP status code and the associated HTTP status reason phrase. * * @param response the response that will be returned to the client, a value of null will be replaced with an internal * server error response (status code 500). * @param cause the underlying cause of the exception. */
public WebApplicationException(final Throwable cause, final Response response) { this(computeExceptionMessage(response), cause, response); }
Construct a new instance with the supplied message, root cause and response.
Params:
  • message – the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
  • response – the response that will be returned to the client, a value of null will be replaced with an internal server error response (status code 500).
  • cause – the underlying cause of the exception.
Since:2.0
/** * Construct a new instance with the supplied message, root cause and response. * * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method). * @param response the response that will be returned to the client, a value of null will be replaced with an internal * server error response (status code 500). * @param cause the underlying cause of the exception. * @since 2.0 */
public WebApplicationException(final String message, final Throwable cause, final Response response) { super(message, cause); if (response == null) { this.response = Response.serverError().build(); } else { this.response = response; } } private static String computeExceptionMessage(final Response response) { final Response.StatusType statusInfo; if (response != null) { statusInfo = response.getStatusInfo(); } else { statusInfo = Response.Status.INTERNAL_SERVER_ERROR; } return "HTTP " + statusInfo.getStatusCode() + ' ' + statusInfo.getReasonPhrase(); }
Construct a new instance with the supplied root cause, HTTP status code and a default message generated from the HTTP status code and the associated HTTP status reason phrase.
Params:
  • status – the HTTP status code that will be returned to the client.
  • cause – the underlying cause of the exception.
/** * Construct a new instance with the supplied root cause, HTTP status code and a default message generated from the HTTP * status code and the associated HTTP status reason phrase. * * @param status the HTTP status code that will be returned to the client. * @param cause the underlying cause of the exception. */
public WebApplicationException(final Throwable cause, final int status) { this(cause, Response.status(status).build()); }
Construct a new instance with the supplied message, root cause and HTTP status code.
Params:
  • message – the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
  • status – the HTTP status code that will be returned to the client.
  • cause – the underlying cause of the exception.
Since:2.0
/** * Construct a new instance with the supplied message, root cause and HTTP status code. * * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method). * @param status the HTTP status code that will be returned to the client. * @param cause the underlying cause of the exception. * @since 2.0 */
public WebApplicationException(final String message, final Throwable cause, final int status) { this(message, cause, Response.status(status).build()); }
Construct a new instance with the supplied root cause, HTTP status code and a default message generated from the HTTP status code and the associated HTTP status reason phrase.
Params:
  • status – the HTTP status code that will be returned to the client.
  • cause – the underlying cause of the exception.
Throws:
/** * Construct a new instance with the supplied root cause, HTTP status code and a default message generated from the HTTP * status code and the associated HTTP status reason phrase. * * @param status the HTTP status code that will be returned to the client. * @param cause the underlying cause of the exception. * @throws IllegalArgumentException if status is {@code null}. */
public WebApplicationException(final Throwable cause, final Response.Status status) throws IllegalArgumentException { this(cause, Response.status(status).build()); }
Construct a new instance with a the supplied message, root cause and HTTP status code.
Params:
  • message – the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
  • status – the HTTP status code that will be returned to the client.
  • cause – the underlying cause of the exception.
Since:2.0
/** * Construct a new instance with a the supplied message, root cause and HTTP status code. * * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method). * @param status the HTTP status code that will be returned to the client. * @param cause the underlying cause of the exception. * @since 2.0 */
public WebApplicationException(final String message, final Throwable cause, final Response.Status status) throws IllegalArgumentException { this(message, cause, Response.status(status).build()); }
Get the HTTP response.
Returns:the HTTP response.
/** * Get the HTTP response. * * @return the HTTP response. */
public Response getResponse() { return response; }
Validate that a Response object has an expected HTTP response status code set.
Params:
  • response – response object.
  • expectedStatus – expected response status code.
Throws:
Returns:validated response object.
Since:2.0
/** * Validate that a {@link jakarta.ws.rs.core.Response} object has an expected HTTP response status code set. * * @param response response object. * @param expectedStatus expected response status code. * @return validated response object. * @throws IllegalArgumentException if the response validation failed. * @since 2.0 */
static Response validate(final Response response, final Response.Status expectedStatus) { if (expectedStatus.getStatusCode() != response.getStatus()) { throw new IllegalArgumentException(String.format("Invalid response status code. Expected [%d], was [%d].", expectedStatus.getStatusCode(), response.getStatus())); } return response; }
Validate that a Response object has an expected HTTP response status code set.
Params:
  • response – response object.
  • expectedStatusFamily – expected response status code family.
Throws:
Returns:validated response object.
Since:2.0
/** * Validate that a {@link jakarta.ws.rs.core.Response} object has an expected HTTP response status code set. * * @param response response object. * @param expectedStatusFamily expected response status code family. * @return validated response object. * @throws IllegalArgumentException if the response validation failed. * @since 2.0 */
static Response validate(final Response response, final Response.Status.Family expectedStatusFamily) { if (response.getStatusInfo().getFamily() != expectedStatusFamily) { throw new IllegalArgumentException(String.format( "Status code of the supplied response [%d] is not from the required status code family \"%s\".", response.getStatus(), expectedStatusFamily)); } return response; } }