001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.rest; 014 015import java.io.*; 016 017import javax.servlet.http.*; 018 019import org.apache.juneau.rest.annotation.*; 020import org.apache.juneau.rest.reshandlers.*; 021 022/** 023 * Defines the interface for handlers that convert POJOs to appropriate HTTP responses. 024 * 025 * <p> 026 * The REST Server API uses the concept of registered response handlers for converting objects returned by REST 027 * methods or set through {@link RestResponse#setOutput(Object)} into appropriate HTTP responses. 028 * 029 * <p> 030 * Response handlers can be associated with REST resources via the following: 031 * <ul> 032 * <li class='ja'>{@link RestResource#responseHandlers} 033 * <li class='jm'>{@link RestContextBuilder#responseHandlers(Class...)} 034 * <li class='jm'>{@link RestContextBuilder#responseHandlers(ResponseHandler...)} 035 * </ul> 036 * 037 * <p> 038 * By default, REST resources are registered with the following response handlers: 039 * <ul class='spaced-list'> 040 * <li class='jc'> 041 * {@link DefaultHandler} - Serializes POJOs using the Juneau serializer API. 042 * <li class='jc'> 043 * {@link ReaderHandler} - Pipes the output of {@link Reader Readers} to the response writer 044 * ({@link RestResponse#getWriter()}). 045 * <li class='jc'> 046 * {@link InputStreamHandler} - Pipes the output of {@link InputStream InputStreams} to the response output 047 * stream ({@link RestResponse#getOutputStream()}). 048 * </ul> 049 * 050 * <p> 051 * Response handlers can be used to process POJOs that cannot normally be handled through Juneau serializers, or 052 * because it's simply easier to define response handlers for special cases. 053 * 054 * <p> 055 * The following example shows how to create a response handler to handle special <c>Foo</c> objects outside the 056 * normal Juneau architecture. 057 * <p class='bcode w800'> 058 * <ja>@RestResource</ja>( 059 * path=<js>"/example"</js>, 060 * responseHandlers=FooHandler.<jk>class</jk> 061 * ) 062 * <jk>public class</jk> Example <jk>extends</jk> RestServlet { 063 * 064 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>) 065 * <jk>public</jk> Foo test1() { 066 * <jk>return new</jk> Foo(<js>"123"</js>); 067 * } 068 * 069 * <jk>public static class</jk> FooHandler <jk>implements</jk> ResponseHandler { 070 * <ja>@Override</ja> 071 * <jk>public boolean</jk> handle(RestRequest req, RestResponse res, Object output) <jk>throws</jk> IOException, RestException { 072 * <jk>if</jk> (output <jk>instanceof</jk> Foo) { 073 * Foo foo = (Foo)output; 074 * <jc>// Set some headers and body content.</jc> 075 * res.setHeader(<js>"Foo-ID"</js>, foo.getId()); 076 * res.getWriter().write(<js>"foo.id="</js> + foo.getId()); 077 * <jk>return true</jk>; <jc>// We handled it.</jc> 078 * } 079 * <jk>return false</jk>; <jc>// We didn't handle it.</jc> 080 * } 081 * } 082 * } 083 * </p> 084 * 085 * <ul class='seealso'> 086 * <li class='link'>{@doc juneau-rest-server.RestMethod.MethodReturnTypes} 087 * </ul> 088 */ 089public interface ResponseHandler { 090 091 /** 092 * Process this response if possible. 093 * This method should return <jk>false</jk> if it wasn't able to process the response. 094 * 095 * @param req The HTTP servlet request. 096 * @param res The HTTP servlet response; 097 * @return true If this handler handled the response. 098 * @throws IOException 099 * If low-level exception occurred on output stream. 100 * Results in a {@link HttpServletResponse#SC_INTERNAL_SERVER_ERROR} error. 101 * @throws RestException 102 * If some other exception occurred. 103 * Can be used to provide an appropriate HTTP response code and message. 104 */ 105 boolean handle(RestRequest req, RestResponse res) throws IOException, RestException; 106}