Coverage Report

Coverage Report - com.jcabi.http.Request

Classes in this File

 /**
  * Copyright (c) 2011-2017, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met: 1) Redistributions of source code must retain the above
  * copyright notice, this list of conditions and the following
  * disclaimer. 2) Redistributions in binary form must reproduce the above
  * copyright notice, this list of conditions and the following
  * disclaimer in the documentation and/or other materials provided
  * with the distribution. 3) Neither the name of the jcabi.com nor
  * the names of its contributors may be used to endorse or promote
  * products derived from this software without specific prior written
  * permission.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
  * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
  * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  * OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 package com.jcabi.http;
 
 import com.jcabi.aspects.Immutable;
 import java.io.IOException;
 import java.io.InputStream;
 
 /**
  * RESTful request.
  *
  * <p>Instance of this class is supposed to be used this way:
  *
  * <pre> String name = new ApacheRequest("https://www.example.com:8080")
  *   .uri().path("/users").queryParam("id", 333).back()
  *   .method(Request.GET)
  *   .header(HttpHeaders.ACCEPT, MediaType.TEXT_XML)
  *   .fetch()
  *   .as(RestResponse.class)
  *   .assertStatus(HttpURLConnection.HTTP_OK)
  *   .as(XmlResponse.class)
  *   .assertXPath("/page/links/link[@rel='see']")
  *   .rel("/page/links/link[@rel='see']/@href")
  *   .header(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON)
  *   .fetch()
  *   .as(JsonResponse.class)
  *   .json().getJsonObject().getString("name");</pre>
  *
  * <p>Since version 0.10 it is recommended to use
  * {@link com.jcabi.http.wire.RetryWire}
  * decorator to avoid accidental {@link IOException} when connection is weak
  * or unstable, for example:
  *
  * <pre> String body = new JdkRequest("https://www.google.com")
  *   .through(RetryWire.class)
  *   .fetch()
  *   .body();</pre>
  *
  * <p>Instances of this interface are immutable and thread-safe.
  *
  * <p>You can use either {@link ApacheRequest} or {@link JdkRequest},
  * according to your needs. {@link JdkRequest} won't require any additional
  * dependencies, while {@link ApacheRequest} will properly support all
  * possible HTTP methods ({@link JdkRequest} doesn't support {@code PATCH},
  * for example).
  *
  * @author Yegor Bugayenko (yegor@tpc2.com)
  * @version $Id: 571c08293eadd539fa97a07fddbd599f2b967108 $
  * @since 0.8
  * @see com.jcabi.http.request.JdkRequest
  * @see com.jcabi.http.request.ApacheRequest
  */
 @Immutable
 @SuppressWarnings("PMD.AvoidDuplicateLiterals")
 public interface Request {
 
     /**
      * GET method name.
      */
     String GET = "GET";
 
     /**
      * POST method name.
      */
     String POST = "POST";
 
     /**
      * PUT method name.
      */
     String PUT = "PUT";
 
     /**
      * HEAD method name.
      */
     String HEAD = "HEAD";
 
     /**
      * DELETE method name.
      */
     String DELETE = "DELETE";
 
     /**
      * OPTIONS method name.
      */
     String OPTIONS = "OPTIONS";
 
     /**
      * PATCH method name.
      */
     String PATCH = "PATCH";
 
     /**
      * Get destination URI.
      * @return The destination it is currently pointing to
      */
     RequestURI uri();
 
     /**
      * Get request body.
      * @return New alternated request
      */
     RequestBody body();
 
     /**
      * Get multipart form (multipart/form-data) body.
      * @return New altered request
      */
     RequestBody multipartBody();
 
     /**
      * Set request header.
      * @param name ImmutableHeader name
      * @param value Value of the header to set
      * @return New alternated request
      */
     Request header(String name, Object value);
 
     /**
      * Remove all headers with this name.
      * @param name ImmutableHeader name
      * @return New alternated request
      * @since 0.10
      */
     Request reset(String name);
 
     /**
      * Use this method.
      * @param method The method to use
      * @return New alternated request
      */
     Request method(String method);
 
     /**
      * Use this timeout values.
      * @param connect The connect timeout to use in ms
      * @param read The read timeout to use in ms
      * @return New alternated request
      */
     Request timeout(int connect, int read);
 
     /**
      * Execute it with a specified HTTP method.
      * @return Response
      * @throws IOException If fails to fetch HTTP request
      */
     Response fetch() throws IOException;
 
     /**
      * Execute this request using the content provided by the
      * {@link InputStream} being passed as the request body. Note that the
      * request MUST have an empty body when this method is being invoked, or
      * it will throw an {@link IllegalStateException}.
      *
      * @param stream The input stream to use
      * @return Response
      * @throws IOException If fails to fetch HTTP request
      * @since 1.8
      */
     Response fetch(InputStream stream) throws IOException;
 
     /**
      * Send it through a decorating {@link Wire}.
      * @param type Type of wire to use
      * @param args Optional arguments for the wire constructor
      * @param <T> Type to use
      * @return New request with a wire decorated
      * @since 0.10
      */
     <T extends Wire> Request through(Class<T> type, Object... args);
 
 }

1		/**
2		* Copyright (c) 2011-2017, jcabi.com
3		* All rights reserved.
4		*
5		* Redistribution and use in source and binary forms, with or without
6		* modification, are permitted provided that the following conditions
7		* are met: 1) Redistributions of source code must retain the above
8		* copyright notice, this list of conditions and the following
9		* disclaimer. 2) Redistributions in binary form must reproduce the above
10		* copyright notice, this list of conditions and the following
11		* disclaimer in the documentation and/or other materials provided
12		* with the distribution. 3) Neither the name of the jcabi.com nor
13		* the names of its contributors may be used to endorse or promote
14		* products derived from this software without specific prior written
15		* permission.
16		*
17		* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18		* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
19		* NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20		* FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21		* THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22		* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23		* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24		* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25		* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26		* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27		* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28		* OF THE POSSIBILITY OF SUCH DAMAGE.
29		*/
30		package com.jcabi.http;
31
32		import com.jcabi.aspects.Immutable;
33		import java.io.IOException;
34		import java.io.InputStream;
35
36		/**
37		* RESTful request.
38		*
39		* <p>Instance of this class is supposed to be used this way:
40		*
41		* <pre> String name = new ApacheRequest("https://www.example.com:8080")
42		* .uri().path("/users").queryParam("id", 333).back()
43		* .method(Request.GET)
44		* .header(HttpHeaders.ACCEPT, MediaType.TEXT_XML)
45		* .fetch()
46		* .as(RestResponse.class)
47		* .assertStatus(HttpURLConnection.HTTP_OK)
48		* .as(XmlResponse.class)
49		* .assertXPath("/page/links/link[@rel='see']")
50		* .rel("/page/links/link[@rel='see']/@href")
51		* .header(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON)
52		* .fetch()
53		* .as(JsonResponse.class)
54		* .json().getJsonObject().getString("name");</pre>
55		*
56		* <p>Since version 0.10 it is recommended to use
57		* {@link com.jcabi.http.wire.RetryWire}
58		* decorator to avoid accidental {@link IOException} when connection is weak
59		* or unstable, for example:
60		*
61		* <pre> String body = new JdkRequest("https://www.google.com")
62		* .through(RetryWire.class)
63		* .fetch()
64		* .body();</pre>
65		*
66		* <p>Instances of this interface are immutable and thread-safe.
67		*
68		* <p>You can use either {@link ApacheRequest} or {@link JdkRequest},
69		* according to your needs. {@link JdkRequest} won't require any additional
70		* dependencies, while {@link ApacheRequest} will properly support all
71		* possible HTTP methods ({@link JdkRequest} doesn't support {@code PATCH},
72		* for example).
73		*
74		* @author Yegor Bugayenko (yegor@tpc2.com)
75		* @version $Id: 571c08293eadd539fa97a07fddbd599f2b967108 $
76		* @since 0.8
77		* @see com.jcabi.http.request.JdkRequest
78		* @see com.jcabi.http.request.ApacheRequest
79		*/
80		@Immutable
81		@SuppressWarnings("PMD.AvoidDuplicateLiterals")
82		public interface Request {
83
84		/**
85		* GET method name.
86		*/
87		String GET = "GET";
88
89		/**
90		* POST method name.
91		*/
92		String POST = "POST";
93
94		/**
95		* PUT method name.
96		*/
97		String PUT = "PUT";
98
99		/**
100		* HEAD method name.
101		*/
102		String HEAD = "HEAD";
103
104		/**
105		* DELETE method name.
106		*/
107		String DELETE = "DELETE";
108
109		/**
110		* OPTIONS method name.
111		*/
112		String OPTIONS = "OPTIONS";
113
114		/**
115		* PATCH method name.
116		*/
117		String PATCH = "PATCH";
118
119		/**
120		* Get destination URI.
121		* @return The destination it is currently pointing to
122		*/
123		RequestURI uri();
124
125		/**
126		* Get request body.
127		* @return New alternated request
128		*/
129		RequestBody body();
130
131		/**
132		* Get multipart form (multipart/form-data) body.
133		* @return New altered request
134		*/
135		RequestBody multipartBody();
136
137		/**
138		* Set request header.
139		* @param name ImmutableHeader name
140		* @param value Value of the header to set
141		* @return New alternated request
142		*/
143		Request header(String name, Object value);
144
145		/**
146		* Remove all headers with this name.
147		* @param name ImmutableHeader name
148		* @return New alternated request
149		* @since 0.10
150		*/
151		Request reset(String name);
152
153		/**
154		* Use this method.
155		* @param method The method to use
156		* @return New alternated request
157		*/
158		Request method(String method);
159
160		/**
161		* Use this timeout values.
162		* @param connect The connect timeout to use in ms
163		* @param read The read timeout to use in ms
164		* @return New alternated request
165		*/
166		Request timeout(int connect, int read);
167
168		/**
169		* Execute it with a specified HTTP method.
170		* @return Response
171		* @throws IOException If fails to fetch HTTP request
172		*/
173		Response fetch() throws IOException;
174
175		/**
176		* Execute this request using the content provided by the
177		* {@link InputStream} being passed as the request body. Note that the
178		* request MUST have an empty body when this method is being invoked, or
179		* it will throw an {@link IllegalStateException}.
180		*
181		* @param stream The input stream to use
182		* @return Response
183		* @throws IOException If fails to fetch HTTP request
184		* @since 1.8
185		*/
186		Response fetch(InputStream stream) throws IOException;
187
188		/**
189		* Send it through a decorating {@link Wire}.
190		* @param type Type of wire to use
191		* @param args Optional arguments for the wire constructor
192		* @param <T> Type to use
193		* @return New request with a wire decorated
194		* @since 0.10
195		*/
196		<T extends Wire> Request through(Class<T> type, Object... args);
197
198		}