1 // 2 // ======================================================================== 3 // Copyright (c) 1995-2015 Mort Bay Consulting Pty. Ltd. 4 // ------------------------------------------------------------------------ 5 // All rights reserved. This program and the accompanying materials 6 // are made available under the terms of the Eclipse Public License v1.0 7 // and Apache License v2.0 which accompanies this distribution. 8 // 9 // The Eclipse Public License is available at 10 // http://www.eclipse.org/legal/epl-v10.html 11 // 12 // The Apache License v2.0 is available at 13 // http://www.opensource.org/licenses/apache2.0.php 14 // 15 // You may elect to redistribute this code under either of these licenses. 16 // ======================================================================== 17 // 18 19 package org.eclipse.jetty.client.api; 20 21 import java.io.Closeable; 22 import java.nio.ByteBuffer; 23 import java.util.Iterator; 24 25 import org.eclipse.jetty.client.util.ByteBufferContentProvider; 26 import org.eclipse.jetty.client.util.PathContentProvider; 27 28 /** 29 * <p>{@link ContentProvider} provides a source of request content.</p> 30 * <p>Implementations should return an {@link Iterator} over the request content. 31 * If the request content comes from a source that needs to be closed (for 32 * example, an {@link java.io.InputStream}), then the iterator implementation class 33 * must implement {@link Closeable} and will be closed when the request is 34 * completed (either successfully or failed).</p> 35 * <p>Applications should rely on utility classes such as {@link ByteBufferContentProvider} 36 * or {@link PathContentProvider}.</p> 37 * <p>{@link ContentProvider} provides a {@link #getLength() length} of the content 38 * it represents. 39 * If the length is positive, it typically overrides any {@code Content-Length} 40 * header set by applications; if the length is negative, it typically removes 41 * any {@code Content-Length} header set by applications, resulting in chunked 42 * content (i.e. {@code Transfer-Encoding: chunked}) being sent to the server.</p> 43 */ 44 public interface ContentProvider extends Iterable<ByteBuffer> 45 { 46 /** 47 * @return the content length, if known, or -1 if the content length is unknown 48 */ 49 long getLength(); 50 51 /** 52 * An extension of {@link ContentProvider} that provides a content type string 53 * to be used as a {@code Content-Type} HTTP header in requests. 54 */ 55 public interface Typed extends ContentProvider 56 { 57 /** 58 * @return the content type string such as "application/octet-stream" or 59 * "application/json;charset=UTF8", or null if no content type must be set 60 */ 61 public String getContentType(); 62 } 63 }