You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2017/06/27 02:38:21 UTC
[07/19] incubator-juneau git commit: Clean up javadocs.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallException.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallException.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallException.java
index 097a6cf..b0a01d9 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallException.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallException.java
@@ -87,7 +87,7 @@ public final class RestCallException extends IOException {
* @param responseMsg The response message.
* @param method The HTTP method (for message purposes).
* @param url The HTTP URL (for message purposes).
- * @param response The reponse from the server.
+ * @param response The response from the server.
*/
public RestCallException(int responseCode, String responseMsg, String method, URI url, String response) {
super(format("HTTP method '%s' call to '%s' caused response code '%s,%s'.%nResponse: %n%s%n", method, url, responseCode, responseMsg, response));
@@ -100,7 +100,8 @@ public final class RestCallException extends IOException {
* Sets the server-side exception details.
*
* @param exceptionName The <code>Exception-Name:</code> header specifying the full name of the exception.
- * @param exceptionMessage The <code>Exception-Message:</code> header specifying the message returned by {@link Throwable#getMessage()}.
+ * @param exceptionMessage
+ * The <code>Exception-Message:</code> header specifying the message returned by {@link Throwable#getMessage()}.
* @param exceptionTrace The stack trace of the exception returned by {@link Throwable#printStackTrace()}.
* @return This object (for method chaining).
*/
@@ -116,6 +117,7 @@ public final class RestCallException extends IOException {
/**
* Tries to reconstruct and re-throw the server-side exception.
+ *
* <p>
* The exception is based on the following HTTP response headers:
* <ul>
@@ -123,8 +125,10 @@ public final class RestCallException extends IOException {
* <li><code>Exception-Message:</code> - The message returned by {@link Throwable#getMessage()}.
* <li><code>Exception-Trace:</code> - The stack trace of the exception returned by {@link Throwable#printStackTrace()}.
* </ul>
+ *
* <p>
* Does nothing if the server-side exception could not be reconstructed.
+ *
* <p>
* Currently only supports <code>Throwables</code> with either a public no-arg constructor
* or a public constructor that takes in a simple string message.
@@ -154,7 +158,7 @@ public final class RestCallException extends IOException {
/**
* Sets the HTTP response object that caused this exception.
*
- * @param httpResponse The HTTP respose object.
+ * @param httpResponse The HTTP response object.
* @return This object (for method chaining).
*/
protected RestCallException setHttpResponse(HttpResponse httpResponse) {
@@ -165,7 +169,9 @@ public final class RestCallException extends IOException {
/**
* Returns the HTTP response object that caused this exception.
*
- * @return The HTTP response object that caused this exception, or <jk>null</jk> if no response was created yet when the exception was thrown.
+ * @return
+ * The HTTP response object that caused this exception, or <jk>null</jk> if no response was created yet when the
+ * exception was thrown.
*/
public HttpResponse getHttpResponse() {
return this.httpResponse;
@@ -200,6 +206,7 @@ public final class RestCallException extends IOException {
/**
* Sets the inner cause for this exception.
+ *
* @param cause The inner cause.
* @return This object (for method chaining).
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallInterceptor.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallInterceptor.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallInterceptor.java
index ddaf90a..54f36b2 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallInterceptor.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallInterceptor.java
@@ -15,8 +15,9 @@ package org.apache.juneau.rest.client;
import org.apache.http.*;
/**
- * Used to intercept http connection responses to allow modification of that response before processing
- * and for listening for call lifecycle events.
+ * Used to intercept http connection responses to allow modification of that response before processing and for
+ * listening for call lifecycle events.
+ *
* <p>
* Useful if you want to prevent {@link RestCallException RestCallExceptions} from being thrown on error conditions.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallLogger.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallLogger.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallLogger.java
index a1621ac..4e2adb8 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallLogger.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCallLogger.java
@@ -22,19 +22,21 @@ import org.apache.http.client.methods.*;
import org.apache.http.util.*;
/**
- * Specialized interceptor for logging calls to a log file.
+ * Specialized intercepter for logging calls to a log file.
+ *
* <p>
- * Causes a log entry to be created that shows all the request and response headers and content
- * at the end of the request.
+ * Causes a log entry to be created that shows all the request and response headers and content at the end of the
+ * request.
+ *
* <p>
- * Use the {@link RestClientBuilder#logTo(Level, Logger)} and {@link RestCall#logTo(Level, Logger)}
- * <p>
- * methods to create instances of this class.
+ * Use the {@link RestClientBuilder#logTo(Level, Logger)} and {@link RestCall#logTo(Level, Logger)} methods to create
+ * instances of this class.
*/
public class RestCallLogger extends RestCallInterceptor {
/**
* Default HTTP request logger.
+ * <p>
* Logs outgoing HTTP requests to the <code>org.apache.juneau.rest.client</code> logger at <jsf>WARNING</jsf> level.
*/
public static final RestCallLogger DEFAULT = new RestCallLogger(Level.WARNING, Logger.getLogger("org.apache.juneau.rest.client"));
@@ -68,9 +70,9 @@ public class RestCallLogger extends RestCallInterceptor {
public void onRetry(RestCall restCall, int statusCode, HttpRequest req, HttpResponse res, Exception ex) {
if (log.isLoggable(level)) {
if (ex == null)
- log.log(level, format("Call to {0} returned {1}. Will retry.", req.getRequestLine().getUri(), statusCode)); //$NON-NLS-1$
+ log.log(level, format("Call to {0} returned {1}. Will retry.", req.getRequestLine().getUri(), statusCode));
else
- log.log(level, format("Call to {0} caused exception {1}. Will retry.", req.getRequestLine().getUri(), ex.getLocalizedMessage()), ex); //$NON-NLS-1$
+ log.log(level, format("Call to {0} caused exception {1}. Will retry.", req.getRequestLine().getUri(), ex.getLocalizedMessage()), ex);
}
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
index 5f8d1e9..72f0f0f 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java
@@ -42,16 +42,23 @@ import org.apache.juneau.urlencoding.*;
*
* <h6 class='topic'>Features</h6>
* <ul class='spaced-list'>
- * <li>Convert POJOs directly to HTTP request message bodies using {@link Serializer} class.
- * <li>Convert HTTP response message bodies directly to POJOs using {@link Parser} class.
- * <li>Fluent interface.
- * <li>Thread safe.
- * <li>API for interacting with remoteable services.
+ * <li>
+ * Convert POJOs directly to HTTP request message bodies using {@link Serializer} class.
+ * <li>
+ * Convert HTTP response message bodies directly to POJOs using {@link Parser} class.
+ * <li>
+ * Fluent interface.
+ * <li>
+ * Thread safe.
+ * <li>
+ * API for interacting with remoteable services.
* </ul>
*
* <h5 class='section'>Additional information:</h5>
* <ul>
- * <li><a class="doclink" href="package-summary.html#RestClient">org.apache.juneau.rest.client > REST client API</a> for more information and code examples.
+ * <li>
+ * <a class="doclink" href="package-summary.html#RestClient">org.apache.juneau.rest.client > REST client API</a>
+ * for more information and code examples.
* </ul>
*/
@SuppressWarnings("rawtypes")
@@ -76,7 +83,7 @@ public class RestClient extends CoreObject {
final int retries;
final long retryInterval;
final boolean debug;
- final RestCallInterceptor[] interceptors;
+ final RestCallInterceptor[] intercepters;
// This is lazy-created.
private volatile ExecutorService executorService;
@@ -92,7 +99,7 @@ public class RestClient extends CoreObject {
UrlEncodingSerializer urlEncodingSerializer,
PartSerializer partSerializer,
Map<String,String> headers,
- List<RestCallInterceptor> interceptors,
+ List<RestCallInterceptor> intercepters,
String rootUri,
RetryOn retryOn,
int retries,
@@ -117,11 +124,11 @@ public class RestClient extends CoreObject {
this.retryInterval = retryInterval;
this.debug = debug;
- List<RestCallInterceptor> l = new ArrayList<RestCallInterceptor>(interceptors);
+ List<RestCallInterceptor> l = new ArrayList<RestCallInterceptor>(intercepters);
if (debug)
l.add(RestCallLogger.DEFAULT);
- this.interceptors = l.toArray(new RestCallInterceptor[l.size()]);
+ this.intercepters = l.toArray(new RestCallInterceptor[l.size()]);
if (Boolean.getBoolean("org.apache.juneau.rest.client.RestClient.trackLifecycle"))
creationStack = Thread.currentThread().getStackTrace();
@@ -134,6 +141,8 @@ public class RestClient extends CoreObject {
/**
* Calls {@link CloseableHttpClient#close()} on the underlying {@link CloseableHttpClient}.
+ *
+ * <p>
* It's good practice to call this method after the client is no longer used.
*
* @throws IOException
@@ -165,6 +174,8 @@ public class RestClient extends CoreObject {
/**
* Execute the specified request.
+ *
+ * <p>
* Subclasses can override this method to provide specialized handling.
*
* @param req The HTTP request.
@@ -178,9 +189,12 @@ public class RestClient extends CoreObject {
/**
* Perform a <code>GET</code> request against the specified URL.
*
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException If any authentication errors occurred.
*/
public RestCall doGet(Object url) throws RestCallException {
@@ -190,16 +204,25 @@ public class RestClient extends CoreObject {
/**
* Perform a <code>PUT</code> request against the specified URL.
*
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @param o The object to serialize and transmit to the URL as the body of the request.
- * Can be of the following types:
- * <ul class='spaced-list'>
- * <li>{@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
- * <li>{@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
- * <li>{@link Object} - POJO to be converted to text using the {@link Serializer} registered with the {@link RestClient}.
- * <li>{@link HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
- * </ul>
- * @return A {@link RestCall} object that can be further tailored before executing the request
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @param o
+ * The object to serialize and transmit to the URL as the body of the request.
+ * Can be of the following types:
+ * <ul class='spaced-list'>
+ * <li>
+ * {@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
+ * <li>
+ * {@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
+ * <li>
+ * {@link Object} - POJO to be converted to text using the {@link Serializer} registered with the
+ * {@link RestClient}.
+ * <li>
+ * {@link HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
+ * </ul>
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request
* and getting the response as a parsed object.
* @throws RestCallException If any authentication errors occurred.
*/
@@ -209,13 +232,17 @@ public class RestClient extends CoreObject {
/**
* Same as {@link #doPut(Object, Object)} but don't specify the input yet.
+ *
* <p>
* You must call either {@link RestCall#input(Object)} or {@link RestCall#formData(String, Object)}
* to set the contents on the result object.
*
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException
*/
public RestCall doPut(Object url) throws RestCallException {
@@ -225,17 +252,25 @@ public class RestClient extends CoreObject {
/**
* Perform a <code>POST</code> request against the specified URL.
*
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @param o The object to serialize and transmit to the URL as the body of the request.
- * Can be of the following types:
- * <ul class='spaced-list'>
- * <li>{@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
- * <li>{@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
- * <li>{@link Object} - POJO to be converted to text using the {@link Serializer} registered with the {@link RestClient}.
- * <li>{@link HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
- * </ul>
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @param o
+ * The object to serialize and transmit to the URL as the body of the request.
+ * Can be of the following types:
+ * <ul class='spaced-list'>
+ * <li>
+ * {@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
+ * <li>
+ * {@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
+ * <li>
+ * {@link Object} - POJO to be converted to text using the {@link Serializer} registered with the {@link RestClient}.
+ * <li>
+ * {@link HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
+ * </ul>
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException If any authentication errors occurred.
*/
public RestCall doPost(Object url, Object o) throws RestCallException {
@@ -244,13 +279,17 @@ public class RestClient extends CoreObject {
/**
* Same as {@link #doPost(Object, Object)} but don't specify the input yet.
+ *
* <p>
- * You must call either {@link RestCall#input(Object)} or {@link RestCall#formData(String, Object)}
- * to set the contents on the result object.
+ * You must call either {@link RestCall#input(Object)} or {@link RestCall#formData(String, Object)} to set the
+ * contents on the result object.
*
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException
*/
public RestCall doPost(Object url) throws RestCallException {
@@ -260,9 +299,12 @@ public class RestClient extends CoreObject {
/**
* Perform a <code>DELETE</code> request against the specified URL.
*
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException If any authentication errors occurred.
*/
public RestCall doDelete(Object url) throws RestCallException {
@@ -272,9 +314,12 @@ public class RestClient extends CoreObject {
/**
* Perform an <code>OPTIONS</code> request against the specified URL.
*
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException If any authentication errors occurred.
*/
public RestCall doOptions(Object url) throws RestCallException {
@@ -282,13 +327,18 @@ public class RestClient extends CoreObject {
}
/**
- * Perform a <code>POST</code> request with a content type of <code>application/x-www-form-urlencoded</code> against the specified URL.
+ * Perform a <code>POST</code> request with a content type of <code>application/x-www-form-urlencoded</code>
+ * against the specified URL.
*
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @param o The object to serialize and transmit to the URL as the body of the request, serialized as a form post
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @param o
+ * The object to serialize and transmit to the URL as the body of the request, serialized as a form post
* using the {@link UrlEncodingSerializer#DEFAULT} serializer.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException If any authentication errors occurred.
*/
public RestCall doFormPost(Object url, Object o) throws RestCallException {
@@ -298,22 +348,28 @@ public class RestClient extends CoreObject {
/**
* Performs a REST call where the entire call is specified in a simple string.
+ *
* <p>
* This method is useful for performing callbacks when the target of a callback is passed in
* on an initial request, for example to signal when a long-running process has completed.
+ *
* <p>
* The call string can be any of the following formats:
* <ul class='spaced-list'>
- * <li><js>"[method] [url]"</js> - e.g. <js>"GET http://localhost/callback"</js>
- * <li><js>"[method] [url] [payload]"</js> - e.g. <js>"POST http://localhost/callback some text payload"</js>
- * <li><js>"[method] [headers] [url] [payload]"</js> - e.g. <js>"POST {'Content-Type':'text/json'} http://localhost/callback {'some':'json'}"</js>
+ * <li>
+ * <js>"[method] [url]"</js> - e.g. <js>"GET http://localhost/callback"</js>
+ * <li>
+ * <js>"[method] [url] [payload]"</js> - e.g. <js>"POST http://localhost/callback some text payload"</js>
+ * <li>
+ * <js>"[method] [headers] [url] [payload]"</js> - e.g. <js>"POST {'Content-Type':'text/json'} http://localhost/callback {'some':'json'}"</js>
* </ul>
* <p>
* The payload will always be sent using a simple {@link StringEntity}.
*
* @param callString The call string.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException
*/
public RestCall doCallback(String callString) throws RestCallException {
@@ -367,19 +423,29 @@ public class RestClient extends CoreObject {
* Perform a generic REST call.
*
* @param method The HTTP method.
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
- * @param content The HTTP body content.
- * Can be of the following types:
- * <ul class='spaced-list'>
- * <li>{@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
- * <li>{@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
- * <li>{@link Object} - POJO to be converted to text using the {@link Serializer} registered with the {@link RestClient}.
- * <li>{@link HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
- * <li>{@link NameValuePairs} - Converted to a URL-encoded FORM post.
- * </ul>
- * This parameter is IGNORED if {@link HttpMethod#hasContent()} is <jk>false</jk>.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @param content
+ * The HTTP body content.
+ * Can be of the following types:
+ * <ul class='spaced-list'>
+ * <li>
+ * {@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
+ * <li>
+ * {@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
+ * <li>
+ * {@link Object} - POJO to be converted to text using the {@link Serializer} registered with the
+ * {@link RestClient}.
+ * <li>
+ * {@link HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
+ * <li>
+ * {@link NameValuePairs} - Converted to a URL-encoded FORM post.
+ * </ul>
+ * This parameter is IGNORED if {@link HttpMethod#hasContent()} is <jk>false</jk>.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException If any authentication errors occurred.
*/
public RestCall doCall(HttpMethod method, Object url, Object content) throws RestCallException {
@@ -393,10 +459,13 @@ public class RestClient extends CoreObject {
* Perform a generic REST call.
*
* @param method The method name (e.g. <js>"GET"</js>, <js>"OPTIONS"</js>).
- * @param url The URL of the remote REST resource. Can be any of the following: {@link String}, {@link URI}, {@link URL}.
+ * @param url
+ * The URL of the remote REST resource.
+ * Can be any of the following: {@link String}, {@link URI}, {@link URL}.
* @param hasContent Boolean flag indicating if the specified request has content associated with it.
- * @return A {@link RestCall} object that can be further tailored before executing the request
- * and getting the response as a parsed object.
+ * @return
+ * A {@link RestCall} object that can be further tailored before executing the request and getting the response
+ * as a parsed object.
* @throws RestCallException If any authentication errors occurred.
*/
public RestCall doCall(String method, Object url, boolean hasContent) throws RestCallException {
@@ -445,6 +514,7 @@ public class RestClient extends CoreObject {
/**
* Create a new proxy interface against a REST interface.
+ *
* <p>
* The URL to the REST interface is based on the following values:
* <ul>
@@ -452,6 +522,7 @@ public class RestClient extends CoreObject {
* <li>The {@link RestClientBuilder#rootUrl(Object) rootUrl} on the client (<code>root-url</code>).
* <li>The fully-qualified class name of the interface (<code>class-name</code>).
* </ul>
+ *
* <p>
* The URL calculation is as follows:
* <ul>
@@ -459,8 +530,10 @@ public class RestClient extends CoreObject {
* <li><code>root-url/remoteable-path</code> - If remoteable path is relative and root-url has been specified.
* <li><code>root-url/class-name</code> - If remoteable path is not specified.
* </ul>
+ *
* <p>
* If the information is not available to resolve to an absolute URL, a {@link RemoteableMetadataException} is thrown.
+ *
* <p>
* Examples:
* <p class='bcode'>
@@ -491,11 +564,14 @@ public class RestClient extends CoreObject {
* .build()
* .getRemoteableProxy(MyInterface3.<jk>class</jk>);
* </p>
+ *
* <h5 class='section'>Notes:</h5>
* <ul>
- * <li>If you plan on using your proxy in a multi-threaded environment, you'll want to use an underlying
- * pooling client connection manager. The easiest way to do this is to use the {@link RestClientBuilder#pooled()}
- * method. If you don't do this, you may end up seeing "Connection still allocated" exceptions.
+ * <li>
+ * If you plan on using your proxy in a multi-threaded environment, you'll want to use an underlying
+ * pooling client connection manager.
+ * The easiest way to do this is to use the {@link RestClientBuilder#pooled()} method.
+ * If you don't do this, you may end up seeing "Connection still allocated" exceptions.
* </ul>
*
* @param interfaceClass The interface to create a proxy for.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClientBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClientBuilder.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClientBuilder.java
index 529a068..66a0f65 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClientBuilder.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClientBuilder.java
@@ -69,7 +69,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
private Map<String,String> headers = new TreeMap<String,String>(String.CASE_INSENSITIVE_ORDER);
- private List<RestCallInterceptor> interceptors = new ArrayList<RestCallInterceptor>();
+ private List<RestCallInterceptor> intercepters = new ArrayList<RestCallInterceptor>();
private String rootUrl;
private SSLOpts sslOpts;
@@ -90,6 +90,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Constructor, default settings.
+ *
* <p>
* Shortcut for calling <code><jk>new</jk> RestClientBuilder().serializer(s).parser(p);</code>
*
@@ -104,6 +105,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Constructor, default settings.
+ *
* <p>
* Shortcut for calling <code><jk>new</jk> RestClientBuilder().serializer(s).parser(p);</code>
*
@@ -118,6 +120,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Constructor.
+ *
* @param propertyStore The initial configuration settings for this builder.
*/
public RestClientBuilder(PropertyStore propertyStore) {
@@ -153,7 +156,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
pf = partSerializerClass.newInstance();
}
- return new RestClient(propertyStore, httpClient, keepHttpClientOpen, s, p, us, pf, headers, interceptors, rootUrl, retryOn, retries, retryInterval, debug, executorService, executorServiceShutdownOnClose);
+ return new RestClient(propertyStore, httpClient, keepHttpClientOpen, s, p, us, pf, headers, intercepters, rootUrl, retryOn, retries, retryInterval, debug, executorService, executorServiceShutdownOnClose);
} catch (Exception e) {
throw new RuntimeException(e);
}
@@ -161,15 +164,18 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Creates an instance of an {@link HttpClient} to be used to handle all HTTP communications with the target server.
+ *
* <p>
* This HTTP client is used when the HTTP client is not specified through one of the constructors or the
- * {@link #httpClient(CloseableHttpClient, boolean)} method.
+ * {@link #httpClient(CloseableHttpClient, boolean)} method.
+ *
* <p>
- * Subclasses can override this method to provide specially-configured HTTP clients to handle
- * stuff such as SSL/TLS certificate handling, authentication, etc.
+ * Subclasses can override this method to provide specially-configured HTTP clients to handle stuff such as
+ * SSL/TLS certificate handling, authentication, etc.
+ *
* <p>
- * The default implementation returns an instance of {@link HttpClient} using the client builder
- * returned by {@link #createHttpClientBuilder()}.
+ * The default implementation returns an instance of {@link HttpClient} using the client builder returned by
+ * {@link #createHttpClientBuilder()}.
*
* @return The HTTP client to use.
* @throws Exception
@@ -182,10 +188,11 @@ public class RestClientBuilder extends CoreObjectBuilder {
}
/**
- * Creates an instance of an {@link HttpClientBuilder} to be used to create
- * the {@link HttpClient}.
+ * Creates an instance of an {@link HttpClientBuilder} to be used to create the {@link HttpClient}.
+ *
* <p>
* Subclasses can override this method to provide their own client builder.
+ *
* <p>
* The predefined method returns an {@link HttpClientBuilder} with the following settings:
* <ul>
@@ -203,8 +210,10 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Creates the {@link HttpClientConnectionManager} returned by {@link #createConnectionManager()}.
+ *
* <p>
* Subclasses can override this method to provide their own connection manager.
+ *
* <p>
* The default implementation returns an instance of a {@link PoolingHttpClientConnectionManager}.
*
@@ -245,13 +254,16 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Set a root URL for this client.
+ *
* <p>
* When set, URL strings passed in through the various rest call methods (e.g. {@link RestClient#doGet(Object)}
- * will be prefixed with the specified root.
+ * will be prefixed with the specified root.
* This root URL is ignored on those methods if you pass in a {@link URL}, {@link URI}, or an absolute URL string.
*
- * @param rootUrl The root URL to prefix to relative URL strings. Trailing slashes are trimmed.
- * Usually a <code>String</code> but you can also pass in <code>URI</code> and <code>URL</code> objects as well.
+ * @param rootUrl
+ * The root URL to prefix to relative URL strings.
+ * Trailing slashes are trimmed.
+ * Usually a <code>String</code> but you can also pass in <code>URI</code> and <code>URL</code> objects as well.
* @return This object (for method chaining).
*/
public RestClientBuilder rootUrl(Object rootUrl) {
@@ -265,8 +277,10 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Enable SSL support on this client.
*
- * @param opts The SSL configuration options. See {@link SSLOpts} for details.
- * This method is a no-op if <code>sslConfig</code> is <jk>null</jk>.
+ * @param opts
+ * The SSL configuration options.
+ * See {@link SSLOpts} for details.
+ * This method is a no-op if <code>sslConfig</code> is <jk>null</jk>.
* @return This object (for method chaining).
* @throws KeyStoreException
* @throws NoSuchAlgorithmException
@@ -278,6 +292,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Enable LAX SSL support.
+ *
* <p>
* Certificate chain validation and hostname verification is disabled.
*
@@ -300,25 +315,25 @@ public class RestClientBuilder extends CoreObjectBuilder {
}
/**
- * Adds an interceptor that gets called immediately after a connection is made.
+ * Adds an intercepter that gets called immediately after a connection is made.
*
- * @param interceptor The interceptor.
+ * @param intercepter The intercepter.
* @return This object (for method chaining).
*/
- public RestClientBuilder interceptor(RestCallInterceptor interceptor) {
- interceptors.add(interceptor);
+ public RestClientBuilder intercepter(RestCallInterceptor intercepter) {
+ intercepters.add(intercepter);
return this;
}
/**
- * Adds a {@link RestCallLogger} to the list of interceptors on this class.
+ * Adds a {@link RestCallLogger} to the list of intercepters on this class.
*
- * @param level The log level to log messsages at.
+ * @param level The log level to log messages at.
* @param log The logger to log messages to.
* @return This object (for method chaining).
*/
public RestClientBuilder logTo(Level level, Logger log) {
- interceptor(new RestCallLogger(level, log));
+ intercepter(new RestCallLogger(level, log));
return this;
}
@@ -327,8 +342,9 @@ public class RestClientBuilder extends CoreObjectBuilder {
*
* @param retries The number of retries to attempt.
* @param interval The time in milliseconds between attempts.
- * @param retryOn Optional object used for determining whether a retry should be attempted.
- * If <jk>null</jk>, uses {@link RetryOn#DEFAULT}.
+ * @param retryOn
+ * Optional object used for determining whether a retry should be attempted.
+ * If <jk>null</jk>, uses {@link RetryOn#DEFAULT}.
* @return This object (for method chaining).
*/
public RestClientBuilder retryable(int retries, long interval, RetryOn retryOn) {
@@ -340,7 +356,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* When called, the {@link #createConnectionManager()} method will return a {@link PoolingHttpClientConnectionManager}
- * instead of a {@link BasicHttpClientConnectionManager}.
+ * instead of a {@link BasicHttpClientConnectionManager}.
*
* @return This object (for method chaining).
*/
@@ -361,8 +377,8 @@ public class RestClientBuilder extends CoreObjectBuilder {
}
/**
- * Same as {@link #serializer(Serializer)}, except takes in a serializer class that
- * will be instantiated through a no-arg constructor.
+ * Same as {@link #serializer(Serializer)}, except takes in a serializer class that will be instantiated through a
+ * no-arg constructor.
*
* @param serializerClass The serializer class.
* @return This object (for method chaining).
@@ -384,8 +400,8 @@ public class RestClientBuilder extends CoreObjectBuilder {
}
/**
- * Same as {@link #parser(Parser)}, except takes in a parser class that
- * will be instantiated through a no-arg constructor.
+ * Same as {@link #parser(Parser)}, except takes in a parser class that will be instantiated through a no-arg
+ * constructor.
*
* @param parserClass The parser class.
* @return This object (for method chaining).
@@ -411,7 +427,8 @@ public class RestClientBuilder extends CoreObjectBuilder {
* Sets the part formatter to use for converting POJOs to headers, query parameters, form-data parameters, and
* path variables.
*
- * @param partSerializerClass The part serializer class.
+ * @param partSerializerClass
+ * The part serializer class.
* The class must have a no-arg constructor.
* @return This object (for method chaining).
*/
@@ -453,6 +470,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Defines the executor service to use when calling future methods on the {@link RestCall} class.
+ *
* <p>
* This executor service is used to create {@link Future} objects on the following methods:
* <ul>
@@ -461,6 +479,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
* <li>{@link RestCall#getResponseFuture(Type,Type...)}
* <li>{@link RestCall#getResponseAsString()}
* </ul>
+ *
* <p>
* The default executor service is a single-threaded {@link ThreadPoolExecutor} with a 30 second timeout
* and a queue size of 10.
@@ -494,8 +513,10 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Accept</code> request header.
+ *
* <p>
- * This overrides the media type specified on the parser, but is overridden by calling <code>header(<js>"Accept"</js>, value);</code>
+ * This overrides the media type specified on the parser, but is overridden by calling
+ * <code>header(<js>"Accept"</js>, value);</code>
*
* @param value The new header value.
* @return This object (for method chaining).
@@ -506,6 +527,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Accept-Charset</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Accept-Charset"</js>, value);</code>
*
@@ -518,6 +540,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Accept-Encoding</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Accept-Encoding"</js>, value);</code>
*
@@ -530,6 +553,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Accept-Language</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Accept-Language"</js>, value);</code>
*
@@ -542,6 +566,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Authorization</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Authorization"</js>, value);</code>
*
@@ -554,6 +579,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Cache-Control</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Cache-Control"</js>, value);</code>
*
@@ -566,6 +592,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Connection</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Connection"</js>, value);</code>
*
@@ -578,6 +605,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Content-Length</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Content-Length"</js>, value);</code>
*
@@ -590,8 +618,10 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Content-Type</code> request header.
+ *
* <p>
- * This overrides the media type specified on the serializer, but is overridden by calling <code>header(<js>"Content-Type"</js>, value);</code>
+ * This overrides the media type specified on the serializer, but is overridden by calling
+ * <code>header(<js>"Content-Type"</js>, value);</code>
*
* @param value The new header value.
* @return This object (for method chaining).
@@ -602,6 +632,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Date</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Date"</js>, value);</code>
*
@@ -614,6 +645,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Expect</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Expect"</js>, value);</code>
*
@@ -626,6 +658,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Forwarded</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Forwarded"</js>, value);</code>
*
@@ -638,6 +671,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>From</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"From"</js>, value);</code>
*
@@ -650,6 +684,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Host</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Host"</js>, value);</code>
*
@@ -662,6 +697,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>If-Match</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"If-Match"</js>, value);</code>
*
@@ -674,6 +710,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>If-Modified-Since</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"If-Modified-Since"</js>, value);</code>
*
@@ -686,6 +723,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>If-None-Match</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"If-None-Match"</js>, value);</code>
*
@@ -698,6 +736,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>If-Range</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"If-Range"</js>, value);</code>
*
@@ -710,6 +749,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>If-Unmodified-Since</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"If-Unmodified-Since"</js>, value);</code>
*
@@ -722,6 +762,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Max-Forwards</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Max-Forwards"</js>, value);</code>
*
@@ -734,6 +775,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Origin</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Origin"</js>, value);</code>
*
@@ -746,6 +788,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Pragma</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Pragma"</js>, value);</code>
*
@@ -758,6 +801,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Proxy-Authorization</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Proxy-Authorization"</js>, value);</code>
*
@@ -770,6 +814,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Range</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Range"</js>, value);</code>
*
@@ -782,6 +827,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Referer</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Referer"</js>, value);</code>
*
@@ -794,6 +840,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>TE</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"TE"</js>, value);</code>
*
@@ -806,6 +853,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>User-Agent</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"User-Agent"</js>, value);</code>
*
@@ -818,6 +866,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Upgrade</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Upgrade"</js>, value);</code>
*
@@ -830,6 +879,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Via</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Via"</js>, value);</code>
*
@@ -842,6 +892,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the value for the <code>Warning</code> request header.
+ *
* <p>
* This is a shortcut for calling <code>header(<js>"Warning"</js>, value);</code>
*
@@ -1116,10 +1167,11 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* When called, <code>No-Trace: true</code> is added to requests.
+ *
* <p>
* This gives the opportunity for the servlet to not log errors on invalid requests.
- * This is useful for testing purposes when you don't want your log file to show lots
- * of errors that are simply the results of testing.
+ * This is useful for testing purposes when you don't want your log file to show lots of errors that are simply the
+ * results of testing.
*
* @return This object (for method chaining).
*/
@@ -1129,10 +1181,10 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Sets the {@link UonSerializerContext#UON_paramFormat} property on the URL-encoding serializers in this group.
+ *
* <p>
- * This overrides the behavior of the URL-encoding serializer to quote and escape characters
- * in query names and values that may be confused for UON notation (e.g. <js>"'(foo=123)'"</js>, <js>"'@(1,2,3)'"</js>).
- * <p>
+ * This overrides the behavior of the URL-encoding serializer to quote and escape characters in query names and
+ * values that may be confused for UON notation (e.g. <js>"'(foo=123)'"</js>, <js>"'@(1,2,3)'"</js>).
*
* @param value The new value for this property.
* @return This object (for method chaining).
@@ -1145,11 +1197,14 @@ public class RestClientBuilder extends CoreObjectBuilder {
/**
* Shortcut for calling <code>paramFormat(<js>"PLAINTEXT"</js>)</code>.
+ *
* <p>
- * The default behavior is to serialize part values (query parameters, form data, headers, path variables) in UON notation.
+ * The default behavior is to serialize part values (query parameters, form data, headers, path variables) in UON
+ * notation.
* Calling this method forces plain-text to be used instead.
+ *
* <p>
- * Specifially, UON notation has the following effects:
+ * Specifically, UON notation has the following effects:
* <ul>
* <li>Boolean strings (<js>"true"</js>/<js>"false"</js>) and numeric values (<js>"123"</js>) will be
* quoted (<js>"'true'"</js>, <js>"'false'"</js>, <js>"'123'"</js>.
@@ -1158,7 +1213,7 @@ public class RestClientBuilder extends CoreObjectBuilder {
* <js>"'(foo=bar~'baz~')'"</js>.
* </ul>
* <p>
- * The downside to using plain text part serialization is that you cannot serialize arbitrary POJOs.
+ * The down-side to using plain text part serialization is that you cannot serialize arbitrary POJOs.
*
* @return This object (for method chaining).
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestRequestEntity.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestRequestEntity.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestRequestEntity.java
index 9e460ab..8767730 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestRequestEntity.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestRequestEntity.java
@@ -31,6 +31,7 @@ public final class RestRequestEntity extends BasicHttpEntity {
/**
* Constructor.
+ *
* @param input The POJO to serialize. Can also be a {@link Reader} or {@link InputStream}.
* @param serializer The serializer to use to serialize this response.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RetryOn.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RetryOn.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RetryOn.java
index 6d225b0..31e56af 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RetryOn.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RetryOn.java
@@ -16,10 +16,10 @@ import org.apache.http.*;
/**
* Used to determine whether a request should be retried based on the HTTP response code.
+ *
* <p>
- * Subclasses should override either the {@link #onCode(int)} method (if you only care about
- * the HTTP status code) or {@link #onResponse(HttpResponse)} (if you want full access to
- * the HTTP response object.
+ * Subclasses should override either the {@link #onCode(int)} method (if you only care about the HTTP status code)
+ * or {@link #onResponse(HttpResponse)} (if you want full access to the HTTP response object.
*/
public abstract class RetryOn {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SSLOpts.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SSLOpts.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SSLOpts.java
index 35ce572..0dc9676 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SSLOpts.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SSLOpts.java
@@ -41,8 +41,9 @@ public class SSLOpts {
/**
* Constructor.
*
- * @param protocols A comma-delimited list of supported SSL protocols.
- * If <jk>null</jk>, uses the value returned by {@link #getDefaultProtocols()}.
+ * @param protocols
+ * A comma-delimited list of supported SSL protocols.
+ * If <jk>null</jk>, uses the value returned by {@link #getDefaultProtocols()}.
* @param certValidate Certificate validation setting.
* @param hostVerify Host verification setting.
*/
@@ -54,14 +55,15 @@ public class SSLOpts {
}
/**
- * Returns the default list of SSL protocols to support when the <code>protocols</code>
- * parameter on the constructor is <jk>null</jk>.
+ * Returns the default list of SSL protocols to support when the <code>protocols</code> parameter on the constructor
+ * is <jk>null</jk>.
+ *
* <p>
- * The default value is <jk>"SSL_TLS,TLS,SSL"</js> unless overridden by one of the following
- * system properties:
+ * The default value is <jk>"SSL_TLS,TLS,SSL"</js> unless overridden by one of the following system properties:
* <ul>
* <li><js>"transport.client.protocol"</js>
* </ul>
+ *
* <p>
* Subclasses can override this method to provide their own logic for determining default supported protocols.
*
@@ -146,6 +148,7 @@ public class SSLOpts {
/**
* Certificate validation options.
+ *
* <p>
* Used as enum for {@link SSLOpts#getCertValidate()} property.
*/
@@ -165,6 +168,7 @@ public class SSLOpts {
/**
* Certificate host verification options.
+ *
* <p>
* Used as enum for {@link SSLOpts#getHostVerify()} property.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SimpleX509TrustManager.java
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SimpleX509TrustManager.java b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SimpleX509TrustManager.java
index 2da901f..d4a0671 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SimpleX509TrustManager.java
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/SimpleX509TrustManager.java
@@ -43,7 +43,7 @@ public final class SimpleX509TrustManager implements X509TrustManager {
return;
}
}
- throw new IllegalStateException("Couldn't find JRE's X509TrustManager"); //$NON-NLS-1$
+ throw new IllegalStateException("Couldn't find JRE's X509TrustManager");
}
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/package.html
----------------------------------------------------------------------
diff --git a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/package.html b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/package.html
index 5e5fe02..3881f3d 100644
--- a/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/package.html
+++ b/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/package.html
@@ -88,29 +88,38 @@
Juneau provides an HTTP client API that makes it extremely simple to connect to remote REST interfaces and
seemlessly send and receive serialized POJOs in requests and responses.
</p>
+
<h6 class='notes'>Features:</h6>
<ul class='notes'>
- <li>Converts POJOs directly to HTTP request message bodies using {@link org.apache.juneau.serializer.Serializer} classes.
- <li>Converts HTTP response message bodies directly to POJOs using {@link org.apache.juneau.parser.Parser} classes.
- <li>Exposes the full functionality of the Apache HttpClient API by exposing all methods defined on the
+ <li>
+ Converts POJOs directly to HTTP request message bodies using {@link org.apache.juneau.serializer.Serializer}
+ classes.
+ <li>
+ Converts HTTP response message bodies directly to POJOs using {@link org.apache.juneau.parser.Parser}
+ classes.
+ <li>
+ Exposes the full functionality of the Apache HttpClient API by exposing all methods defined on the
{@link org.apache.http.impl.client.HttpClientBuilder} class.
- <li>Provides various convenience methods for setting up common SSL and authentication methods.
- <li>Provides a fluent interface that allows you to make complex REST calls in a single line of code.
+ <li>
+ Provides various convenience methods for setting up common SSL and authentication methods.
+ <li>
+ Provides a fluent interface that allows you to make complex REST calls in a single line of code.
</ul>
<p>
The client API is designed to work as a thin layer on top of the proven Apache HttpClient API.
By leveraging the HttpClient library, details such as SSL certificate negotiation, proxies, encoding, etc...
- are all handled in Apache code.
+ are all handled in Apache code.
</p>
<p>
The Juneau client API prereq's Apache HttpClient 4.1.2+.
- At a mimimum, the following jars are required:
+ At a minimum, the following jars are required:
</p>
<ul>
<li><code>httpclient-4.5.jar</code>
<li><code>httpcore-4.4.1.jar</code>
<li><code>httpmime-4.5.jar</code>
</ul>
+
<h6 class='topic'>Example:</h6>
<p class='bcode'>
<jc>// Examples below use the Juneau Address Book resource example</jc>
@@ -204,8 +213,10 @@
<h6 class='notes'>Notes:</h6>
<ul class='notes'>
- <li><p>The {@link org.apache.juneau.rest.client.RestClient} class exposes all the builder methods on the Apache HttpClient {@link org.apache.http.impl.client.HttpClientBuilder} class.
- Use these methods to provide any customized HTTP client behavior..</p>
+ <li>
+ The {@link org.apache.juneau.rest.client.RestClient} class exposes all the builder methods on the Apache
+ HttpClient {@link org.apache.http.impl.client.HttpClientBuilder} class.
+ Use these methods to provide any customized HTTP client behavior.
</ul>
<!-- ======================================================================================================== -->
@@ -213,13 +224,15 @@
<h3 class='topic' onclick='toggle(this)'>1.1 - SSL Support</h3>
<div class='topic'>
<p>
- The simplest way to enable SSL support in the client is to use the {@link org.apache.juneau.rest.client.RestClientBuilder#enableSSL(SSLOpts)} method
- and one of the predefined {@link org.apache.juneau.rest.client.SSLOpts} instances:
+ The simplest way to enable SSL support in the client is to use the
+ {@link org.apache.juneau.rest.client.RestClientBuilder#enableSSL(SSLOpts)} method and one of the predefined
+ {@link org.apache.juneau.rest.client.SSLOpts} instances:
</p>
<ul>
<li>{@link org.apache.juneau.rest.client.SSLOpts#DEFAULT} - Normal certificate and hostname validation.
<li>{@link org.apache.juneau.rest.client.SSLOpts#LAX} - Allows for self-signed certificates.
</ul>
+
<h6 class='topic'>Example:</h6>
<p class='bcode'>
<jc>// Create a client that ignores self-signed or otherwise invalid certificates.</jc>
@@ -244,22 +257,27 @@
ctx.init(<jk>null</jk>, <jk>new</jk> TrustManager[] { tm }, <jk>null</jk>);
SSLConnectionSocketFactory sf = <jk>new</jk> SSLConnectionSocketFactory(ctx, hv);
builder.setSSLSocketFactory(sf);
- Registry<ConnectionSocketFactory> r = RegistryBuilder.<ConnectionSocketFactory><jsm>.create</jsm>().register(<js>"https"</js>, sf).build();
+ Registry<ConnectionSocketFactory> r = RegistryBuilder.<ConnectionSocketFactory><jsm>.create</jsm>()
+ .register(<js>"https"</js>, sf).build();
builder.setConnectionManager(<jk>new</jk> PoolingHttpClientConnectionManager(r));
}
</p>
<p>
- More complex SSL support can be enabled through the various {@link org.apache.http.impl.client.HttpClientBuilder} methods defined on the class.
+ More complex SSL support can be enabled through the various {@link org.apache.http.impl.client.HttpClientBuilder}
+ methods defined on the class.
</p>
<!-- ======================================================================================================== -->
<a id="SSLOpts"></a>
<h4 class='topic' onclick='toggle(this)'>1.1.1 - SSLOpts Bean</h4>
<div class='topic'>
- <p>
- The {@link org.apache.juneau.rest.client.SSLOpts} class itself is a bean that can be created by the parsers.
- For example, SSL options can be specified in a config file and retrieved as a bean using the {@link org.apache.juneau.ini.ConfigFile} class.
- </p>
+ <p>
+ The {@link org.apache.juneau.rest.client.SSLOpts} class itself is a bean that can be created by the
+ parsers.
+ For example, SSL options can be specified in a config file and retrieved as a bean using the
+ {@link org.apache.juneau.ini.ConfigFile} class.
+ </p>
+
<h6 class='figure'>Contents of <code>MyConfig.cfg</code></h6>
<p class='bcode'>
<jc>#================================================================================
@@ -269,6 +287,7 @@
url = https://myremotehost:9443
ssl = {certValidate:'LAX',hostVerify:'LAX'}
</p>
+
<h6 class='figure'>Code that reads an <code>SSLOpts</code> bean from the config file</h6>
<p class='bcode'>
<jc>// Read config file and set SSL options based on what's in that file.</jc>
@@ -289,20 +308,21 @@
<h4 class='topic' onclick='toggle(this)'>1.2.1 - BASIC Authentication</h4>
<div class='topic'>
<p>
- The {@link org.apache.juneau.rest.client.RestClientBuilder#basicAuth(String,int,String,String)} method can be used to quickly enable
- BASIC authentication support.
+ The {@link org.apache.juneau.rest.client.RestClientBuilder#basicAuth(String,int,String,String)} method
+ can be used to quickly enable BASIC authentication support.
</p>
+
<h6 class='topic'>Example:</h6>
<p class='bcode'>
<jc>// Create a client that performs BASIC authentication using the specified user/pw.</jc>
RestClient restClient = <jk>new</jk> RestClientBuilder()
.basicAuth(<jsf>HOST</jsf>, <jsf>PORT</jsf>, <jsf>USER</jsf>, <jsf>PW</jsf>)
.build();
- </p>
- <p>
- This is functionally equivalent to the following:
- </p>
- <p class='bcode'>
+ </p>
+ <p>
+ This is functionally equivalent to the following:
+ </p>
+ <p class='bcode'>
RestClientBuilder builder = <jk>new</jk> RestClientBuilder();
AuthScope scope = <jk>new</jk> AuthScope(<jsf>HOST</jsf>, <jsf>PORT</jsf>);
Credentials up = <jk>new</jk> UsernamePasswordCredentials(<jsf>USER</jsf>, <jsf>PW</jsf>);
@@ -317,15 +337,16 @@
<h4 class='topic' onclick='toggle(this)'>1.2.2 - FORM-based Authentication</h4>
<div class='topic'>
<p>
- The {@link org.apache.juneau.rest.client.RestClientBuilder} class does not itself provide FORM-based authentication since there
- is no standard way of providing such support.
+ The {@link org.apache.juneau.rest.client.RestClientBuilder} class does not itself provide FORM-based
+ authentication since there is no standard way of providing such support.
Typically, to perform FORM-based or other types of authentication, you'll want to create your own
- subclass of {@link org.apache.juneau.rest.client.RestClientBuilder} and override the {@link org.apache.juneau.rest.client.RestClientBuilder#createHttpClient()}
- method to provide an authenticated client.
+ subclass of {@link org.apache.juneau.rest.client.RestClientBuilder} and override the
+ {@link org.apache.juneau.rest.client.RestClientBuilder#createHttpClient()} method to provide an
+ authenticated client.
</p>
<p>
- The following example shows how the <code>JazzRestClient</code> class provides
- FORM-based authentication support.
+ The following example shows how the <code>JazzRestClient</code> class provides FORM-based
+ authentication support.
</p>
<p class='bcode'>
<jd>/**
@@ -405,8 +426,8 @@
<h4 class='topic' onclick='toggle(this)'>1.2.3 - OIDC Authentication</h4>
<div class='topic'>
<p>
- The following example shows how the <code>JazzRestClient</code> class provides
- OIDC authentication support.
+ The following example shows how the <code>JazzRestClient</code> class provides OIDC authentication
+ support.
</p>
<p class='bcode'>
<jd>/**
@@ -443,13 +464,15 @@
<jk>return</jk>;
<jk>if</jk> (code != <jsf>SC_UNAUTHORIZED</jsf>)
- <jk>throw new</jk> RestCallException(<js>"Unexpected response during OIDC authentication: "</js> + response.getStatusLine());
+ <jk>throw new</jk> RestCallException(<js>"Unexpected response during OIDC authentication: "</js>
+ + response.getStatusLine());
<jc>// x-jsa-authorization-redirect</jc>
String redirectUri = getHeader(response, <js>"X-JSA-AUTHORIZATION-REDIRECT"</js>);
<jk>if</jk> (redirectUri == <jk>null</jk>)
- <jk>throw new</jk> RestCallException(<js>"Expected a redirect URI during OIDC authentication: "</js> + response.getStatusLine());
+ <jk>throw new</jk> RestCallException(<js>"Expected a redirect URI during OIDC authentication: "</js>
+ + response.getStatusLine());
<jc>// Handle Bearer Challenge</jc>
HttpGet method = <jk>new</jk> HttpGet(redirectUri + <js>"&prompt=none"</js>);
@@ -460,12 +483,14 @@
code = response.getStatusLine().getStatusCode();
<jk>if</jk> (code != <jsf>SC_OK</jsf>)
- <jk>throw new</jk> RestCallException(<js>"Unexpected response during OIDC authentication phase 2: "</js> + response.getStatusLine());
+ <jk>throw new</jk> RestCallException(<js>"Unexpected response during OIDC authentication phase 2: "</js>
+ + response.getStatusLine());
String loginRequired = getHeader(response, <js>"X-JSA-LOGIN-REQUIRED"</js>);
<jk>if</jk> (! <js>"true"</js>.equals(loginRequired))
- <jk>throw new</jk> RestCallException(<js>"X-JSA-LOGIN-REQUIRED header not found on response during OIDC authentication phase 2: "</js> + response.getStatusLine());
+ <jk>throw new</jk> RestCallException(<js>"X-JSA-LOGIN-REQUIRED header not found on response during OIDC authentication phase 2: "</js>
+ + response.getStatusLine());
method = <jk>new</jk> HttpGet(redirectUri + <js>"&prompt=none"</js>);
@@ -475,7 +500,8 @@
code = response.getStatusLine().getStatusCode();
<jk>if</jk> (code != <jsf>SC_OK</jsf>)
- <jk>throw new</jk> RestCallException(<js>"Unexpected response during OIDC authentication phase 3: "</js> + response.getStatusLine());
+ <jk>throw new</jk> RestCallException(<js>"Unexpected response during OIDC authentication phase 3: "</js>
+ + response.getStatusLine());
<jc>// Handle JAS Challenge</jc>
method = <jk>new</jk> HttpGet(redirectUri);
@@ -486,15 +512,18 @@
code = response.getStatusLine().getStatusCode();
<jk>if</jk> (code != <jsf>SC_OK</jsf>)
- <jk>throw new</jk> RestCallException(<js>"Unexpected response during OIDC authentication phase 4: "</js> + response.getStatusLine());
+ <jk>throw new</jk> RestCallException(<js>"Unexpected response during OIDC authentication phase 4: "</js>
+ + response.getStatusLine());
<jf>cookie</jf> = getHeader(response, <js>"Set-Cookie"</js>);
Header[] defaultHeaders = <jk>new</jk> Header[] {
<jk>new</jk> BasicHeader(<js>"User-Agent"</js>, <js>"Jazz Native Client"</js>),
- <jk>new</jk> BasicHeader(<js>"X-com-ibm-team-configuration-versions"</js>, <js>"com.ibm.team.rtc=6.0.0,com.ibm.team.jazz.foundation=6.0"</js>),
+ <jk>new</jk> BasicHeader(<js>"X-com-ibm-team-configuration-versions"</js>,
+ <js>"com.ibm.team.rtc=6.0.0,com.ibm.team.jazz.foundation=6.0"</js>),
<jk>new</jk> BasicHeader(<js>"Accept"</js>, <js>"text/json"</js>),
- <jk>new</jk> BasicHeader(<js>"Authorization"</js>, <js>"Basic "</js> + StringUtils.<jsm>base64EncodeToString</jsm>(<jf>user</jf> + <js>":"</js> + <jf>pw</jf>)),
+ <jk>new</jk> BasicHeader(<js>"Authorization"</js>, <js>"Basic "</js>
+ + StringUtils.<jsm>base64EncodeToString</jsm>(<jf>user</jf> + <js>":"</js> + <jf>pw</jf>)),
<jk>new</jk> BasicHeader(<js>"Cookie"</js>, cookie)
};
@@ -507,11 +536,13 @@
<jk>private void</jk> addDefaultOidcHeaders(HttpRequestBase method) {
method.addHeader(<js>"User-Agent"</js>, <js>"Jazz Native Client"</js>);
- method.addHeader(<js>"X-com-ibm-team-configuration-versions"</js>, <js>"com.ibm.team.rtc=6.0.0,com.ibm.team.jazz.foundation=6.0"</js>);
+ method.addHeader(<js>"X-com-ibm-team-configuration-versions"</js>,
+ <js>"com.ibm.team.rtc=6.0.0,com.ibm.team.jazz.foundation=6.0"</js>);
method.addHeader(<js>"Accept"</js>, <js>"text/json"</js>);
<jk>if</jk> (<jf>cookie</jf> != <jk>null</jk>) {
- method.addHeader(<js>"Authorization"</js>, <js>"Basic "</js> + StringUtils.<jsm>base64EncodeToString</jsm>(<jf>user</jf> + <js>":"</js> + <jf>pw</jf>));
+ method.addHeader(<js>"Authorization"</js>, <js>"Basic "</js>
+ + StringUtils.<jsm>base64EncodeToString</jsm>(<jf>user</jf> + <js>":"</js> + <jf>pw</jf>));
method.addHeader(<js>"Cookie"</js>, cookie);
}
}
@@ -529,16 +560,18 @@
the results through the connection, and then fails after an HTTP 200 has already been sent.
</p>
<p>
- One common solution is to serialize some text at the end to indicate whether the long-running process succeeded (e.g. <js>"FAILED"</js> or <js>"SUCCEEDED"</js>).
+ One common solution is to serialize some text at the end to indicate whether the long-running process
+ succeeded (e.g. <js>"FAILED"</js> or <js>"SUCCEEDED"</js>).
</p>
<p>
- The {@link org.apache.juneau.rest.client.RestClient} class has convenience methods for scanning the response without
- interfering with the other methods used for retrieving output.
+ The {@link org.apache.juneau.rest.client.RestClient} class has convenience methods for scanning the
+ response without interfering with the other methods used for retrieving output.
</p>
<p>
- The following example shows how the {@link org.apache.juneau.rest.client.RestCall#successPattern(String)} method can be used
- to look for a SUCCESS message in the output:
+ The following example shows how the {@link org.apache.juneau.rest.client.RestCall#successPattern(String)}
+ method can be used to look for a SUCCESS message in the output:
</p>
+
<h6 class='topic'>Example:</h6>
<p class='bcode'>
<jc>// Throw a RestCallException if SUCCESS is not found in the output.</jc>
@@ -550,6 +583,7 @@
The {@link org.apache.juneau.rest.client.RestCall#failurePattern(String)} method does the opposite.
It throws an exception if a failure message is detected.
</p>
+
<h6 class='topic'>Example:</h6>
<p class='bcode'>
<jc>// Throw a RestCallException if FAILURE or ERROR is found in the output.</jc>
@@ -558,14 +592,16 @@
.run();
</p>
<p>
- These convenience methods are specialized methods that use the {@link org.apache.juneau.rest.client.RestCall#responsePattern(ResponsePattern)}
- method which uses regular expression matching against the response body.
+ These convenience methods are specialized methods that use the
+ {@link org.apache.juneau.rest.client.RestCall#responsePattern(ResponsePattern)} method which uses regular
+ expression matching against the response body.
This method can be used to search for arbitrary patterns in the response body.
</p>
<p>
- The following example shows how to use a response pattern finder to find and capture patterns for <js>"x=number"</js> and <js>"y=string"</js>
- from a response body.
+ The following example shows how to use a response pattern finder to find and capture patterns for
+ <js>"x=number"</js> and <js>"y=string"</js> from a response body.
</p>
+
<h6 class='topic'>Example:</h6>
<p class='bcode'>
<jk>final</jk> List<Number> xList = <jk>new</jk> ArrayList<Number>();
@@ -600,9 +636,11 @@
</p>
<p>
Using response patterns does not affect the functionality of any of the other methods
- used to retrieve the response such as {@link org.apache.juneau.rest.client.RestCall#getResponseAsString()} or {@link org.apache.juneau.rest.client.RestCall#getResponse(Class)}.<br>
+ used to retrieve the response such as {@link org.apache.juneau.rest.client.RestCall#getResponseAsString()}
+ or {@link org.apache.juneau.rest.client.RestCall#getResponse(Class)}.<br>
HOWEVER, if you want to retrieve the entire text of the response from inside the match methods,
- use {@link org.apache.juneau.rest.client.RestCall#getCapturedResponse()} since this method will not absorb the response for those other methods.
+ use {@link org.apache.juneau.rest.client.RestCall#getCapturedResponse()} since this method will not absorb
+ the response for those other methods.
</p>
</div>
@@ -611,15 +649,17 @@
<h3 class='topic' onclick='toggle(this)'>1.4 - Piping Response Output</h3>
<div class='topic'>
<p>
- The {@link org.apache.juneau.rest.client.RestCall} class provides various convenience <code>pipeTo()</code> methods
- to pipe output to output streams and writers.
+ The {@link org.apache.juneau.rest.client.RestCall} class provides various convenience <code>pipeTo()</code>
+ methods to pipe output to output streams and writers.
</p>
<p>
- If you want to pipe output without any intermediate buffering, you can use the {@link org.apache.juneau.rest.client.RestCall#byLines()} method.
+ If you want to pipe output without any intermediate buffering, you can use the
+ {@link org.apache.juneau.rest.client.RestCall#byLines()} method.
This will cause the output to be piped and flushed after every line.
This can be useful if you want to display the results in real-time from a long running process producing
- output on a REST call.
+ output on a REST call.
</p>
+
<h6 class='topic'>Example:</h6>
<p class='bcode'>
<jc>// Pipe output from REST call to System.out in real-time.</jc>
@@ -636,9 +676,10 @@
made from the client.
</p>
<p>
- Under-the-covers, this is simply a shortcut for adding the {@link org.apache.juneau.rest.client.RestCallLogger#DEFAULT} interceptor
- to the client. This causes the following output to be generated by the Java <code>org.apache.juneau.rest.client</code> logger at <jsf>WARNING</jsf>
- level:
+ Under-the-covers, this is simply a shortcut for adding the {@link org.apache.juneau.rest.client.RestCallLogger#DEFAULT}
+ intercepter to the client.
+ This causes the following output to be generated by the Java <code>org.apache.juneau.rest.client</code>
+ logger at <jsf>WARNING</jsf> level:
</p>
<p class='bcode'>
=== HTTP Call (outgoing) =======================================================
@@ -663,7 +704,8 @@
=== END ========================================================================
</p>
<p>
- This setting also causes a <code>Debug: true</code> header value to trigger logging of the request on the server side as well.
+ This setting also causes a <code>Debug: true</code> header value to trigger logging of the request on the
+ server side as well.
</p>
<p class='bcode'>
=== HTTP Request (incoming) ====================================================
@@ -689,10 +731,11 @@
<h3 class='topic' onclick='toggle(this)'>1.6 - Logging</h3>
<div class='topic'>
<p>
- Use the {@link org.apache.juneau.rest.client.RestClientBuilder#logTo(Level,Logger)} and {@link org.apache.juneau.rest.client.RestCall#logTo(Level,Logger)} methods
- to log HTTP calls.
+ Use the {@link org.apache.juneau.rest.client.RestClientBuilder#logTo(Level,Logger)} and
+ {@link org.apache.juneau.rest.client.RestCall#logTo(Level,Logger)} methods to log HTTP calls.
These methods will cause the HTTP request and response headers and body to be logged to the specified logger.
</p>
+
<h6 class='topic'>Example:</h6>
<p class='bcode'>
<jc>// Log the HTTP request/response to the specified logger.</jc>
@@ -702,8 +745,8 @@
The method call is ignored if the logger level is below the specified level.
</p>
<p>
- Customized logging can be handled by subclassing the {@link org.apache.juneau.rest.client.RestCallLogger} class and using the
- {@link org.apache.juneau.rest.client.RestCall#interceptor(RestCallInterceptor)} method.
+ Customized logging can be handled by sub-classing the {@link org.apache.juneau.rest.client.RestCallLogger}
+ class and using the {@link org.apache.juneau.rest.client.RestCall#intercepter(RestCallInterceptor)} method.
</p>
</div>
@@ -712,16 +755,17 @@
<h3 class='topic' onclick='toggle(this)'>1.7 - Interceptors</h3>
<div class='topic'>
<p>
- The {@link org.apache.juneau.rest.client.RestClientBuilder#interceptor(RestCallInterceptor)} and {@link org.apache.juneau.rest.client.RestCall#interceptor(RestCallInterceptor)} methods
- can be used to intercept responses during specific connection lifecycle events.
+ The {@link org.apache.juneau.rest.client.RestClientBuilder#intercepter(RestCallInterceptor)} and
+ {@link org.apache.juneau.rest.client.RestCall#intercepter(RestCallInterceptor)} methods can be used to
+ intercept responses during specific connection lifecycle events.
</p>
<p>
- The {@link org.apache.juneau.rest.client.RestCallLogger} class is an example of an interceptor that uses the various lifecycle methods
- to log HTTP requests.
+ The {@link org.apache.juneau.rest.client.RestCallLogger} class is an example of an intercepter that uses
+ the various lifecycle methods to log HTTP requests.
</p>
<p class='bcode'>
<jd>/**
- * Specialized interceptor for logging calls to a log file.
+ * Specialized intercepter for logging calls to a log file.
*/</jd>
<jk>public class</jk> RestCallLogger <jk>extends</jk> RestCallInterceptor {
@@ -812,21 +856,23 @@
<!-- ======================================================================================================== -->
<a id="Remoteable"></a>
- <h3 class='topic' onclick='toggle(this)'>1.8 - Remotable Proxies</h3>
+ <h3 class='topic' onclick='toggle(this)'>1.8 - Remoteable Proxies</h3>
<div class='topic'>
<p>
Juneau provides the capability of calling methods on POJOs on a server through client-side proxy interfaces.
It offers a number of advantages over other similar remote proxy interfaces, such as being much simpler to
- use and allowing much more flexibility.
+ use and allowing much more flexibility.
</p>
<p>
- Proxy interfaces are retrieved using the {@link org.apache.juneau.rest.client.RestClient#getRemoteableProxy(Class)} method.
- The remoteable servlet is a specialized subclass of {@link org.apache.juneau.rest.RestServlet} that provides a full-blown
- REST interface for calling interfaces remotely.
+ Proxy interfaces are retrieved using the {@link org.apache.juneau.rest.client.RestClient#getRemoteableProxy(Class)}
+ method.
+ The remoteable servlet is a specialized subclass of {@link org.apache.juneau.rest.RestServlet} that
+ provides a full-blown REST interface for calling interfaces remotely.
</p>
<p>
In this example, we have the following interface defined that we want to call from the client side against
- a POJO on the server side (i.e. a Remoteable Service)...
+ a POJO on the server side (i.e. a Remoteable Service)...
+ </p>
<p class='bcode'>
<jk>public interface</jk> IAddressBook {
Person createPerson(CreatePerson cp) <jk>throws</jk> Exception;
@@ -855,18 +901,21 @@
The requirements for a method to be callable through a remoteable service are:
</p>
<ul class='spaced-list'>
- <li>The method must be public.
- <li>The parameter and return types must be <a href='../../../../overview-summary.html#Core.PojoCategories'>serializable and parsable</a>.
+ <li>
+ The method must be public.
+ <li>
+ The parameter and return types must be <a href='../../../../overview-summary.html#Core.PojoCategories'>serializable and parsable</a>.
</ul>
<p>
One significant feature is that the remoteable services servlet is a full-blown REST interface.
- Therefore, in cases where the interface classes are not available on the client side,
- the same method calls can be made through pure REST calls.
- This can also aid significantly in debugging since calls to the remoteable service
- can be called directly from a browser with no code involved.
+ Therefore, in cases where the interface classes are not available on the client side, the same method calls
+ can be made through pure REST calls.
+ This can also aid significantly in debugging since calls to the remoteable service can be called directly
+ from a browser with no code involved.
</p>
<p>
- See <a class='doclink' href='../remoteable/package-summary.html#TOC'>org.apache.juneau.rest.remoteable</a> for more information.
+ See <a class='doclink' href='../remoteable/package-summary.html#TOC'>org.apache.juneau.rest.remoteable</a>
+ for more information.
</p>
</div>
@@ -875,8 +924,8 @@
<h3 class='topic' onclick='toggle(this)'>1.9 - Other Useful Methods</h3>
<div class='topic'>
<p>
- The {@link org.apache.juneau.rest.client.RestClientBuilder#rootUrl(Object)} method can be used to specify a root URL on
- all requests so that you don't have to use absolute paths on individual calls.
+ The {@link org.apache.juneau.rest.client.RestClientBuilder#rootUrl(Object)} method can be used to specify a
+ root URL on all requests so that you don't have to use absolute paths on individual calls.
</p>
<p class='bcode'>
<jc>// Create a rest client with a root URL</jc>
@@ -884,8 +933,8 @@
String r = rc.doGet(<js>"/baz"</js>).getResponseAsString(); <jc>// Gets "http://localhost:9080/foobar/baz"</jc>
</p>
<p>
- The {@link org.apache.juneau.rest.client.RestClientBuilder#property(String,Object)} method can be used to set serializer
- and parser properties.
+ The {@link org.apache.juneau.rest.client.RestClientBuilder#property(String,Object)} method can be used to
+ set serializer and parser properties.
For example, if you're parsing a response into POJOs and you want to ignore fields that aren't on the
POJOs, you can use the {@link org.apache.juneau.BeanContext#BEAN_ignoreUnknownBeanProperties} property.
</p>
@@ -898,10 +947,10 @@
MyPojo myPojo = rc.doGet(<jsf>URL</jsf>).getResponse(MyPojo.<jk>class</jk>);
</p>
<p>
- The {@link org.apache.juneau.rest.client.RestCall#retryable(int,long,RetryOn)} method can be used to automatically
- retry requests on failures.
- This can be particularly useful if you're attempting to connect to a REST resource that may be in
- the process of still initializing.
+ The {@link org.apache.juneau.rest.client.RestCall#retryable(int,long,RetryOn)} method can be used to
+ automatically retry requests on failures.
+ This can be particularly useful if you're attempting to connect to a REST resource that may be in the
+ process of still initializing.
</p>
<p class='bcode'>
<jc>// Create a rest call that retries every 10 seconds for up to 30 minutes as long as a connection fails
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-rest-jaxrs/src/main/java/org/apache/juneau/rest/jaxrs/package.html
----------------------------------------------------------------------
diff --git a/juneau-rest-jaxrs/src/main/java/org/apache/juneau/rest/jaxrs/package.html b/juneau-rest-jaxrs/src/main/java/org/apache/juneau/rest/jaxrs/package.html
index 43c3b15..926cbdf 100644
--- a/juneau-rest-jaxrs/src/main/java/org/apache/juneau/rest/jaxrs/package.html
+++ b/juneau-rest-jaxrs/src/main/java/org/apache/juneau/rest/jaxrs/package.html
@@ -81,26 +81,35 @@
What you can do with the Juneau JAX-RS provider classes:
</p>
<ul class='spaced-list'>
- <li>Use existing Juneau serializers and parsers for converting streams to POJOs and vis-versa.
- <li>Use annotations to specify filters and properties using the {@link org.apache.juneau.rest.annotation.RestMethod}
+ <li>
+ Use existing Juneau serializers and parsers for converting streams to POJOs and vis-versa.
+ <li>
+ Use annotations to specify filters and properties using the {@link org.apache.juneau.rest.annotation.RestMethod}
and {@link org.apache.juneau.rest.jaxrs.JuneauProvider} annotations.
</ul>
<p>
What you can't do with the Juneau JAX-RS provider classes:
</p>
<ul class='spaced-list'>
- <li>Specify or override serializers/parsers at the Java class and method levels.
+ <li>
+ Specify or override serializers/parsers at the Java class and method levels.
<br>JAX-RS does not provide the capability to use different providers for the same media types
- at the class or method levels.
- <li>Specify or override filters and properties at the Java class level.
- <li>Default stylesheets for the {@link org.apache.juneau.html.HtmlDocSerializer} class.
+ at the class or method levels.
+ <li>
+ Specify or override filters and properties at the Java class level.
+ <li>
+ Default stylesheets for the {@link org.apache.juneau.html.HtmlDocSerializer} class.
<br>It will produce HTML, but it won't contain any styles applied.
<br>However, it's possible to specify your own stylesheet using the {@link org.apache.juneau.html.HtmlDocSerializerContext#HTMLDOC_cssUrl} property.
- <li>The ability to specify HTTP method, headers, and content using GET parameters.
+ <li>
+ The ability to specify HTTP method, headers, and content using GET parameters.
<br>These make debugging REST interfaces using only a browser possible.
- <li>Class or method level encoding.
- <li>Class or method level guards.
- <li>Class or method level converters.
+ <li>
+ Class or method level encoding.
+ <li>
+ Class or method level guards.
+ <li>
+ Class or method level converters.
</ul>
<h6 class='topic'>Juneau JAX-RS Provider API</h6>
@@ -108,12 +117,15 @@
The Juneau JAX-RS provider API consists of the following classes:
</p>
<ul class='spaced-list'>
- <li>{@link org.apache.juneau.rest.jaxrs.BaseProvider} - The base provider class that implements the JAX-RS
+ <li>
+ {@link org.apache.juneau.rest.jaxrs.BaseProvider} - The base provider class that implements the JAX-RS
<code>MessageBodyReader</code> and <code>MessageBodyWriter</code> interfaces.
- <li>{@link org.apache.juneau.rest.jaxrs.JuneauProvider} - Annotation that is applied to subclasses of <code>BaseProvider</code>
+ <li>
+ {@link org.apache.juneau.rest.jaxrs.JuneauProvider} - Annotation that is applied to subclasses of <code>BaseProvider</code>
to specify the serializers/parsers associated with a provider, and optionally filters and properties to
apply to those serializers and parsers.
- <li>{@link org.apache.juneau.rest.jaxrs.DefaultProvider} - A default provider that provides the same level
+ <li>
+ {@link org.apache.juneau.rest.jaxrs.DefaultProvider} - A default provider that provides the same level
of media type support as the {@link org.apache.juneau.rest.RestServletDefault} class.
</ul>
<p>