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 org.apache.juneau.http.exception.*; 016import org.apache.juneau.rest.annotation.*; 017import org.apache.juneau.rest.converters.*; 018import org.apache.juneau.serializer.*; 019 020/** 021 * REST method response converter. 022 * 023 * <p> 024 * Implements a filter mechanism for REST method calls that allows response objects to be converted to some other POJO 025 * after invocation of the REST method. 026 * 027 * <p> 028 * Converters are associated with REST methods through the following: 029 * <ul class='javatree'> 030 * <li class='ja'>{@link RestResource#converters()} 031 * <li class='ja'>{@link RestMethod#converters()} 032 * <li class='jf'>{@link RestContext#REST_converters} 033 * <li class='jm'>{@link RestContextBuilder#converters(Class...)} 034 * <li class='jm'>{@link RestContextBuilder#converters(RestConverter...)} 035 * </ul> 036 * 037 * <h5 class='section'>Example:</h5> 038 * <p class='bcode w800'> 039 * <jk>public class</jk> RequestEchoResource <jk>extends</jk> RestServlet { 040 * 041 * <jc>// GET request handler</jc> 042 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/*"</js>, converters={Queryable.<jk>class</jk>,Traversable.<jk>class</jk>}) 043 * <jk>public</jk> HttpServletRequest doGet(RestRequest req) { 044 * res.setTitle(<js>"Contents of HttpServletRequest object"</js>); 045 * <jk>return</jk> req; 046 * } 047 * } 048 * </p> 049 * 050 * <p> 051 * Converters can also be associated at the servlet level using the {@link RestResource#converters() @RestResource(converters)} annotation. 052 * <br>Applying converters at the resource level is equivalent to applying converters to each resource method individually. 053 * 054 * <h5 class='topic'>How to implement</h5> 055 * 056 * Implementers should simply implement the {@link #convert(RestRequest, Object)} and return back a 'converted' object. 057 * <br>It's up to the implementer to decide what this means. 058 * 059 * <p> 060 * Subclasses must implement one of the following constructors: 061 * <ul> 062 * <li><jk>public</jk> T(); <jc>// No-arg constructor</jc> 063 * <li><jk>public</jk> T(PropertyStore); <jc>// Property store of the RestContext</jc> 064 * </ul> 065 * 066 * <p> 067 * Subclasses can also be defined as inner classes of the resource class. 068 * 069 * <h5 class='topic'>Predefined converters</h5> 070 * <ul class='javatree'> 071 * <li class='jc'>{@link Traversable} - Allows URL additional path info to address individual elements in a POJO tree. 072 * <li class='jc'>{@link Queryable} - Allows query/view/sort functions to be performed on POJOs. 073 * <li class='jc'>{@link Introspectable} - Allows Java public methods to be invoked on the returned POJOs. 074 * </ul> 075 * 076 * <ul class='seealso'> 077 * <li class='jf'>{@link RestContext#REST_converters} - Registering converters with REST resources. 078 * <li class='link'>{@doc juneau-rest-server.Converters} 079 * </ul> 080 */ 081public interface RestConverter { 082 083 /** 084 * Performs post-call conversion on the specified response object. 085 * 086 * @param req The servlet request. 087 * @param res The response object set by the REST method through the {@link RestResponse#setOutput(Object)} method. 088 * @return The converted object. 089 * @throws HttpException Thrown if any errors occur during conversion. 090 * @throws SerializeException Generic serialization error occurred. 091 */ 092 public Object convert(RestRequest req, Object res) throws HttpException, SerializeException; 093}