org.apache.juneau.rest.client.RestCallHandler 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.client;
import java.io.*;
import org.apache.http.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.protocol.*;
/**
* Interface that allows you to override the handling of HTTP requests.
*
*
* Providing this implementation is the equivalent to overriding the {@link RestClient#execute(HttpHost,HttpRequest,HttpContext)}.
*
This can also be accomplished by providing your own {@link RestClient.Builder#connectionManager(org.apache.http.conn.HttpClientConnectionManager) connection manager}
* or subclassing {@link RestClient}, but this provides a simpler way of handling the requests yourself.
*
*
* The constructor on the implementation class can optionally take in any of the following parameters:
*
* - {@link RestClient} - The client using this handler.
*
*
*
* The {@link BasicRestCallHandler} shows an example of a simple pass-through handler. Note that you must handle
* the case where {@link HttpHost} is null.
*
*
* public class BasicRestCallHandler implements RestCallHandler {
*
* private final RestClient client ;
*
* public BasicRestCallHandler(RestClient client ) {
* this .client = client ;
* }
*
* @Override
* public HttpResponse run(HttpHost target , HttpRequest request , HttpContext context ) throws IOException {
* if (target == null )
* return client .execute((HttpUriRequest)request , context );
* return client .execute(target , request , context );
* }
* }
*
*
* See Also:
* - {@link RestClient.Builder#callHandler()}
*
- juneau-rest-client
*
*/
public interface RestCallHandler {
//-----------------------------------------------------------------------------------------------------------------
// Instance
//-----------------------------------------------------------------------------------------------------------------
/**
* Execute the specified request.
*
*
* Subclasses can override this method to provide specialized handling.
*
* @param target The target host for the request.
*
Implementations may accept null if they can still determine a route, for example to a default
* target or by inspecting the request.
* @param request The request to execute. Must be an instance of {@link HttpUriRequest} if the target is null .
* @param context The context to use for the execution, or null to use the default context.
* @return
* The response to the request.
*
This is always a final response, never an intermediate response with an 1xx status code.
*
Whether redirects or authentication challenges will be returned or handled automatically depends on the
* implementation and configuration of this client.
* @throws IOException In case of a problem or the connection was aborted.
* @throws ClientProtocolException In case of an http protocol error.
*/
HttpResponse run(HttpHost target, HttpRequest request, HttpContext context) throws ClientProtocolException, IOException;
}