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.http.exception.*; 020import org.apache.juneau.rest.annotation.*; 021import org.apache.juneau.rest.reshandlers.*; 022 023/** 024 * Defines the interface for handlers that convert POJOs to appropriate HTTP responses. 025 * 026 * <p> 027 * The REST Server API uses the concept of registered response handlers for converting objects returned by REST 028 * methods or set through {@link RestResponse#setOutput(Object)} into appropriate HTTP responses. 029 * 030 * <p> 031 * Response handlers can be associated with REST resources via the following: 032 * <ul> 033 * <li class='ja'>{@link Rest#responseHandlers} 034 * <li class='jm'>{@link RestContextBuilder#responseHandlers(Class...)} 035 * <li class='jm'>{@link RestContextBuilder#responseHandlers(ResponseHandler...)} 036 * </ul> 037 * 038 * <p> 039 * By default, REST resources are registered with the following response handlers: 040 * <ul class='spaced-list'> 041 * <li class='jc'> 042 * {@link DefaultHandler} - Serializes POJOs using the Juneau serializer API. 043 * <li class='jc'> 044 * {@link ReaderHandler} - Pipes the output of {@link Reader Readers} to the response writer 045 * ({@link RestResponse#getWriter()}). 046 * <li class='jc'> 047 * {@link InputStreamHandler} - Pipes the output of {@link InputStream InputStreams} to the response output 048 * stream ({@link RestResponse#getOutputStream()}). 049 * </ul> 050 * 051 * <p> 052 * Response handlers can be used to process POJOs that cannot normally be handled through Juneau serializers, or 053 * because it's simply easier to define response handlers for special cases. 054 * 055 * <p> 056 * The following example shows how to create a response handler to handle special <c>Foo</c> objects outside the 057 * normal Juneau architecture. 058 * <p class='bcode w800'> 059 * <ja>@Rest</ja>( 060 * path=<js>"/example"</js>, 061 * responseHandlers=FooHandler.<jk>class</jk> 062 * ) 063 * <jk>public class</jk> Example <jk>extends</jk> RestServlet { 064 * 065 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>) 066 * <jk>public</jk> Foo test1() { 067 * <jk>return new</jk> Foo(<js>"123"</js>); 068 * } 069 * 070 * <jk>public static class</jk> FooHandler <jk>implements</jk> ResponseHandler { 071 * <ja>@Override</ja> 072 * <jk>public boolean</jk> handle(RestRequest req, RestResponse res, Object output) <jk>throws</jk> IOException, RestException { 073 * <jk>if</jk> (output <jk>instanceof</jk> Foo) { 074 * Foo foo = (Foo)output; 075 * <jc>// Set some headers and body content.</jc> 076 * res.setHeader(<js>"Foo-ID"</js>, foo.getId()); 077 * res.getWriter().write(<js>"foo.id="</js> + foo.getId()); 078 * <jk>return true</jk>; <jc>// We handled it.</jc> 079 * } 080 * <jk>return false</jk>; <jc>// We didn't handle it.</jc> 081 * } 082 * } 083 * } 084 * </p> 085 * 086 * <ul class='seealso'> 087 * <li class='link'>{@doc juneau-rest-server.RestMethod.MethodReturnTypes} 088 * </ul> 089 */ 090public interface ResponseHandler { 091 092 /** 093 * Process this response if possible. 094 * This method should return <jk>false</jk> if it wasn't able to process the response. 095 * 096 * @param req The HTTP servlet request. 097 * @param res The HTTP servlet response; 098 * @return true If this handler handled the response. 099 * @throws IOException 100 * If low-level exception occurred on output stream. 101 * Results in a {@link HttpServletResponse#SC_INTERNAL_SERVER_ERROR} error. 102 * @throws HttpException 103 * If some other exception occurred. 104 * Can be used to provide an appropriate HTTP response code and message. 105 */ 106 boolean handle(RestRequest req, RestResponse res) throws IOException, HttpException; 107}