org.apache.juneau.rest.ResponseHandler Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.rest;
import java.io.*;
import javax.servlet.http.*;
import org.apache.juneau.*;
import org.apache.juneau.rest.annotation.*;
import org.apache.juneau.rest.response.*;
/**
* Defines the interface for handlers that convert POJOs to appropriate HTTP responses.
*
*
* The {@link RestServlet} API uses the concept of registered response handlers for converting objects returned by REST
* methods or set through {@link RestResponse#setOutput(Object)} into appropriate HTTP responses.
*
*
* Response handlers can be associated with {@link RestServlet RestServlets} through the following ways:
*
* -
* Through the {@link RestResource#responseHandlers @RestResource.responseHandlers} annotation.
*
-
* By calling the {@link RestConfig#addResponseHandlers(Class...)} and augmenting or creating your
* own list of handlers.
*
*
*
* By default, {@link RestServlet RestServlets} are registered with the following response handlers:
*
* -
* {@link DefaultHandler} - Serializes POJOs using the Juneau serializer API.
*
-
* {@link ReaderHandler} - Pipes the output of {@link Reader Readers} to the response writer
* ({@link RestResponse#getWriter()}).
*
-
* {@link InputStreamHandler} - Pipes the output of {@link InputStream InputStreams} to the response output
* stream ({@link RestResponse#getOutputStream()}).
*
-
* {@link RedirectHandler} - Handles {@link Redirect} objects.
*
-
* {@link WritableHandler} - Handles {@link Writable} objects.
*
-
* {@link StreamableHandler} - Handles {@link Streamable} objects.
*
*
*
* Response handlers can be used to process POJOs that cannot normally be handled through Juneau serializers, or
* because it's simply easier to define response handlers for special cases.
*
*
* The following example shows how to create a response handler to handle special Foo objects outside the
* normal Juneau architecture.
*
* @RestResource (
* path="/example" ,
* responseHandlers=FooHandler.class
* )
* public class Example extends RestServlet {
*
* @RestMethod (name=GET , path="/" )
* public Foo test1() {
* return new Foo("123" );
* }
*
* public static class FooHandler implements ResponseHandler {
* @Override
* public boolean handle(RestRequest req, RestResponse res, Object output) throws IOException, RestException {
* if (output instanceof Foo) {
* Foo foo = (Foo)output;
* // Set some headers and body content.
* res.setHeader("Foo-ID" , foo.getId());
* res.getWriter().write("foo.id=" + foo.getId());
* return true ; // We handled it.
* }
* return false ; // We didn't handle it.
* }
* }
* }
*
*/
public interface ResponseHandler {
/**
* Process this response if possible.
* This method should return false if it wasn't able to process the response.
*
* @param req The HTTP servlet request.
* @param res The HTTP servlet response;
* @param output The POJO returned by the REST method that now needs to be sent to the response.
* @return true If this handler handled the response.
* @throws IOException
* If low-level exception occurred on output stream.
* Results in a {@link HttpServletResponse#SC_INTERNAL_SERVER_ERROR} error.
* @throws RestException
* If some other exception occurred.
* Can be used to provide an appropriate HTTP response code and message.
*/
boolean handle(RestRequest req, RestResponse res, Object output) throws IOException, RestException;
}