View Javadoc

1   /*
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  
20  package org.apache.hadoop.hbase.rest.client;
21  
22  import java.io.IOException;
23  import java.io.InputStream;
24  import java.util.Collections;
25  import java.util.Map;
26  import java.util.concurrent.ConcurrentHashMap;
27  
28  import org.apache.commons.httpclient.Header;
29  import org.apache.commons.httpclient.HttpClient;
30  import org.apache.commons.httpclient.HttpMethod;
31  import org.apache.commons.httpclient.HttpVersion;
32  import org.apache.commons.httpclient.MultiThreadedHttpConnectionManager;
33  import org.apache.commons.httpclient.URI;
34  import org.apache.commons.httpclient.methods.ByteArrayRequestEntity;
35  import org.apache.commons.httpclient.methods.DeleteMethod;
36  import org.apache.commons.httpclient.methods.GetMethod;
37  import org.apache.commons.httpclient.methods.HeadMethod;
38  import org.apache.commons.httpclient.methods.PostMethod;
39  import org.apache.commons.httpclient.methods.PutMethod;
40  import org.apache.commons.httpclient.params.HttpClientParams;
41  import org.apache.commons.httpclient.params.HttpConnectionManagerParams;
42  import org.apache.commons.logging.Log;
43  import org.apache.commons.logging.LogFactory;
44  import org.apache.hadoop.classification.InterfaceAudience;
45  import org.apache.hadoop.classification.InterfaceStability;
46  
47  /**
48   * A wrapper around HttpClient which provides some useful function and
49   * semantics for interacting with the REST gateway.
50   */
51  @InterfaceAudience.Public
52  @InterfaceStability.Stable
53  public class Client {
54    public static final Header[] EMPTY_HEADER_ARRAY = new Header[0];
55  
56    private static final Log LOG = LogFactory.getLog(Client.class);
57  
58    private HttpClient httpClient;
59    private Cluster cluster;
60  
61    private Map<String, String> extraHeaders;
62  
63    /**
64     * Default Constructor
65     */
66    public Client() {
67      this(null);
68    }
69  
70    /**
71     * Constructor
72     * @param cluster the cluster definition
73     */
74    public Client(Cluster cluster) {
75      this.cluster = cluster;
76      MultiThreadedHttpConnectionManager manager = 
77        new MultiThreadedHttpConnectionManager();
78      HttpConnectionManagerParams managerParams = manager.getParams();
79      managerParams.setConnectionTimeout(2000); // 2 s
80      managerParams.setDefaultMaxConnectionsPerHost(10);
81      managerParams.setMaxTotalConnections(100);
82      extraHeaders = new ConcurrentHashMap<String, String>();
83      this.httpClient = new HttpClient(manager);
84      HttpClientParams clientParams = httpClient.getParams();
85      clientParams.setVersion(HttpVersion.HTTP_1_1);
86    }
87  
88    /**
89     * Shut down the client. Close any open persistent connections. 
90     */
91    public void shutdown() {
92      MultiThreadedHttpConnectionManager manager = 
93        (MultiThreadedHttpConnectionManager) httpClient.getHttpConnectionManager();
94      manager.shutdown();
95    }
96  
97    /**
98     * @return the wrapped HttpClient
99     */
100   public HttpClient getHttpClient() {
101     return httpClient;
102   }
103 
104   /**
105    * Add extra headers.  These extra headers will be applied to all http
106    * methods before they are removed. If any header is not used any more,
107    * client needs to remove it explicitly.
108    */
109   public void addExtraHeader(final String name, final String value) {
110     extraHeaders.put(name, value);
111   }
112 
113   /**
114    * Get an extra header value.
115    */
116   public String getExtraHeader(final String name) {
117     return extraHeaders.get(name);
118   }
119 
120   /**
121    * Get all extra headers (read-only).
122    */
123   public Map<String, String> getExtraHeaders() {
124     return Collections.unmodifiableMap(extraHeaders);
125   }
126 
127   /**
128    * Remove an extra header.
129    */
130   public void removeExtraHeader(final String name) {
131     extraHeaders.remove(name);
132   }
133 
134   /**
135    * Execute a transaction method given only the path. Will select at random
136    * one of the members of the supplied cluster definition and iterate through
137    * the list until a transaction can be successfully completed. The
138    * definition of success here is a complete HTTP transaction, irrespective
139    * of result code.  
140    * @param cluster the cluster definition
141    * @param method the transaction method
142    * @param headers HTTP header values to send
143    * @param path the properly urlencoded path
144    * @return the HTTP response code
145    * @throws IOException
146    */
147   public int executePathOnly(Cluster cluster, HttpMethod method,
148       Header[] headers, String path) throws IOException {
149     IOException lastException;
150     if (cluster.nodes.size() < 1) {
151       throw new IOException("Cluster is empty");
152     }
153     int start = (int)Math.round((cluster.nodes.size() - 1) * Math.random());
154     int i = start;
155     do {
156       cluster.lastHost = cluster.nodes.get(i);
157       try {
158         StringBuilder sb = new StringBuilder();
159         sb.append("http://");
160         sb.append(cluster.lastHost);
161         sb.append(path);
162         URI uri = new URI(sb.toString(), true);
163         return executeURI(method, headers, uri.toString());
164       } catch (IOException e) {
165         lastException = e;
166       }
167     } while (++i != start && i < cluster.nodes.size());
168     throw lastException;
169   }
170 
171   /**
172    * Execute a transaction method given a complete URI.
173    * @param method the transaction method
174    * @param headers HTTP header values to send
175    * @param uri a properly urlencoded URI
176    * @return the HTTP response code
177    * @throws IOException
178    */
179   public int executeURI(HttpMethod method, Header[] headers, String uri)
180       throws IOException {
181     method.setURI(new URI(uri, true));
182     for (Map.Entry<String, String> e: extraHeaders.entrySet()) {
183       method.addRequestHeader(e.getKey(), e.getValue());
184     }
185     if (headers != null) {
186       for (Header header: headers) {
187         method.addRequestHeader(header);
188       }
189     }
190     long startTime = System.currentTimeMillis();
191     int code = httpClient.executeMethod(method);
192     long endTime = System.currentTimeMillis();
193     if (LOG.isDebugEnabled()) {
194       LOG.debug(method.getName() + " " + uri + " " + code + " " +
195         method.getStatusText() + " in " + (endTime - startTime) + " ms");
196     }
197     return code;
198   }
199 
200   /**
201    * Execute a transaction method. Will call either <tt>executePathOnly</tt>
202    * or <tt>executeURI</tt> depending on whether a path only is supplied in
203    * 'path', or if a complete URI is passed instead, respectively.
204    * @param cluster the cluster definition
205    * @param method the HTTP method
206    * @param headers HTTP header values to send
207    * @param path the properly urlencoded path or URI
208    * @return the HTTP response code
209    * @throws IOException
210    */
211   public int execute(Cluster cluster, HttpMethod method, Header[] headers,
212       String path) throws IOException {
213     if (path.startsWith("/")) {
214       return executePathOnly(cluster, method, headers, path);
215     }
216     return executeURI(method, headers, path);
217   }
218 
219   /**
220    * @return the cluster definition
221    */
222   public Cluster getCluster() {
223     return cluster;
224   }
225 
226   /**
227    * @param cluster the cluster definition
228    */
229   public void setCluster(Cluster cluster) {
230     this.cluster = cluster;
231   }
232 
233   /**
234    * Send a HEAD request 
235    * @param path the path or URI
236    * @return a Response object with response detail
237    * @throws IOException
238    */
239   public Response head(String path) throws IOException {
240     return head(cluster, path, null);
241   }
242 
243   /**
244    * Send a HEAD request 
245    * @param cluster the cluster definition
246    * @param path the path or URI
247    * @param headers the HTTP headers to include in the request
248    * @return a Response object with response detail
249    * @throws IOException
250    */
251   public Response head(Cluster cluster, String path, Header[] headers) 
252       throws IOException {
253     HeadMethod method = new HeadMethod();
254     try {
255       int code = execute(cluster, method, null, path);
256       headers = method.getResponseHeaders();
257       return new Response(code, headers, null);
258     } finally {
259       method.releaseConnection();
260     }
261   }
262 
263   /**
264    * Send a GET request 
265    * @param path the path or URI
266    * @return a Response object with response detail
267    * @throws IOException
268    */
269   public Response get(String path) throws IOException {
270     return get(cluster, path);
271   }
272 
273   /**
274    * Send a GET request 
275    * @param cluster the cluster definition
276    * @param path the path or URI
277    * @return a Response object with response detail
278    * @throws IOException
279    */
280   public Response get(Cluster cluster, String path) throws IOException {
281     return get(cluster, path, EMPTY_HEADER_ARRAY);
282   }
283 
284   /**
285    * Send a GET request 
286    * @param path the path or URI
287    * @param accept Accept header value
288    * @return a Response object with response detail
289    * @throws IOException
290    */
291   public Response get(String path, String accept) throws IOException {
292     return get(cluster, path, accept);
293   }
294 
295   /**
296    * Send a GET request 
297    * @param cluster the cluster definition
298    * @param path the path or URI
299    * @param accept Accept header value
300    * @return a Response object with response detail
301    * @throws IOException
302    */
303   public Response get(Cluster cluster, String path, String accept)
304       throws IOException {
305     Header[] headers = new Header[1];
306     headers[0] = new Header("Accept", accept);
307     return get(cluster, path, headers);
308   }
309 
310   /**
311    * Send a GET request
312    * @param path the path or URI
313    * @param headers the HTTP headers to include in the request, 
314    * <tt>Accept</tt> must be supplied
315    * @return a Response object with response detail
316    * @throws IOException
317    */
318   public Response get(String path, Header[] headers) throws IOException {
319     return get(cluster, path, headers);
320   }
321 
322   /**
323    * Send a GET request
324    * @param c the cluster definition
325    * @param path the path or URI
326    * @param headers the HTTP headers to include in the request
327    * @return a Response object with response detail
328    * @throws IOException
329    */
330   public Response get(Cluster c, String path, Header[] headers) 
331       throws IOException {
332     GetMethod method = new GetMethod();
333     try {
334       int code = execute(c, method, headers, path);
335       headers = method.getResponseHeaders();
336       byte[] body = method.getResponseBody();
337       InputStream in = method.getResponseBodyAsStream();
338       return new Response(code, headers, body, in);
339     } finally {
340       method.releaseConnection();
341     }
342   }
343 
344   /**
345    * Send a PUT request
346    * @param path the path or URI
347    * @param contentType the content MIME type
348    * @param content the content bytes
349    * @return a Response object with response detail
350    * @throws IOException
351    */
352   public Response put(String path, String contentType, byte[] content)
353       throws IOException {
354     return put(cluster, path, contentType, content);
355   }
356 
357   /**
358    * Send a PUT request
359    * @param cluster the cluster definition
360    * @param path the path or URI
361    * @param contentType the content MIME type
362    * @param content the content bytes
363    * @return a Response object with response detail
364    * @throws IOException
365    */
366   public Response put(Cluster cluster, String path, String contentType, 
367       byte[] content) throws IOException {
368     Header[] headers = new Header[1];
369     headers[0] = new Header("Content-Type", contentType);
370     return put(cluster, path, headers, content);
371   }
372 
373   /**
374    * Send a PUT request
375    * @param path the path or URI
376    * @param headers the HTTP headers to include, <tt>Content-Type</tt> must be
377    * supplied
378    * @param content the content bytes
379    * @return a Response object with response detail
380    * @throws IOException
381    */
382   public Response put(String path, Header[] headers, byte[] content) 
383       throws IOException {
384     return put(cluster, path, headers, content);
385   }
386 
387   /**
388    * Send a PUT request
389    * @param cluster the cluster definition
390    * @param path the path or URI
391    * @param headers the HTTP headers to include, <tt>Content-Type</tt> must be
392    * supplied
393    * @param content the content bytes
394    * @return a Response object with response detail
395    * @throws IOException
396    */
397   public Response put(Cluster cluster, String path, Header[] headers, 
398       byte[] content) throws IOException {
399     PutMethod method = new PutMethod();
400     try {
401       method.setRequestEntity(new ByteArrayRequestEntity(content));
402       int code = execute(cluster, method, headers, path);
403       headers = method.getResponseHeaders();
404       content = method.getResponseBody();
405       return new Response(code, headers, content);
406     } finally {
407       method.releaseConnection();
408     }
409   }
410 
411   /**
412    * Send a POST request
413    * @param path the path or URI
414    * @param contentType the content MIME type
415    * @param content the content bytes
416    * @return a Response object with response detail
417    * @throws IOException
418    */
419   public Response post(String path, String contentType, byte[] content)
420       throws IOException {
421     return post(cluster, path, contentType, content);
422   }
423 
424   /**
425    * Send a POST request
426    * @param cluster the cluster definition
427    * @param path the path or URI
428    * @param contentType the content MIME type
429    * @param content the content bytes
430    * @return a Response object with response detail
431    * @throws IOException
432    */
433   public Response post(Cluster cluster, String path, String contentType, 
434       byte[] content) throws IOException {
435     Header[] headers = new Header[1];
436     headers[0] = new Header("Content-Type", contentType);
437     return post(cluster, path, headers, content);
438   }
439 
440   /**
441    * Send a POST request
442    * @param path the path or URI
443    * @param headers the HTTP headers to include, <tt>Content-Type</tt> must be
444    * supplied
445    * @param content the content bytes
446    * @return a Response object with response detail
447    * @throws IOException
448    */
449   public Response post(String path, Header[] headers, byte[] content) 
450       throws IOException {
451     return post(cluster, path, headers, content);
452   }
453 
454   /**
455    * Send a POST request
456    * @param cluster the cluster definition
457    * @param path the path or URI
458    * @param headers the HTTP headers to include, <tt>Content-Type</tt> must be
459    * supplied
460    * @param content the content bytes
461    * @return a Response object with response detail
462    * @throws IOException
463    */
464   public Response post(Cluster cluster, String path, Header[] headers, 
465       byte[] content) throws IOException {
466     PostMethod method = new PostMethod();
467     try {
468       method.setRequestEntity(new ByteArrayRequestEntity(content));
469       int code = execute(cluster, method, headers, path);
470       headers = method.getResponseHeaders();
471       content = method.getResponseBody();
472       return new Response(code, headers, content);
473     } finally {
474       method.releaseConnection();
475     }
476   }
477 
478   /**
479    * Send a DELETE request
480    * @param path the path or URI
481    * @return a Response object with response detail
482    * @throws IOException
483    */
484   public Response delete(String path) throws IOException {
485     return delete(cluster, path);
486   }
487 
488   /**
489    * Send a DELETE request
490    * @param cluster the cluster definition
491    * @param path the path or URI
492    * @return a Response object with response detail
493    * @throws IOException
494    */
495   public Response delete(Cluster cluster, String path) throws IOException {
496     DeleteMethod method = new DeleteMethod();
497     try {
498       int code = execute(cluster, method, null, path);
499       Header[] headers = method.getResponseHeaders();
500       byte[] content = method.getResponseBody();
501       return new Response(code, headers, content);
502     } finally {
503       method.releaseConnection();
504     }
505   }
506 }