All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.eclipse.jetty.client.api.Request Maven / Gradle / Ivy

The newest version!
//
//  ========================================================================
//  Copyright (c) 1995-2012 Mort Bay Consulting Pty. Ltd.
//  ------------------------------------------------------------------------
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================
//

package org.eclipse.jetty.client.api;

import java.io.IOException;
import java.nio.file.Path;
import java.util.EventListener;
import java.util.List;
import java.util.Map;
import java.util.concurrent.Future;

import org.eclipse.jetty.client.HttpClient;
import org.eclipse.jetty.http.HttpFields;
import org.eclipse.jetty.http.HttpMethod;
import org.eclipse.jetty.http.HttpVersion;
import org.eclipse.jetty.util.Fields;

/**
 * 

{@link Request} represents a HTTP request, and offers a fluent interface to customize * various attributes such as the path, the headers, the content, etc.

*

You can create {@link Request} objects via {@link HttpClient#newRequest(String)} and * you can send them using either {@link #send()} for a blocking semantic, or * {@link #send(Response.Listener)} for an asynchronous semantic.

* * @see Response */ public interface Request { /** * @return the conversation id */ long getConversationID(); /** * @return the scheme of this request, such as "http" or "https" */ String getScheme(); /** * @param scheme the scheme of this request, such as "http" or "https" * @return this request object */ Request scheme(String scheme); /** * @return the host of this request, such as "127.0.0.1" or "google.com" */ String getHost(); /** * @return the port of this request such as 80 or 443 */ int getPort(); /** * @return the method of this request, such as GET or POST */ HttpMethod getMethod(); /** * @param method the method of this request, such as GET or POST * @return this request object */ Request method(HttpMethod method); /** * @return the path of this request, such as "/" */ String getPath(); /** * @param path the path of this request, such as "/" * @return this request object */ Request path(String path); /** * @return the full URI of this request such as "http://host:port/path" */ String getURI(); /** * @return the HTTP version of this request, such as "HTTP/1.1" */ HttpVersion getVersion(); /** * @param version the HTTP version of this request, such as "HTTP/1.1" * @return this request object */ Request version(HttpVersion version); /** * @return the query parameters of this request */ Fields getParams(); /** * @param name the name of the query parameter * @param value the value of the query parameter * @return this request object */ Request param(String name, String value); /** * @return the headers of this request */ HttpFields getHeaders(); /** * @param name the name of the header * @param value the value of the header * @return this request object */ Request header(String name, String value); /** * @param name the name of the attribute * @param value the value of the attribute * @return this request object */ Request attribute(String name, Object value); /** * @return the attributes of this request */ Map getAttributes(); /** * @return the content provider of this request */ ContentProvider getContent(); /** * @param content the content provider of this request * @return this request object */ Request content(ContentProvider content); /** * Shortcut method to specify a file as a content for this request, with the default content type of * "application/octect-stream". * * @param file the file to upload * @return this request object * @throws IOException if the file does not exist or cannot be read */ Request file(Path file) throws IOException; /** * Shortcut method to specify a file as a content for this request, with the given content type. * * @param file the file to upload * @param contentType the content type of the file * @return this request object * @throws IOException if the file does not exist or cannot be read */ Request file(Path file, String contentType) throws IOException; /** * @return the user agent for this request */ String getAgent(); /** * @param agent the user agent for this request * @return this request object */ Request agent(String agent); /** * @return the idle timeout for this request */ long getIdleTimeout(); /** * @param timeout the idle timeout for this request * @return this request object */ Request idleTimeout(long timeout); /** * @return whether this request follows redirects */ boolean isFollowRedirects(); /** * @param follow whether this request follows redirects * @return this request object */ Request followRedirects(boolean follow); /** * @param listenerClass the class of the listener, or null for all listeners classes * @return the listeners for request events of the given class */ List getRequestListeners(Class listenerClass); /** * @param listener a listener for request events * @return this request object */ Request listener(Listener listener); /** * @param listener a listener for request queued event * @return this request object */ Request onRequestQueued(QueuedListener listener); /** * @param listener a listener for request begin event * @return this request object */ Request onRequestBegin(BeginListener listener); /** * @param listener a listener for request headers event * @return this request object */ Request onRequestHeaders(HeadersListener listener); /** * @param listener a listener for request success event * @return this request object */ Request onRequestSuccess(SuccessListener listener); /** * @param listener a listener for request failure event * @return this request object */ Request onRequestFailure(FailureListener listener); /** * @param listener a listener for response begin event * @return this request object */ Request onResponseBegin(Response.BeginListener listener); /** * @param listener a listener for response headers event * @return this request object */ Request onResponseHeaders(Response.HeadersListener listener); /** * @param listener a listener for response content events * @return this request object */ Request onResponseContent(Response.ContentListener listener); /** * @param listener a listener for response success event * @return this request object */ Request onResponseSuccess(Response.SuccessListener listener); /** * @param listener a listener for response failure event * @return this request object */ Request onResponseFailure(Response.FailureListener listener); /** * Sends this request and returns a {@link Future} that can be used to wait for the * request and the response to be completed (either with a success or a failure). *

* This method should be used when a simple blocking semantic is needed, and when it is known * that the response content can be buffered without exceeding memory constraints. * For example, this method is not appropriate to download big files from a server; consider using * {@link #send(Response.Listener)} instead, passing your own {@link Response.Listener} or a utility * listener such as {@link InputStreamResponseListener}. *

* The future will return when {@link Response.Listener#onComplete(Result)} is invoked. * * @return a {@link Future} to wait on for request and response completion * @see Response.Listener#onComplete(Result) */ Future send(); /** * Sends this request and asynchronously notifies the given listener for response events. *

* This method should be used when the application needs to be notified of the various response events * as they happen, or when the application needs to efficiently manage the response content. * * @param listener the listener that receives response events */ void send(Response.CompleteListener listener); /** * Attempts to abort the send of this request. * * @param cause the abort cause, must not be null * @return whether the abort succeeded */ boolean abort(Throwable cause); /** * @return the abort cause passed to {@link #abort(Throwable)}, * or null if this request has not been aborted */ Throwable getAbortCause(); public interface RequestListener extends EventListener { } public interface QueuedListener extends RequestListener { /** * Callback method invoked when the request is queued, waiting to be sent * * @param request the request being queued */ public void onQueued(Request request); } public interface BeginListener extends RequestListener { /** * Callback method invoked when the request begins being processed in order to be sent. * This is the last opportunity to modify the request. * * @param request the request that begins being processed */ public void onBegin(Request request); } public interface HeadersListener extends RequestListener { /** * Callback method invoked when the request headers (and perhaps small content) have been sent. * The request is now committed, and in transit to the server, and further modifications to the * request may have no effect. * @param request the request that has been committed */ public void onHeaders(Request request); } public interface SuccessListener extends RequestListener { /** * Callback method invoked when the request has been successfully sent. * * @param request the request sent */ public void onSuccess(Request request); } public interface FailureListener extends RequestListener { /** * Callback method invoked when the request has failed to be sent * @param request the request that failed * @param failure the failure */ public void onFailure(Request request, Throwable failure); } /** * Listener for all request events */ public interface Listener extends QueuedListener, BeginListener, HeadersListener, SuccessListener, FailureListener { /** * An empty implementation of {@link Listener} */ public static class Empty implements Listener { @Override public void onQueued(Request request) { } @Override public void onBegin(Request request) { } @Override public void onHeaders(Request request) { } @Override public void onSuccess(Request request) { } @Override public void onFailure(Request request, Throwable failure) { } } } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy