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 015 016import java.io.*; 017import java.util.*; 018 019import javax.servlet.*; 020import javax.servlet.http.*; 021 022/** 023 * Class that handles the basic lifecycle of an HTTP REST call. 024 * 025 * <div class='warn'> 026 * <b>Deprecated</b> - Use {@link RestContext#REST_context} and override methods. 027 * </div> 028 */ 029@Deprecated 030public interface RestCallHandler { 031 032 /** 033 * Represents no RestCallHandler. 034 */ 035 public interface Null extends RestCallHandler {} 036 037 /** 038 * The main service method. 039 * 040 * @param r1 The incoming HTTP servlet request object. 041 * @param r2 The incoming HTTP servlet response object. 042 * @throws ServletException Error occurred. 043 * @throws IOException Thrown by underlying stream. 044 */ 045 public void execute(HttpServletRequest r1, HttpServletResponse r2) throws ServletException, IOException; 046 047 /** 048 * Wraps an incoming servlet request/response pair into a single {@link RestCall} object. 049 * 050 * @param req The rest request. 051 * @param res The rest response. 052 * @return The wrapped request/response pair. 053 */ 054 public RestCall createCall(HttpServletRequest req, HttpServletResponse res); 055 056 /** 057 * Creates a {@link RestRequest} object based on the specified incoming {@link HttpServletRequest} object. 058 * 059 * @param call The current REST call. 060 * @return The wrapped request object. 061 * @throws ServletException If any errors occur trying to interpret the request. 062 */ 063 public RestRequest createRequest(RestCall call) throws ServletException; 064 065 /** 066 * Creates a {@link RestResponse} object based on the specified incoming {@link HttpServletResponse} object 067 * and the request returned by {@link #createRequest(RestCall)}. 068 * 069 * @param call The current REST call. 070 * @return The wrapped response object. 071 * @throws ServletException If any errors occur trying to interpret the request or response. 072 */ 073 public RestResponse createResponse(RestCall call) throws ServletException; 074 075 /** 076 * The main method for serializing POJOs passed in through the {@link RestResponse#setOutput(Object)} method or 077 * returned by the Java method. 078 * 079 * @param call The current REST call. 080 * @throws Exception Can be thrown if error occurred while handling response. 081 */ 082 public void handleResponse(RestCall call) throws Exception; 083 084 /** 085 * Handle the case where a matching method was not found. 086 * 087 * @param call The current REST call. 088 * @throws Exception Can be thrown if error occurred while handling response. 089 */ 090 public void handleNotFound(RestCall call) throws Exception; 091 092 /** 093 * Method for handling response errors. 094 * 095 * @param call The current REST call. 096 * @param e The exception that occurred. 097 * @throws Exception Can be thrown if error occurred while handling response. 098 */ 099 public void handleError(RestCall call, Throwable e) throws Exception; 100 101 /** 102 * Method for converting thrown exceptions into other types before they are handled. 103 * 104 * @param t The thrown object. 105 * @return The converted thrown object. 106 */ 107 public Throwable convertThrowable(Throwable t); 108 109 /** 110 * Returns the session objects for the specified request. 111 * 112 * @param req The REST request. 113 * @param res The REST response. 114 * @return The session objects for that request. 115 */ 116 public Map<String,Object> getSessionObjects(RestRequest req, RestResponse res); 117}