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 }