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