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>
