Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

restclient: update docs

  • Loading branch information...
commit 08473d124fc950dea350c5d58fd13e3639ee954f 1 parent fe17429
@kgilmer kgilmer authored
View
5 README
@@ -1,5 +0,0 @@
-This is a set of utility classes released into the public domain.
-
-- restclient: a class to simplify java.net.HttpURLConnection for common rest-style API operations.
- Binaries: https://leafcutter.ci.cloudbees.com/job/restclient/lastSuccessfulBuild/artifact/org.touge.restclient/dist/
- Javadoc: https://leafcutter.ci.cloudbees.com/job/restclient/javadoc/
View
5 README.md
@@ -6,8 +6,9 @@
- One file, public domain, drop sources in any project easily.
- Supports vistor-style error handling, header customization.
- Simple deserialization support.
-- Programmatically create URLs with URLBuilder
-- Synchronous or Async (Future style) modes.
+- Programmatically create URLs with URLBuilder.
+- Synchronous or asynchronous (Future-style) calling modes.
+- Optional debug output of requests and response data.
- Examples: http://kgilmer.github.com/touge/
- Binaries: https://leafcutter.ci.cloudbees.com/job/restclient/lastSuccessfulBuild/artifact/org.touge.restclient/dist/
- Javadoc: https://leafcutter.ci.cloudbees.com/job/restclient/javadoc/
View
1  org.touge.restclient/.gitignore
@@ -1 +1,2 @@
javadoc
+docs
View
600 org.touge.restclient/docs/ReSTClientTest.html
@@ -1,600 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
- <meta http-equiv="content-type" content="text/html;charset=utf-8">
- <title>ReSTClientTest.java</title>
- <link rel="stylesheet" href="pycco.css">
-</head>
-<body>
-<div id="background"></div>
-<div id='container'>
-
- <div class='section'>
- <div class='docs'><h1>ReSTClientTest.java</h1></div>
- </div>
- <div class='clearall'>
- <div class='section' id='section-0'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-0'>#</a>
- </div>
- <h3><strong>ReSTClient</strong> wraps java.net.HttpURLConnection and provides facilities for deserialization, explicit and implicit error handling, and request header initialization.</h3>
-<p>ReSTClient sources are <a href="https://github.com/kgilmer/touge">on GitHub</a>.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre><span class="cm">/*</span>
-<span class="cm"> * This file is in the public domain, furnished &quot;as is&quot;, without technical</span>
-<span class="cm"> * support, and with no warranty, express or implied, as to its usefulness for</span>
-<span class="cm"> * any purpose.</span>
-<span class="cm"> */</span>
-<span class="n">package</span> <span class="n">org</span><span class="p">.</span><span class="n">touge</span><span class="p">.</span><span class="n">restclient</span><span class="p">;</span>
-
-<span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="n">ByteArrayInputStream</span><span class="p">;</span>
-<span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="n">IOException</span><span class="p">;</span>
-<span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="n">InputStream</span><span class="p">;</span>
-<span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">util</span><span class="p">.</span><span class="n">HashMap</span><span class="p">;</span>
-<span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">util</span><span class="p">.</span><span class="n">List</span><span class="p">;</span>
-<span class="n">import</span> <span class="n">java</span><span class="p">.</span><span class="n">util</span><span class="p">.</span><span class="n">Map</span><span class="p">;</span>
-
-<span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">touge</span><span class="p">.</span><span class="n">restclient</span><span class="p">.</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">HttpMethod</span><span class="p">;</span>
-<span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">touge</span><span class="p">.</span><span class="n">restclient</span><span class="p">.</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">Response</span><span class="p">;</span>
-<span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">touge</span><span class="p">.</span><span class="n">restclient</span><span class="p">.</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">ResponseDeserializer</span><span class="p">;</span>
-<span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">touge</span><span class="p">.</span><span class="n">restclient</span><span class="p">.</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">URLBuilder</span><span class="p">;</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-1'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-1'>#</a>
- </div>
- <h3>Examples of how to use ReSTClient.</h3>
- </div>
- <div class='code'>
- <div class="highlight"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">ReSTClientTest</span> <span class="p">{</span>
-
- <span class="n">public</span> <span class="k">static</span> <span class="kt">void</span> <span class="n">main</span><span class="p">(</span><span class="n">String</span><span class="p">[]</span> <span class="n">args</span><span class="p">)</span> <span class="n">throws</span> <span class="n">IOException</span> <span class="p">{</span>
-
- <span class="n">ReSTClient</span> <span class="n">restClient</span> <span class="o">=</span> <span class="n">new</span> <span class="n">ReSTClient</span><span class="p">();</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-2'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-2'>#</a>
- </div>
- <p>The most common simple thing to do is GET and return the body
-as a String. ReSTClient:</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">String</span> <span class="n">responseBody</span> <span class="o">=</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">callGet</span><span class="p">(</span><span class="s">&quot;localhost&quot;</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-3'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-3'>#</a>
- </div>
- <p>Another common thing is to POST a String to a server:</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">restClient</span><span class="p">.</span><span class="n">callPost</span><span class="p">(</span><span class="s">&quot;localhost&quot;</span><span class="p">,</span> <span class="s">&quot;my content&quot;</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-4'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-4'>#</a>
- </div>
- <p>Getting more complex, we can specify a deserializer that will turn
-the server response into an Object our client wants. Here we use
-one of the few predefined deserializers.
-Call GET on localhost using long form, pass in a predefined deserializer, no body (since GET), and no custom headers.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">Response</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">resp</span> <span class="o">=</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">call</span><span class="p">(</span><span class="n">HttpMethod</span><span class="p">.</span><span class="n">GET</span><span class="p">,</span> <span class="s">&quot;localhost&quot;</span><span class="p">,</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">STRING_DESERIALIZER</span><span class="p">,</span> <span class="n">null</span><span class="p">,</span> <span class="n">null</span><span class="p">);</span>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;Response: &quot;</span> <span class="o">+</span> <span class="n">resp</span><span class="p">.</span><span class="n">getContent</span><span class="p">());</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-5'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-5'>#</a>
- </div>
- <p>Call get and provide a custom deserializer into a custom type.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">Response</span><span class="o">&lt;</span><span class="n">Double</span><span class="o">&gt;</span> <span class="n">cresp</span> <span class="o">=</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">call</span><span class="p">(</span><span class="n">HttpMethod</span><span class="p">.</span><span class="n">GET</span><span class="p">,</span> <span class="s">&quot;localhost&quot;</span><span class="p">,</span> <span class="n">new</span> <span class="n">ResponseDeserializer</span><span class="o">&lt;</span><span class="n">Double</span><span class="o">&gt;</span><span class="p">()</span> <span class="p">{</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-6'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-6'>#</a>
- </div>
-
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="err">@</span><span class="n">Override</span>
- <span class="n">public</span> <span class="n">Double</span> <span class="n">deserialize</span><span class="p">(</span><span class="n">InputStream</span> <span class="n">input</span><span class="p">,</span> <span class="kt">int</span> <span class="n">responseCode</span><span class="p">,</span> <span class="n">Map</span><span class="o">&lt;</span><span class="n">String</span><span class="p">,</span> <span class="n">List</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;&gt;</span> <span class="n">headers</span><span class="p">)</span> <span class="n">throws</span> <span class="n">IOException</span> <span class="p">{</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-7'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-7'>#</a>
- </div>
- <p>Here one would check the server response and read the input stream.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">String</span> <span class="p">[]</span> <span class="n">s</span> <span class="o">=</span> <span class="s">&quot;321 asdf&quot;</span><span class="p">.</span><span class="n">split</span><span class="p">(</span><span class="s">&quot; &quot;</span><span class="p">);</span>
- <span class="k">return</span> <span class="n">Double</span><span class="p">.</span><span class="n">parseDouble</span><span class="p">(</span><span class="n">s</span><span class="p">[</span><span class="mi">1</span><span class="p">]);</span>
- <span class="p">}</span>
-
- <span class="p">},</span> <span class="n">null</span><span class="p">,</span> <span class="n">null</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-8'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-8'>#</a>
- </div>
- <p>API allows for code that specifically checks for errors,
-or relies on exception handling.
-First we explicitly check for errors.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">resp</span><span class="p">.</span><span class="n">isError</span><span class="p">())</span>
- <span class="n">pl</span><span class="p">(</span><span class="n">resp</span><span class="p">.</span><span class="n">getContent</span><span class="p">());</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-9'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-9'>#</a>
- </div>
- <p>Or we can use an error handler instead.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">restClient</span><span class="p">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">new</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">ErrorHandler</span><span class="p">()</span> <span class="p">{</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-10'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-10'>#</a>
- </div>
-
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="err">@</span><span class="n">Override</span>
- <span class="n">public</span> <span class="kt">void</span> <span class="n">handleError</span><span class="p">(</span><span class="kt">int</span> <span class="n">code</span><span class="p">)</span> <span class="n">throws</span> <span class="n">IOException</span> <span class="p">{</span>
- <span class="n">System</span><span class="p">.</span><span class="n">err</span><span class="p">.</span><span class="n">println</span><span class="p">(</span><span class="s">&quot;HTTP Error &quot;</span> <span class="o">+</span> <span class="n">code</span> <span class="o">+</span> <span class="s">&quot; occurred.&quot;</span><span class="p">);</span>
- <span class="p">}</span>
- <span class="p">});</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-11'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-11'>#</a>
- </div>
- <p>Use URLBuilder to build a url.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">URLBuilder</span> <span class="n">localhost</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">buildURL</span><span class="p">(</span><span class="s">&quot;localhost&quot;</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-12'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-12'>#</a>
- </div>
- <p>Prints http://localhost</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span><span class="n">localhost</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-13'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-13'>#</a>
- </div>
- <p>Prints http://localhost/myservlet</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span>
- <span class="n">localhost</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;//myservlet&quot;</span><span class="p">));</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-14'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-14'>#</a>
- </div>
- <p>do a POST with the short-form method</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">Response</span><span class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span> <span class="n">rc</span> <span class="o">=</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">callPost</span><span class="p">(</span><span class="n">localhost</span><span class="p">,</span> <span class="s">&quot;My POST content&quot;</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-15'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-15'>#</a>
- </div>
- <p>Check the last response for an error.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="k">if</span> <span class="p">(</span><span class="n">rc</span><span class="p">.</span><span class="n">isError</span><span class="p">())</span>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;boo!&quot;</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-16'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-16'>#</a>
- </div>
- <p>Call GET and pass back the raw response InputStream to the client.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">callGet</span><span class="p">(</span><span class="n">localhost</span><span class="p">,</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">INPUTSTREAM_DESERIALIZER</span><span class="p">)</span>
- <span class="p">.</span><span class="n">getContent</span><span class="p">().</span><span class="n">available</span><span class="p">());</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-17'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-17'>#</a>
- </div>
- <p>Create a rest client that will throw exceptions on all HTTP and I/O errors.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">restClient</span><span class="p">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">THROW_ALL_ERRORS</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-18'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-18'>#</a>
- </div>
- <p>This GET will deserialize server response as a string and
-throw IOException on any error.<br />
-</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">Response</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">rs</span> <span class="o">=</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">callGet</span><span class="p">(</span><span class="n">localhost</span><span class="p">,</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">STRING_DESERIALIZER</span><span class="p">);</span>
-
- <span class="n">pl</span><span class="p">(</span><span class="n">rs</span><span class="p">.</span><span class="n">getContent</span><span class="p">());</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-19'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-19'>#</a>
- </div>
- <p>Subsequent calls to this rest client will not throw exceptions on HTTP errors.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">restClient</span><span class="p">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">null</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-20'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-20'>#</a>
- </div>
- <p>Since we do not have an error handler, this call will not throw IOException.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">rs</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">callGet</span><span class="p">(</span><span class="n">localhost</span><span class="p">.</span><span class="n">copy</span><span class="p">(</span><span class="s">&quot;asdf&quot;</span><span class="p">),</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">STRING_DESERIALIZER</span><span class="p">);</span>
-
- <span class="k">if</span> <span class="p">(</span><span class="n">rs</span><span class="p">.</span><span class="n">isError</span><span class="p">())</span>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;Error: &quot;</span> <span class="o">+</span> <span class="n">rs</span><span class="p">.</span><span class="n">getCode</span><span class="p">());</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-21'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-21'>#</a>
- </div>
- <p>Set the error handler to throw all errors.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">restClient</span><span class="p">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">THROW_ALL_ERRORS</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-22'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-22'>#</a>
- </div>
- <p>The following line will throw IOException.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">try</span> <span class="p">{</span>
- <span class="n">rs</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">callGet</span><span class="p">(</span><span class="n">localhost</span><span class="p">.</span><span class="n">copy</span><span class="p">(</span><span class="s">&quot;/asdf&quot;</span><span class="p">),</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">STRING_DESERIALIZER</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-23'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-23'>#</a>
- </div>
- <p>Error is thrown when trying to get content.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span><span class="n">rs</span><span class="p">.</span><span class="n">getContent</span><span class="p">());</span>
- <span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">IOException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;Error: &quot;</span> <span class="o">+</span> <span class="n">e</span><span class="p">.</span><span class="n">getMessage</span><span class="p">());</span>
- <span class="p">}</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-24'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-24'>#</a>
- </div>
- <p>following line will throw IOException </p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">try</span> <span class="p">{</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-25'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-25'>#</a>
- </div>
- <p>Error is thrown when trying to get content.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">String</span> <span class="n">respstr</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">callGet</span><span class="p">(</span><span class="s">&quot;localhost/asdf&quot;</span><span class="p">);</span>
- <span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">IOException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;Error: &quot;</span> <span class="o">+</span> <span class="n">e</span><span class="p">.</span><span class="n">getMessage</span><span class="p">());</span>
- <span class="p">}</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-26'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-26'>#</a>
- </div>
- <p>Only throw errors relating to server problems.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">restClient</span><span class="p">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">THROW_5XX_ERRORS</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-27'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-27'>#</a>
- </div>
- <p>following line will throw IOException </p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">try</span> <span class="p">{</span>
- <span class="n">rs</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">callGet</span><span class="p">(</span><span class="s">&quot;localhost/asdf&quot;</span><span class="p">,</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">STRING_DESERIALIZER</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-28'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-28'>#</a>
- </div>
- <p>Error is not thrown when trying to get content because it is not a server error, but rather a 404.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;Should be true: &quot;</span> <span class="o">+</span> <span class="n">rs</span><span class="p">.</span><span class="n">isError</span><span class="p">());</span>
- <span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">IOException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;Error: &quot;</span> <span class="o">+</span> <span class="n">e</span><span class="p">.</span><span class="n">getMessage</span><span class="p">());</span>
- <span class="p">}</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-29'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-29'>#</a>
- </div>
- <p>following line will throw IOException </p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">restClient</span><span class="p">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">THROW_ALL_ERRORS</span><span class="p">);</span>
- <span class="n">try</span> <span class="p">{</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-30'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-30'>#</a>
- </div>
- <p>Error is thrown when trying to get content.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">String</span> <span class="n">respstr</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">callGetContent</span><span class="p">(</span><span class="n">localhost</span><span class="p">.</span><span class="n">copy</span><span class="p">(</span><span class="s">&quot;/asdf&quot;</span><span class="p">),</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">STRING_DESERIALIZER</span><span class="p">);</span>
- <span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">IOException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;Error: &quot;</span> <span class="o">+</span> <span class="n">e</span><span class="p">.</span><span class="n">getMessage</span><span class="p">());</span>
- <span class="p">}</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-31'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-31'>#</a>
- </div>
- <p>Multipart POST with a file upload.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">Map</span><span class="o">&lt;</span><span class="n">String</span><span class="p">,</span> <span class="n">Object</span><span class="o">&gt;</span> <span class="n">body</span> <span class="o">=</span> <span class="n">new</span> <span class="n">HashMap</span><span class="o">&lt;</span><span class="n">String</span><span class="p">,</span> <span class="n">Object</span><span class="o">&gt;</span><span class="p">();</span>
-
- <span class="n">body</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="s">&quot;tkey&quot;</span><span class="p">,</span> <span class="s">&quot;tval&quot;</span><span class="p">);</span>
- <span class="n">body</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="s">&quot;myfile&quot;</span><span class="p">,</span> <span class="n">new</span> <span class="n">ReSTClient</span><span class="p">.</span><span class="n">FormFile</span><span class="p">(</span><span class="s">&quot;/tmp/boo.txt&quot;</span><span class="p">,</span> <span class="s">&quot;text/plain&quot;</span><span class="p">));</span>
-
- <span class="n">restClient</span><span class="p">.</span><span class="n">callPostMultipart</span><span class="p">(</span><span class="s">&quot;localhost&quot;</span><span class="p">,</span> <span class="n">body</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-32'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-32'>#</a>
- </div>
- <p>PUT, short form, throw exception on error</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">restClient</span><span class="p">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">ReSTClient</span><span class="p">.</span><span class="n">THROW_ALL_ERRORS</span><span class="p">);</span>
- <span class="n">Response</span><span class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span> <span class="n">mr</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">callPut</span><span class="p">(</span><span class="s">&quot;localhost&quot;</span><span class="p">,</span> <span class="n">new</span> <span class="n">ByteArrayInputStream</span><span class="p">(</span><span class="s">&quot;boo&quot;</span><span class="p">.</span><span class="n">getBytes</span><span class="p">()));</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-33'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-33'>#</a>
- </div>
- <p>HTTP DELETE</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">Response</span><span class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span> <span class="n">drc</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">callDelete</span><span class="p">(</span><span class="n">localhost</span><span class="p">.</span><span class="n">copy</span><span class="p">(</span><span class="s">&quot;/deleteurl&quot;</span><span class="p">));</span>
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;should be true: &quot;</span> <span class="o">+</span> <span class="n">drc</span><span class="p">.</span><span class="n">isError</span><span class="p">());</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-34'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-34'>#</a>
- </div>
- <p>HTTP HEAD</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">Response</span><span class="o">&lt;</span><span class="n">Integer</span><span class="o">&gt;</span> <span class="n">mrc</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">callHead</span><span class="p">(</span><span class="n">localhost</span><span class="p">);</span>
-
- <span class="n">pl</span><span class="p">(</span><span class="s">&quot;should be false: &quot;</span> <span class="o">+</span> <span class="n">mrc</span><span class="p">.</span><span class="n">isError</span><span class="p">());</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-35'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-35'>#</a>
- </div>
- <p>When programmatically building URLs it can be nice to have something
-take care of the concatenation, path separators, and scheme.<br />
-URLBuilder is a static helper that does this.</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-36'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-36'>#</a>
- </div>
- <p>This URLBuilder builds https://citibank.com/secureme/halp <br />
-</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">buildURL</span><span class="p">(</span><span class="s">&quot;htTPS://citibank.com/secureme/&quot;</span><span class="p">).</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;/halp&quot;</span><span class="p">));</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-37'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-37'>#</a>
- </div>
- <p>Builds http://yahoo.com/a/mystore/toodles?index=5</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span><span class="n">restClient</span><span class="p">.</span><span class="n">buildURL</span><span class="p">(</span><span class="s">&quot;yahoo.com&quot;</span><span class="p">)</span>
- <span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;a&quot;</span><span class="p">)</span>
- <span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;mystore/&quot;</span><span class="p">)</span>
- <span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;toodles?index=5&quot;</span><span class="p">));</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-38'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-38'>#</a>
- </div>
- <p>Builds http://me.com/you/andi/like/each/ohter</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">buildURL</span><span class="p">(</span><span class="s">&quot;me.com/&quot;</span><span class="p">)</span>
- <span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;/you/&quot;</span><span class="p">)</span>
- <span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;/andi/&quot;</span><span class="p">)</span>
- <span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;like/each/ohter/&quot;</span><span class="p">));</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-39'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-39'>#</a>
- </div>
- <p>Builds https://myhost.com/first/second/third/forth/fith/mypage.asp?i=1&amp;b=2&amp;c=3</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span>
- <span class="n">restClient</span><span class="p">.</span><span class="n">buildURL</span><span class="p">(</span>
- <span class="s">&quot;myhost.com&quot;</span><span class="p">,</span>
- <span class="s">&quot;first/&quot;</span><span class="p">,</span>
- <span class="s">&quot;//second&quot;</span><span class="p">,</span>
- <span class="s">&quot;third/forth/fith&quot;</span><span class="p">,</span>
- <span class="s">&quot;mypage.asp?i=1&amp;b=2&amp;c=3&quot;</span><span class="p">).</span><span class="n">setHttps</span><span class="p">(</span><span class="nb">true</span><span class="p">));</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-40'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-40'>#</a>
- </div>
- <p>Create child URLs from base URLs</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">URLBuilder</span> <span class="n">origurl</span> <span class="o">=</span> <span class="n">restClient</span><span class="p">.</span><span class="n">buildURL</span><span class="p">(</span><span class="s">&quot;myhost.net/&quot;</span><span class="p">,</span><span class="s">&quot;/homepage&quot;</span><span class="p">);</span>
- <span class="n">URLBuilder</span> <span class="n">newurl</span> <span class="o">=</span> <span class="n">origurl</span>
- <span class="p">.</span><span class="n">copy</span><span class="p">()</span>
- <span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="s">&quot;asdf/adf/reqotwoetiywer&quot;</span><span class="p">)</span>
- <span class="p">.</span><span class="n">setHttps</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-41'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-41'>#</a>
- </div>
- <p>Original URL: http://myhost.net/homepage</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span><span class="n">origurl</span><span class="p">);</span></pre></div>
- </div>
- </div>
- <div class='clearall'></div><div class='section' id='section-42'>
- <div class='docs'>
- <div class='octowrap'>
- <a class='octothorpe' href='#section-42'>#</a>
- </div>
- <p>Child URL: https://myhost.net/homepage/asdf/adf/reqotwoetiywer</p>
- </div>
- <div class='code'>
- <div class="highlight"><pre> <span class="n">pl</span><span class="p">(</span><span class="n">newurl</span><span class="p">);</span>
- <span class="p">}</span>
-
- <span class="n">private</span> <span class="k">static</span> <span class="kt">void</span> <span class="n">pl</span><span class="p">(</span><span class="n">Object</span> <span class="n">message</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">System</span><span class="p">.</span><span class="n">out</span><span class="p">.</span><span class="n">println</span><span class="p">(</span><span class="n">message</span><span class="p">);</span>
- <span class="p">}</span>
-<span class="p">}</span>
-
-</pre></div>
- </div>
- </div>
- <div class='clearall'></div>
-</div>
-</body>
View
186 org.touge.restclient/docs/pycco.css
@@ -1,186 +0,0 @@
-/*--------------------- Layout and Typography ----------------------------*/
-body {
- font-family: 'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif;
- font-size: 16px;
- line-height: 24px;
- color: #252519;
- margin: 0; padding: 0;
-}
-a {
- color: #261a3b;
-}
- a:visited {
- color: #261a3b;
- }
-p {
- margin: 0 0 15px 0;
-}
-h1, h2, h3, h4, h5, h6 {
- margin: 40px 0 15px 0;
-}
-h2, h3, h4, h5, h6 {
- margin-top: 0;
- }
-#container, div.section {
- position: relative;
-}
-#background {
- position: fixed;
- top: 0; left: 580px; right: 0; bottom: 0;
- background: #f5f5ff;
- border-left: 1px solid #e5e5ee;
- z-index: -1;
-}
-#jump_to, #jump_page {
- background: white;
- -webkit-box-shadow: 0 0 25px #777; -moz-box-shadow: 0 0 25px #777;
- -webkit-border-bottom-left-radius: 5px; -moz-border-radius-bottomleft: 5px;
- font: 10px Arial;
- text-transform: uppercase;
- cursor: pointer;
- text-align: right;
-}
-#jump_to, #jump_wrapper {
- position: fixed;
- right: 0; top: 0;
- padding: 5px 10px;
-}
- #jump_wrapper {
- padding: 0;
- display: none;
- }
- #jump_to:hover #jump_wrapper {
- display: block;
- }
- #jump_page {
- padding: 5px 0 3px;
- margin: 0 0 25px 25px;
- }
- #jump_page .source {
- display: block;
- padding: 5px 10px;
- text-decoration: none;
- border-top: 1px solid #eee;
- }
- #jump_page .source:hover {
- background: #f5f5ff;
- }
- #jump_page .source:first-child {
- }
-div.docs {
- float: left;
- max-width: 500px;
- min-width: 500px;
- min-height: 5px;
- padding: 10px 25px 1px 50px;
- vertical-align: top;
- text-align: left;
-}
- .docs pre {
- margin: 15px 0 15px;
- padding-left: 15px;
- }
- .docs p tt, .docs p code {
- background: #f8f8ff;
- border: 1px solid #dedede;
- font-size: 12px;
- padding: 0 0.2em;
- }
- .octowrap {
- position: relative;
- }
- .octothorpe {
- font: 12px Arial;
- text-decoration: none;
- color: #454545;
- position: absolute;
- top: 3px; left: -20px;
- padding: 1px 2px;
- opacity: 0;
- -webkit-transition: opacity 0.2s linear;
- }
- div.docs:hover .octothorpe {
- opacity: 1;
- }
-div.code {
- margin-left: 580px;
- padding: 14px 15px 16px 50px;
- vertical-align: top;
-}
- .code pre, .docs p code {
- font-size: 12px;
- }
- pre, tt, code {
- line-height: 18px;
- font-family: Monaco, Consolas, "Lucida Console", monospace;
- margin: 0; padding: 0;
- }
-div.clearall {
- clear: both;
-}
-
-
-/*---------------------- Syntax Highlighting -----------------------------*/
-td.linenos { background-color: #f0f0f0; padding-right: 10px; }
-span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; }
-body .hll { background-color: #ffffcc }
-body .c { color: #408080; font-style: italic } /* Comment */
-body .err { border: 1px solid #FF0000 } /* Error */
-body .k { color: #954121 } /* Keyword */
-body .o { color: #666666 } /* Operator */
-body .cm { color: #408080; font-style: italic } /* Comment.Multiline */
-body .cp { color: #BC7A00 } /* Comment.Preproc */
-body .c1 { color: #408080; font-style: italic } /* Comment.Single */
-body .cs { color: #408080; font-style: italic } /* Comment.Special */
-body .gd { color: #A00000 } /* Generic.Deleted */
-body .ge { font-style: italic } /* Generic.Emph */
-body .gr { color: #FF0000 } /* Generic.Error */
-body .gh { color: #000080; font-weight: bold } /* Generic.Heading */
-body .gi { color: #00A000 } /* Generic.Inserted */
-body .go { color: #808080 } /* Generic.Output */
-body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
-body .gs { font-weight: bold } /* Generic.Strong */
-body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
-body .gt { color: #0040D0 } /* Generic.Traceback */
-body .kc { color: #954121 } /* Keyword.Constant */
-body .kd { color: #954121; font-weight: bold } /* Keyword.Declaration */
-body .kn { color: #954121; font-weight: bold } /* Keyword.Namespace */
-body .kp { color: #954121 } /* Keyword.Pseudo */
-body .kr { color: #954121; font-weight: bold } /* Keyword.Reserved */
-body .kt { color: #B00040 } /* Keyword.Type */
-body .m { color: #666666 } /* Literal.Number */
-body .s { color: #219161 } /* Literal.String */
-body .na { color: #7D9029 } /* Name.Attribute */
-body .nb { color: #954121 } /* Name.Builtin */
-body .nc { color: #0000FF; font-weight: bold } /* Name.Class */
-body .no { color: #880000 } /* Name.Constant */
-body .nd { color: #AA22FF } /* Name.Decorator */
-body .ni { color: #999999; font-weight: bold } /* Name.Entity */
-body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
-body .nf { color: #0000FF } /* Name.Function */
-body .nl { color: #A0A000 } /* Name.Label */
-body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
-body .nt { color: #954121; font-weight: bold } /* Name.Tag */
-body .nv { color: #19469D } /* Name.Variable */
-body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
-body .w { color: #bbbbbb } /* Text.Whitespace */
-body .mf { color: #666666 } /* Literal.Number.Float */
-body .mh { color: #666666 } /* Literal.Number.Hex */
-body .mi { color: #666666 } /* Literal.Number.Integer */
-body .mo { color: #666666 } /* Literal.Number.Oct */
-body .sb { color: #219161 } /* Literal.String.Backtick */
-body .sc { color: #219161 } /* Literal.String.Char */
-body .sd { color: #219161; font-style: italic } /* Literal.String.Doc */
-body .s2 { color: #219161 } /* Literal.String.Double */
-body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
-body .sh { color: #219161 } /* Literal.String.Heredoc */
-body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
-body .sx { color: #954121 } /* Literal.String.Other */
-body .sr { color: #BB6688 } /* Literal.String.Regex */
-body .s1 { color: #219161 } /* Literal.String.Single */
-body .ss { color: #19469D } /* Literal.String.Symbol */
-body .bp { color: #954121 } /* Name.Builtin.Pseudo */
-body .vc { color: #19469D } /* Name.Variable.Class */
-body .vg { color: #19469D } /* Name.Variable.Global */
-body .vi { color: #19469D } /* Name.Variable.Instance */
-body .il { color: #666666 } /* Literal.Number.Integer.Long */
View
9 ...tclient/test/org/touge/restclient/test/Usage.java → ...t/org/touge/restclient/test/ReSTClient_usage.java
@@ -10,6 +10,8 @@
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
+import java.io.OutputStreamWriter;
+import java.io.PrintWriter;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
@@ -21,7 +23,7 @@
import org.touge.restclient.ReSTClient.URLBuilder;
// ### Examples of how to use ReSTClient.
-public class Usage {
+public class ReSTClient_usage {
public static void main(String[] args) throws IOException {
@@ -35,6 +37,9 @@ public static void main(String[] args) throws IOException {
//Another common thing is to POST a String to a server:
restClient.callPost("localhost", "my content");
+ //Print debug info to System.out
+ restClient.setDebugWriter(new PrintWriter(System.out));
+
//Getting more complex, we can specify a deserializer that will turn
//the server response into an Object our client wants. Here we use
//one of the few predefined deserializers.
@@ -56,6 +61,8 @@ public Double deserialize(InputStream input, int responseCode, Map<String, List<
}, null, null);
+ //Disable debug output
+ restClient.setDebugWriter(null);
//API allows for code that specifically checks for errors,
// or relies on exception handling.
Please sign in to comment.
Something went wrong with that request. Please try again.