http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.client/src/com/ibm/juno/client/jazz/JazzRestClient.java ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.client/src/com/ibm/juno/client/jazz/JazzRestClient.java b/com.ibm.team.juno.client/src/com/ibm/juno/client/jazz/JazzRestClient.java new file mode 100755 index 0000000..e578b0d --- /dev/null +++ b/com.ibm.team.juno.client/src/com/ibm/juno/client/jazz/JazzRestClient.java @@ -0,0 +1,392 @@ +/******************************************************************************* + * Licensed Materials - Property of IBM + * (c) Copyright IBM Corporation 2014, 2015. All Rights Reserved. + * + * The source code for this program is not published or otherwise + * divested of its trade secrets, irrespective of what has been + * deposited with the U.S. Copyright Office. + *******************************************************************************/ +package com.ibm.juno.client.jazz; + +import static org.apache.http.HttpStatus.*; + +import java.io.*; +import java.net.*; +import java.util.*; + +import org.apache.http.*; +import org.apache.http.auth.*; +import org.apache.http.client.*; +import org.apache.http.client.config.*; +import org.apache.http.client.entity.*; +import org.apache.http.client.methods.*; +import org.apache.http.impl.client.*; +import org.apache.http.message.*; +import org.apache.http.util.*; + +import com.ibm.juno.client.*; +import com.ibm.juno.core.parser.*; +import com.ibm.juno.core.serializer.*; +import com.ibm.juno.core.utils.*; + +/** + * Specialized {@link RestClient} for working with Jazz servers. + * <p> + * Provides support for BASIC, FORM, and OIDC authentication against Jazz servers and simple SSL certificate validation. + * + * <h6 class='topic'>Additional Information</h6> + * <ul> + * <li><a class='doclink' href='package-summary.html#RestClient'>com.ibm.juno.client.jazz > Jazz REST client API</a> for more information and code examples. + * </ul> + * @author James Bognar ([email protected]) + */ +public class JazzRestClient extends RestClient { + + private String user, pw; + private URI jazzUri; + private SSLOpts sslOpts; + private String cookie = null; + + /** + * Create a new client with no serializer or parser. + * + * @param jazzUrl The URL of the Jazz server being connected to (e.g. <js>"https://localhost:9443/jazz";</js>) + * @param sslOpts SSL options. + * @param user The Jazz username. + * @param pw The Jazz password. + * @throws IOException If a problem occurred trying to authenticate against the Jazz server. + */ + public JazzRestClient(String jazzUrl, SSLOpts sslOpts, String user, String pw) throws IOException { + super(); + this.user = user; + this.pw = pw; + if (! jazzUrl.endsWith("/")) + jazzUrl = jazzUrl + "/"; + this.sslOpts = sslOpts; + jazzUri = URI.create(jazzUrl); + } + + /** + * Create a new client with no serializer or parser, and LAX SSL support. + * + * @param jazzUrl The URL of the Jazz server being connected to (e.g. <js>"https://localhost:9443/jazz";</js>) + * @param user The Jazz username. + * @param pw The Jazz password. + * @throws IOException + */ + public JazzRestClient(String jazzUrl, String user, String pw) throws IOException { + this(jazzUrl, SSLOpts.LAX, user, pw); + } + + /** + * Create a new client with the specified serializer and parser instances. + * + * @param jazzUri The URI of the Jazz server being connected to (e.g. <js>"https://localhost:9443/jazz";</js>) + * @param sslOpts SSL options. + * @param user The Jazz username. + * @param pw The Jazz password. + * @param s The serializer for converting POJOs to HTTP request message body text. + * @param p The parser for converting HTTP response message body text to POJOs. + * @throws IOException If a problem occurred trying to authenticate against the Jazz server. + */ + public JazzRestClient(String jazzUri, SSLOpts sslOpts, String user, String pw, Serializer<?> s, Parser<?> p) throws IOException { + this(jazzUri, sslOpts, user, pw); + setParser(p); + setSerializer(s); + } + + /** + * Create a new client with the specified serializer and parser instances and LAX SSL support. + * + * @param jazzUri The URI of the Jazz server being connected to (e.g. <js>"https://localhost:9443/jazz";</js>) + * @param user The Jazz username. + * @param pw The Jazz password. + * @param s The serializer for converting POJOs to HTTP request message body text. + * @param p The parser for converting HTTP response message body text to POJOs. + * @throws IOException If a problem occurred trying to authenticate against the Jazz server. + */ + public JazzRestClient(String jazzUri, String user, String pw, Serializer<?> s, Parser<?> p) throws IOException { + this(jazzUri, SSLOpts.LAX, user, pw); + setParser(p); + setSerializer(s); + } + + /** + * Create a new client with the specified serializer and parser classes. + * + * @param jazzUri The URI of the Jazz server being connected to (e.g. <js>"https://localhost:9443/jazz";</js>) + * @param sslOpts SSL options. + * @param user The Jazz username. + * @param pw The Jazz password. + * @param s The serializer for converting POJOs to HTTP request message body text. + * @param p The parser for converting HTTP response message body text to POJOs. + * @throws IOException If a problem occurred trying to authenticate against the Jazz server. + * @throws InstantiationException If serializer or parser could not be instantiated. + */ + public JazzRestClient(String jazzUri, SSLOpts sslOpts, String user, String pw, Class<? extends Serializer<?>> s, Class<? extends Parser<?>> p) throws InstantiationException, IOException { + this(jazzUri, sslOpts, user, pw); + setParser(p); + setSerializer(s); + } + + /** + * Create a new client with the specified serializer and parser classes and LAX SSL support. + * + * @param jazzUri The URI of the Jazz server being connected to (e.g. <js>"https://localhost:9443/jazz";</js>) + * @param user The Jazz username. + * @param pw The Jazz password. + * @param s The serializer for converting POJOs to HTTP request message body text. + * @param p The parser for converting HTTP response message body text to POJOs. + * @throws IOException If a problem occurred trying to authenticate against the Jazz server. + * @throws InstantiationException If serializer or parser could not be instantiated. + */ + public JazzRestClient(String jazzUri, String user, String pw, Class<? extends Serializer<?>> s, Class<? extends Parser<?>> p) throws InstantiationException, IOException { + this(jazzUri, SSLOpts.LAX, user, pw); + setParser(p); + setSerializer(s); + } + + @Override /* RestClient */ + protected CloseableHttpClient createHttpClient() throws Exception { + try { + if (jazzUri.getScheme().equals("https")) + enableSSL(sslOpts); + + httpClientBuilder.setConnectionManager(createConnectionManager()); + + setRedirectStrategy(new AllowAllRedirects()); + + // See wi 368181. The PublicSuffixDomainFilter uses a default PublicSuffixMatcher + // that rejects hostnames lacking a dot, such as "ccmserver", so needed + // cookies don't get put on outgoing requests. + // Here, we create a cookie spec registry with handlers that don't have a PublicSuffixMatcher. + if (! Boolean.getBoolean("com.ibm.team.repository.transport.client.useDefaultPublicSuffixMatcher")) { //$NON-NLS-1$ + // use a lenient PublicSuffixDomainFilter + setDefaultCookieSpecRegistry(CookieSpecRegistries.createDefault(null)); + } + + // We want to use a fresh HttpClientBuilder since the default implementation + // uses an unshared PoolingConnectionManager, and if you close the client + // and create a new one, can cause a "java.lang.IllegalStateException: Connection pool shut down" + CloseableHttpClient client = httpClientBuilder.build(); + + // Tomcat will respond with SC_BAD_REQUEST (or SC_REQUEST_TIMEOUT?) when the + // j_security_check URL is visited before an authenticated URL has been visited. + visitAuthenticatedURL(client); + + // Authenticate against the server. + String authMethod = determineAuthMethod(client); + if (authMethod.equals("FORM")) { + formBasedAuthenticate(client); + visitAuthenticatedURL(client); + } else if (authMethod.equals("BASIC")) { + AuthScope scope = new AuthScope(jazzUri.getHost(), jazzUri.getPort()); + Credentials up = new UsernamePasswordCredentials(user, pw); + CredentialsProvider p = new BasicCredentialsProvider(); + p.setCredentials(scope, up); + setDefaultCredentialsProvider(p); + client.close(); + client = httpClientBuilder.build(); + } else if (authMethod.equals("OIDC")) { + oidcAuthenticate(client); + client.close(); + client = httpClientBuilder.build(); + } + + return client; + } catch (Exception e) { + throw e; + } catch (Throwable e) { + throw new RuntimeException(e); + } + } + + @Override /* RestClient */ + protected HttpClientBuilder createHttpClientBuilder() { + HttpClientBuilder b = super.createHttpClientBuilder(); + + // See wi 368181. The PublicSuffixDomainFilter uses a default PublicSuffixMatcher + // that rejects hostnames lacking a dot, such as "ccmserver", so needed + // cookies don't get put on outgoing requests. + // Here, we create a cookie spec registry with handlers that don't have a PublicSuffixMatcher. + if (! Boolean.getBoolean("com.ibm.team.repository.transport.client.useDefaultPublicSuffixMatcher")) + b.setDefaultCookieSpecRegistry(CookieSpecRegistries.createDefault(null)); + + return b; + } + + + /** + * Performs form-based authentication against the Jazz server. + */ + private void formBasedAuthenticate(HttpClient client) throws IOException { + + URI uri2 = jazzUri.resolve("j_security_check"); + HttpPost request = new HttpPost(uri2); + request.setConfig(RequestConfig.custom().setRedirectsEnabled(false).build()); + // Charset must explicitly be set to UTF-8 to handle user/pw with non-ascii characters. + request.addHeader("Content-Type", "application/x-www-form-urlencoded; charset=utf-8"); + + NameValuePairs params = new NameValuePairs() + .append(new BasicNameValuePair("j_username", user)) + .append(new BasicNameValuePair("j_password", pw)); + request.setEntity(new UrlEncodedFormEntity(params)); + + HttpResponse response = client.execute(request); + try { + int rc = response.getStatusLine().getStatusCode(); + + Header authMsg = response.getFirstHeader("X-com-ibm-team-repository-web-auth-msg"); + if (authMsg != null) + throw new IOException(authMsg.getValue()); + + // The form auth request should always respond with a 200 ok or 302 redirect code + if (rc == SC_MOVED_TEMPORARILY) { + if (response.getFirstHeader("Location").getValue().matches("^.*/auth/authfailed.*$")) + throw new IOException("Invalid credentials."); + } else if (rc != SC_OK) { + throw new IOException("Unexpected HTTP status: " + rc); + } + } finally { + EntityUtils.consume(response.getEntity()); + } + } + + private void oidcAuthenticate(HttpClient client) throws IOException { + + HttpGet request = new HttpGet(jazzUri); + request.setConfig(RequestConfig.custom().setRedirectsEnabled(false).build()); + + // Charset must explicitly be set to UTF-8 to handle user/pw with non-ascii characters. + request.addHeader("Content-Type", "application/x-www-form-urlencoded; charset=utf-8"); + + HttpResponse response = client.execute(request); + try { + int code = response.getStatusLine().getStatusCode(); + + // Already authenticated + if (code == SC_OK) + return; + + if (code != SC_UNAUTHORIZED) + throw new RestCallException("Unexpected response during OIDC authentication: " + response.getStatusLine()); + + //'x-jsa-authorization-redirect' + String redirectUri = getHeader(response, "X-JSA-AUTHORIZATION-REDIRECT"); + + if (redirectUri == null) + throw new RestCallException("Excpected a redirect URI during OIDC authentication: " + response.getStatusLine()); + + // Handle Bearer Challenge + HttpGet method = new HttpGet(redirectUri + "&prompt=none"); + addDefaultOidcHeaders(method); + + response = client.execute(method); + + code = response.getStatusLine().getStatusCode(); + + if (code != SC_OK) + throw new RestCallException("Unexpected response during OIDC authentication phase 2: " + response.getStatusLine()); + + String loginRequired = getHeader(response, "X-JSA-LOGIN-REQUIRED"); + + if (! "true".equals(loginRequired)) + throw new RestCallException("X-JSA-LOGIN-REQUIRED header not found on response during OIDC authentication phase 2: " + response.getStatusLine()); + + method = new HttpGet(redirectUri + "&prompt=none"); + + addDefaultOidcHeaders(method); + response = client.execute(method); + + code = response.getStatusLine().getStatusCode(); + + if (code != SC_OK) + throw new RestCallException("Unexpected response during OIDC authentication phase 3: " + response.getStatusLine()); + + // Handle JAS Challenge + method = new HttpGet(redirectUri); + addDefaultOidcHeaders(method); + + response = client.execute(method); + + code = response.getStatusLine().getStatusCode(); + + if (code != SC_OK) + throw new RestCallException("Unexpected response during OIDC authentication phase 4: " + response.getStatusLine()); + + cookie = getHeader(response, "Set-Cookie"); + + Header[] defaultHeaders = new Header[] { + new BasicHeader("User-Agent", "Jazz Native Client"), + new BasicHeader("X-com-ibm-team-configuration-versions", "com.ibm.team.rtc=6.0.0,com.ibm.team.jazz.foundation=6.0"), + new BasicHeader("Accept", "text/json"), + new BasicHeader("Authorization", "Basic " + StringUtils.base64EncodeToString(this.user + ":" + this.pw)), + new BasicHeader("Cookie", cookie) + }; + + setDefaultHeaders(Arrays.asList(defaultHeaders)); + + } finally { + EntityUtils.consume(response.getEntity()); + } + } + + /* + * This is needed for Tomcat because it responds with SC_BAD_REQUEST when the j_security_check URL is visited before an + * authenticated URL has been visited. This same URL must also be visited after authenticating with j_security_check + * otherwise tomcat will not consider the session authenticated + */ + private int visitAuthenticatedURL(HttpClient httpClient) throws IOException { + HttpGet authenticatedURL = new HttpGet(jazzUri.resolve("authenticated/identity")); + HttpResponse response = httpClient.execute(authenticatedURL); + try { + return response.getStatusLine().getStatusCode(); + } finally { + EntityUtils.consume(response.getEntity()); + } + } + + /* + * @return Returns "FORM" for form-based authenication, "BASIC" for basic auth, "OIDC" for OIDC. Never <code>null</code>. + */ + private String determineAuthMethod(HttpClient client) throws IOException { + + HttpGet request = new HttpGet(jazzUri.resolve("authenticated/identity")); + request.setConfig(RequestConfig.custom().setRedirectsEnabled(false).build()); + + // if the FORM_AUTH_URI path exists, then we know we are using FORM auth + HttpResponse response = client.execute(request); + try { //'x-jsa-authorization-redirect' + Header redirectUri = response.getFirstHeader("X-JSA-AUTHORIZATION-REDIRECT"); + if (redirectUri != null) + return "OIDC"; + + int rc = response.getStatusLine().getStatusCode(); + // Tomcat and Jetty return a status code 200 if the server is using FORM auth + if (rc == SC_OK) + return "FORM"; + else if (rc == SC_MOVED_TEMPORARILY && response.getFirstHeader("Location").getValue().matches("^.*(/auth/authrequired|/authenticated/identity).*$")) + return "FORM"; + return "BASIC"; + + } finally { + EntityUtils.consume(response.getEntity()); + } + } + + private String getHeader(HttpResponse response, String key) { + Header h = response.getFirstHeader(key); + return (h == null ? null : h.getValue()); + } + + private void addDefaultOidcHeaders(HttpRequestBase method) { + method.addHeader("User-Agent", "Jazz Native Client"); + method.addHeader("X-com-ibm-team-configuration-versions", "com.ibm.team.rtc=6.0.0,com.ibm.team.jazz.foundation=6.0"); + method.addHeader("Accept", "text/json"); + + if (cookie != null) { + method.addHeader("Authorization", "Basic " + StringUtils.base64EncodeToString(user + ":" + pw)); + method.addHeader("Cookie", cookie); + } + } +}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.client/src/com/ibm/juno/client/jazz/package.html ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.client/src/com/ibm/juno/client/jazz/package.html b/com.ibm.team.juno.client/src/com/ibm/juno/client/jazz/package.html new file mode 100755 index 0000000..fce9248 --- /dev/null +++ b/com.ibm.team.juno.client/src/com/ibm/juno/client/jazz/package.html @@ -0,0 +1,187 @@ +<!DOCTYPE HTML> +<!-- + Licensed Materials - Property of IBM + (c) Copyright IBM Corporation 2014. All Rights Reserved. + + Note to U.S. Government Users Restricted Rights: + Use, duplication or disclosure restricted by GSA ADP Schedule + Contract with IBM Corp. + --> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <style type="text/css"> + /* For viewing in Page Designer */ + @IMPORT url("../../../../../../javadoc.css"); + + /* For viewing in REST interface */ + @IMPORT url("../htdocs/javadoc.css"); + body { + margin: 20px; + } + </style> + <script> + /* Replace all @code and @link tags. */ + window.onload = function() { + document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>'); + document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>'); + } + </script> +</head> +<body> +<p>Jazz REST client API</p> + +<script> + function toggle(x) { + var div = x.nextSibling; + while (div != null && div.nodeType != 1) + div = div.nextSibling; + if (div != null) { + var d = div.style.display; + if (d == 'block' || d == '') { + div.style.display = 'none'; + x.className += " closed"; + } else { + div.style.display = 'block'; + x.className = x.className.replace(/(?:^|\s)closed(?!\S)/g , '' ); + } + } + } +</script> + +<a id='TOC'></a><h5 class='toc'>Table of Contents</h5> +<ol class='toc'> + <li><p><a class='doclink' href='#RestClient'>Jazz REST client API</a></p> +</ol> + +<!-- ======================================================================================================== --> +<a id="RestClient"></a> +<h2 class='topic' onclick='toggle(this)'>1 - Jazz REST client API</h2> +<div class='topic'> + <p> + Juno provides a default REST client implementation for working with Jazz servers. + The client automatically detects and handles BASIC and FORM authentication and basic certificate authentication. + </p> + <p> + The following code shows the Jazz REST client being used for querying and creating server messages on + a Jazz server. The <code>ServerMessage</code> and <code>CreateServerMessage</code> classes + are nothing more than simple beans that get serialized over the connection and reconstituted on + the server. + </p> + <p class='bcode'> + System.<jsf>out</jsf>.println(<js>"Adding sample messages"</js>); + + DateFormat df = <jk>new</jk> SimpleDateFormat(<js>"yyyy-MM-dd'T'HH:mm:ssZ"</js>); + String url = <js>"https://localhost:9443/jazz";</js>; + String sms = url + <js>"/serverMessages"</js>; + CreateServerMessage m; + ServerMessage m2; + String s1; + ServerMessage[] messages; + + <jc>// Serializer for debug messages.</jc> + WriterSerializer serializer = JsonSerializer.<jsf>DEFAULT</jsf>; + + <jc>// Create clients to handle JSON and XML requests and responses.</jc> + RestClient jsonClient = <jk>new</jk> JazzRestClient(url, <js>"ADMIN"</js>, <js>"ADMIN"</js>) + .setSerializer(JsonSerializer.<jk>class</jk>) + .setParser(<jk>new</jk> JsonParser().addFilters(DateFilter.<jsf>ISO8601DTZ</jsf>.<jk>class</jk>)); + + RestClient xmlClient = <jk>new</jk> JazzRestClient(url, <js>"ADMIN"</js>, <js>"ADMIN"</js>, XmlSerializer.<jk>class</jk>, XmlParser.<jk>class</jk>); + + <jc>// Delete any existing messages.</jc> + messages = jsonClient + .doGet(sms) + .getResponse(ServerMessage[].<jk>class</jk>); + + <jk>for</jk> (ServerMessage message : messages) { + <jk>int</jk> rc = jsonClient + .doDelete(message.getUri()) + .execute(); + System.<jsf>out</jsf>.println(rc); <jc>// Prints 200.</jc> + } + + <jc>// Create an active server message.</jc> + m = <jk>new</jk> CreateServerMessage( + <jsf>INFO</jsf>, + <js>"Test message #1"</js>, + <js>"subTypeFoo"</js>, + df.parse(<js>"2012-01-01T12:34:56EST"</js>), + df.parse(<js>"2013-01-01T12:34:56EST"</js>)); + + <jc>// POST the message, get response as string.</jc> + s1 = jsonClient + .doPost(sms, m) + .getResponseAsString(); + System.<jsf>out</jsf>.println(<js>"TEST1: response="</js> + s1); + + <jc>// POST another message, get response as ServerMessage</jc> + m = <jk>new</jk> CreateServerMessage( + <jsf>INFO</jsf>, + <js>"Test message #2"</js>, + <js>"subTypeFoo"</js>, + df.parse(<js>"2012-01-01T12:34:56EST"</js>), + df.parse(<js>"2013-01-01T12:34:56EST"</js>)); + + m2 = jsonClient + .doPost(sms, m) + .getResponse(ServerMessage.<jk>class</jk>); + System.<jsf>out</jsf>.println(<js>"TEST2: response="</js> + serializer.serialize(m2)); + + <jc>// Create a future server message.</jc> + m = <jk>new</jk> CreateServerMessage( + <jsf>INFO</jsf>, + <js>"Test message #3"</js>, + <js>"subTypeFoo"</js>, + df.parse(<js>"2013-01-01T12:34:56EST"</js>), + df.parse(<js>"2014-01-01T12:34:56EST"</js>)); + + m2 = jsonClient + .doPost(sms, m) + .getResponse(ServerMessage.<jk>class</jk>); + System.<jsf>out</jsf>.println(<js>"TEST3: response="</js> + serializer.serialize(m2)); + System.<jsf>out</jsf>.println(<js>"TEST3: id="</js> + m2.getItemId().getUuidValue()); + + <jc>// Create a future server message using XML on both request and response.</jc> + m = <jk>new</jk> CreateServerMessage( + <jsf>INFO</jsf>, + <js>"Test message #4"</js>, + <js>"subTypeFoo"</js>, + df.parse(<js>"2013-01-01T12:34:56EST"</js>), + df.parse(<js>"2014-01-01T12:34:56EST"</js>)); + + s1 = xmlClient + .doPost(sms, m) + .getResponseAsString(); + System.<jsf>out</jsf>.println(<js>"TEST4: response="</js> + s1); + + <jc>// Get all the messages</jc> + messages = jsonClient + .doGet(sms) + .getResponse(ServerMessage[].<jk>class</jk>); + System.<jsf>out</jsf>.println(<js>"TEST5: response="</js> + serializer.serialize(messages)); + + <jc>// Get the first ID</jc> + URI firstMessageUrl = messages[0].getUri(); + + System.<jsf>out</jsf>.println(<js>"firstMessageUrl=["</js>+firstMessageUrl+<js>"]"</js>); + + <jc>// Get the Date of the first ID.</jc> + Date startDate = jsonClient + .doGet(firstMessageUrl + <js>"/startDate"</js>) + .getResponse(Date.<jk>class</jk>); + System.<jsf>out</jsf>.println(<js>"TEST5: response.startDate="</js>+startDate); + + <jc>// Change the start and end dates on first message</jc> + m = <jk>new</jk> CreateServerMessage( + <jsf>INFO</jsf>, + <js>"Test message #3 overwritten"</js>, + <js>"subTypeFooBar"</js>, + df.parse(<js>"2023-01-01T12:34:56EST"</js>), + df.parse(<js>"2024-01-01T12:34:56EST"</js>)); + s1 = jsonClient.doPut(firstMessageUrl, m).getResponseAsString(); + System.<jsf>out</jsf>.println(<js>"TEST6: response="</js>+s1); + </p> +</div> +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.client/src/com/ibm/juno/client/package.html ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.client/src/com/ibm/juno/client/package.html b/com.ibm.team.juno.client/src/com/ibm/juno/client/package.html new file mode 100755 index 0000000..407ef7c --- /dev/null +++ b/com.ibm.team.juno.client/src/com/ibm/juno/client/package.html @@ -0,0 +1,850 @@ +<!DOCTYPE HTML> +<!-- + Licensed Materials - Property of IBM + (c) Copyright IBM Corporation 2014. All Rights Reserved. + + Note to U.S. Government Users Restricted Rights: + Use, duplication or disclosure restricted by GSA ADP Schedule + Contract with IBM Corp. + --> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <style type="text/css"> + /* For viewing in Page Designer */ + @IMPORT url("../../../../../javadoc.css"); + + /* For viewing in REST interface */ + @IMPORT url("../htdocs/javadoc.css"); + body { + margin: 20px; + } + </style> + <script> + /* Replace all @code and @link tags. */ + window.onload = function() { + document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>'); + document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>'); + } + </script> +</head> +<body> +<p>REST client API</p> + +<script> + function toggle(x) { + var div = x.nextSibling; + while (div != null && div.nodeType != 1) + div = div.nextSibling; + if (div != null) { + var d = div.style.display; + if (d == 'block' || d == '') { + div.style.display = 'none'; + x.className += " closed"; + } else { + div.style.display = 'block'; + x.className = x.className.replace(/(?:^|\s)closed(?!\S)/g , '' ); + } + } + } +</script> + +<a id='TOC'></a><h5 class='toc'>Table of Contents</h5> +<ol class='toc'> + <li><p><a class='doclink' href='#RestClient'>REST Client API</a></p> + <ol> + <li><p><a class='doclink' href='#SSL'>SSL Support</a></p> + <ol> + <li><p><a class='doclink' href='#SSLOpts'>SSLOpts Bean</a></p> + </ol> + <li><p><a class='doclink' href='#Authentication'>Authentication</a></p> + <ol> + <li><p><a class='doclink' href='#BASIC'>BASIC Authentication</a></p> + <li><p><a class='doclink' href='#FORM'>FORM-based Authentication</a></p> + <li><p><a class='doclink' href='#OIDC'>OIDC Authentication</a></p> + </ol> + <li><p><a class='doclink' href='#ResponsePatterns'>Using Response Patterns</a></p> + <li><p><a class='doclink' href='#PipingOutput'>Piping Response Output</a></p> + <li><p><a class='doclink' href='#Logging'>Logging</a></p> + <li><p><a class='doclink' href='#Interceptors'>Interceptors</a></p> + <li><p><a class='doclink' href='#Remoteable'>Remoteable Proxies</a></p> + <li><p><a class='doclink' href='#Other'>Other Useful Methods</a></p> + </ol> +</ol> + +<!-- ======================================================================================================== --> +<a id="RestClient"></a> +<h2 class='topic' onclick='toggle(this)'>1 - REST Client API</h2> +<div class='topic'> + <p> + Juno 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 com.ibm.juno.core.serializer.Serializer} classes. + <li>Converts HTTP response message bodies directly to POJOs using {@link com.ibm.juno.core.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. + </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. + </p> + <p> + The Juno client API prereq's Apache HttpClient 4.1.2+. + At a mimimum, 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'>Examples</h6> + <p class='bcode'> + <jc>// Examples below use the Juno Address Book resource example</jc> + + <jc>// Create a reusable client with JSON support</jc> + RestClient client = <jk>new</jk> RestClient(JsonSerializer.<jk>class</jk>, JsonParser.<jk>class</jk>); + + <jc>// GET request, ignoring output</jc> + <jk>try</jk> { + <jk>int</jk> rc = client.doGet(<js>"http://localhost:9080/sample/addressBook";</js>).execute(); + <jc>// Succeeded!</jc> + } <jk>catch</jk> (RestCallException e) { + <jc>// Failed!</jc> + System.<jsf>err</jsf>.println( + String.<jsm>format</jsm>(<js>"status=%s, message=%s"</js>, e.getResponseStatus(), e.getResponseMessage()) + ); + } + + <jc>// Remaining examples ignore thrown exceptions.</jc> + + <jc>// GET request, secure, ignoring output</jc> + client.doGet(<js>"https://localhost:9443/sample/addressBook";</js>).execute(); + + <jc>// GET request, getting output as a String. No POJO parsing is performed. + // Note that when calling one of the getX() methods, you don't need to call connect() or disconnect(), since + // it's automatically called for you.</jc> + String output = client.doGet(<js>"http://localhost:9080/sample/addressBook";</js>) + .getResponseAsString(); + + <jc>// GET request, getting output as a Reader</jc> + Reader r = client.doGet(<js>"http://localhost:9080/sample/addressBook";</js>) + .getReader(); + + <jc>// GET request, getting output as an ObjectMap</jc> + <jc>// Input must be an object (e.g. "{...}")</jc> + ObjectMap m = client.doGet(<js>"http://localhost:9080/sample/addressBook/0";</js>) + .getResponse(ObjectMap.<jk>class</jk>); + + <jc>// GET request, getting output as a ObjectList</jc> + <jc>// Input must be an array (e.g. "[...]")</jc> + ObjectList l = client.doGet(<js>"http://localhost:9080/sample/addressBook";</js>) + .getResponse(ObjectList.<jk>class</jk>); + + <jc>// GET request, getting output as a parsed bean</jc> + <jc>// Input must be an object (e.g. "{...}")</jc> + <jc>// Note that you don't have to do any casting!</jc> + Person p = client.doGet(<js>"http://localhost:9080/sample/addressBook/0";</js>) + .getResponse(Person.<jk>class</jk>); + + <jc>// GET request, getting output as a parsed bean</jc> + <jc>// Input must be an array of objects (e.g. "[{...},{...}]")</jc> + Person[] pa = client.doGet(<js>"http://localhost:9080/sample/addressBook";</js>) + .getResponse(Person[].<jk>class</jk>); + + <jc>// Same as above, except as a List<Person></jc> + ClassMeta cm = BeanContext.<jsf>DEFAULT</jsf>.getCollectionClassMeta(LinkedList.<jk>class</jk>, Person.<jk>class</jk>); + List<Person> pl = client.doGet(<js>"http://localhost:9080/sample/addressBook";</js>) + .getResponse(cm); + + <jc>// GET request, getting output as a parsed string</jc> + <jc>// Input must be a string (e.g. "<string>foo</string>" or "'foo'")</jc> + String name = client.doGet(<js>"http://localhost:9080/sample/addressBook/0/name";</js>) + .getResponse(String.<jk>class</jk>); + + <jc>// GET request, getting output as a parsed number</jc> + <jc>// Input must be a number (e.g. "<number>123</number>" or "123")</jc> + <jk>int</jk> age = client.doGet(<js>"http://localhost:9080/sample/addressBook/0/age";</js>) + .getResponse(Integer.<jk>class</jk>); + + <jc>// GET request, getting output as a parsed boolean</jc> + <jc>// Input must be a boolean (e.g. "<boolean>true</boolean>" or "true")</jc> + <jk>boolean</jk> isCurrent = client.doGet(<js>"http://localhost:9080/sample/addressBook/0/addresses/0/isCurrent";</js>) + .getResponse(Boolean.<jk>class</jk>); + + <jc>// GET request, getting a filtered object</jc> + client.getParser().addFilters(CalendarFilter.<jsf>ISO8601</jsf>.<jk>class</jk>); + Calendar birthDate = client.doGet(<js>"http://localhost:9080/sample/addressBook/0/birthDate";</js>) + .getResponse(GregorianCalendar.<jk>class</jk>); + + <jc>// PUT request on regular field</jc> + String newName = <js>"John Smith"</js>; + <jk>int</jk> rc = client.doPut(<js>"http://localhost:9080/addressBook/0/name";</js>, newName).execute(); + + <jc>// PUT request on filtered field</jc> + Calendar newBirthDate = <jk>new</jk> GregorianCalendar(1, 2, 3, 4, 5, 6); + rc = client.doPut(<js>"http://localhost:9080/sample/addressBook/0/birthDate";</js>, newBirthDate).execute(); + + <jc>// POST of a new entry to a list</jc> + Address newAddress = <jk>new</jk> Address(<js>"101 Main St"</js>, <js>"Anywhere"</js>, <js>"NY"</js>, 12121, <jk>false</jk>); + rc = client.doPost(<js>"http://localhost:9080/addressBook/0/addresses";</js>, newAddress).execute(); + </p> + + <h6 class='notes'>Notes:</h6> + <ul class='notes'> + <li><p>The {@link com.ibm.juno.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> + </ul> + + <!-- ======================================================================================================== --> + <a id="SSL"></a> + <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 com.ibm.juno.client.RestClient#enableSSL(SSLOpts)} method + and one of the predefined {@link com.ibm.juno.client.SSLOpts} instances: + <ul> + <li>{@link com.ibm.juno.client.SSLOpts#DEFAULT} - Normal certificate and hostname validation. + <li>{@link com.ibm.juno.client.SSLOpts#LAX} - Allows for self-signed certificates. + </ul> + </p> + <h6 class='topic'>Example:</h6> + <p class='bcode'> + <jc>// Create a client that ignores self-signed or otherwise invalid certificates.</jc> + RestClient restClient = <jk>new</jk> RestClient() + .enableSSL(SSLOpts.<jsf>LAX</jsf>); + + <jc>// ...or...</jc> + RestClient restClient = <jk>new</jk> RestClient() + .enableLaxSSL(); + </p> + <p> + This is functionally equivalent to the following: + </p> + <p class='bcode'> + RestClient restClient = <jk>new</jk> RestClient(); + + HostnameVerifier hv = <jk>new</jk> NoopHostnameVerifier(); + TrustManager tm = <jk>new</jk> SimpleX509TrustManager(<jk>true</jk>); + + <jk>for</jk> (String p : <jk>new</jk> String[]{<js>"SSL"</js>,<js>"TLS"</js>,<js>"SSL_TLS"</js>}) { + SSLContext ctx = SSLContext.<jsm>getInstance</jsm>(p); + ctx.init(<jk>null</jk>, <jk>new</jk> TrustManager[] { tm }, <jk>null</jk>); + SSLConnectionSocketFactory sf = <jk>new</jk> SSLConnectionSocketFactory(ctx, hv); + restClient.setSSLSocketFactory(sf); + Registry<ConnectionSocketFactory> r = RegistryBuilder.<ConnectionSocketFactory><jsm>.create</jsm>().register(<js>"https"</js>, sf).build(); + restClient.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. + </p> + + <!-- ======================================================================================================== --> + <a id="SSLOpts"></a> + <h4 class='topic' onclick='toggle(this)'>1.1.1 - SSLOpts Bean</h4> + <div class='topic'> + <p> + The {@link com.ibm.juno.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 com.ibm.juno.core.ini.ConfigFile} class. + </p> + <h6 class='figure'>Contents of <code>MyConfig.cfg</code></h6> + <p class='bcode'> + <jc>#================================================================================ + # My Connection Settings + #================================================================================</jc> + [Connection] + 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> + ConfigFile cf = ConfigMgr.<jsf>DEFAULT</jsf>.get(<js>"MyConfig.cfg"</js>); + SSLOpts ssl = cf.getObject(SSLOpts.<jk>class</jk>, <js>"Connection/ssl"</js>); + RestClient rc = <jk>new</jk> RestClient().enableSSL(ssl); + </p> + </div> + </div> + + <!-- ======================================================================================================== --> + <a id="Authentication"></a> + <h3 class='topic' onclick='toggle(this)'>1.2 - Authentication</h3> + <div class='topic'> + + <!-- ======================================================================================================== --> + <a id="BASIC"></a> + <h4 class='topic' onclick='toggle(this)'>1.2.1 - BASIC Authentication</h4> + <div class='topic'> + <p> + The {@link com.ibm.juno.client.RestClient#setBasicAuth(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> RestClient() + .setBasicAuth(<jsf>HOST</jsf>, <jsf>PORT</jsf>, <jsf>USER</jsf>, <jsf>PW</jsf>); + </p> + <p> + This is functionally equivalent to the following: + </p> + <p class='bcode'> + RestClient restClient = <jk>new</jk> RestClient(); + AuthScope scope = <jk>new</jk> AuthScope(<jsf>HOST</jsf>, <jsf>PORT</jsf>); + Credentials up = <jk>new</jk> UsernamePasswordCredentials(<jsf>USER</jsf>, <jsf>PW</jsf>); + CredentialsProvider p = <jk>new</jk> BasicCredentialsProvider(); + p.setCredentials(scope, up); + restClient.setDefaultCredentialsProvider(p); + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="FORM"></a> + <h4 class='topic' onclick='toggle(this)'>1.2.2 - FORM-based Authentication</h4> + <div class='topic'> + <p> + The {@link com.ibm.juno.client.RestClient} 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 com.ibm.juno.client.RestClient} and override the {@link com.ibm.juno.client.RestClient#createHttpClient()} + method to provide an authenticated client. + </p> + <p> + The following example shows how the {@link com.ibm.juno.client.jazz.JazzRestClient} class provides + FORM-based authentication support. + </p> + <p class='bcode'> + <jd>/** + * Constructor. + */</jd> + <jk>public</jk> JazzRestClient(URI jazzUri, String user, String pw) <jk>throws</jk> IOException { + ... + } + + <jd>/** + * Override the createHttpClient() method to return an authenticated client. + */</jd> + <ja>@Override</ja> <jc>/* RestClient */</jc> + <jk>protected</jk> CloseableHttpClient createHttpClient() <jk>throws</jk> Exception { + CloseableHttpClient client = <jk>super</jk>.createHttpClient(); + formBasedAuthenticate(client); + visitAuthenticatedURL(client); + <jk>return</jk> client; + } + + <jc>/* + * Performs form-based authentication against the Jazz server. + */</jc> + <jk>private void</jk> formBasedAuthenticate(HttpClient client) <jk>throws</jk> IOException { + + URI uri2 = <jf>jazzUri</jf>.resolve(<js>"j_security_check"</js>); + HttpPost request = <jk>new</jk> HttpPost(uri2); + request.setConfig(RequestConfig.<jsm>custom</jsm>().setRedirectsEnabled(<jk>false</jk>).build()); + + <jc>// Charset must explicitly be set to UTF-8 to handle user/pw with non-ascii characters.</jc> + request.addHeader(<js>"Content-Type"</js>, <js>"application/x-www-form-urlencoded; charset=utf-8"</js>); + + NameValuePairs params = <jk>new</jk> NameValuePairs() + .append(<jk>new</jk> BasicNameValuePair(<js>"j_username""</js>, <jf>user</jf>)) + .append(<jk>new</jk> BasicNameValuePair(<js>"j_password"</js>, <jf>pw</jf>)); + request.setEntity(<jk>new</jk> UrlEncodedFormEntity(params)); + + HttpResponse response = client.execute(request); + <jk>try</jk> { + <jk>int</jk> rc = response.getStatusLine().getStatusCode(); + + Header authMsg = response.getFirstHeader(<js>"X-com-ibm-team-repository-web-auth-msg"</js>); + <jk>if</jk> (authMsg != <jk>null</jk>) + <jk>throw new</jk> IOException(authMsg.getValue()); + + <jc>// The form auth request should always respond with a 200 ok or 302 redirect code</jc> + <jk>if</jk> (rc == <jsf>SC_MOVED_TEMPORARILY</jsf>) { + <jk>if</jk> (response.getFirstHeader(<js>"Location"</js>).getValue().matches(<js>"^.*/auth/authfailed.*$"</js>)) + <jk>throw new</jk> IOException(<js>"Invalid credentials."</js>); + } <jk>else if</jk> (rc != <jsf>SC_OK</jsf>) { + <jk>throw new</jk> IOException(<js>"Unexpected HTTP status: "</js> + rc); + } + } <jk>finally</jk> { + EntityUtils.<jsm>consume</jsm>(response.getEntity()); + } + } + + <jc>/* + * This is needed for Tomcat because it responds with SC_BAD_REQUEST when the j_security_check URL is visited before an + * authenticated URL has been visited. This same URL must also be visited after authenticating with j_security_check + * otherwise tomcat will not consider the session authenticated + */</jc> + <jk>private int</jk> visitAuthenticatedURL(HttpClient httpClient) <jk>throws</jk> IOException { + HttpGet authenticatedURL = <jk>new</jk> HttpGet(<jf>jazzUri</jf>.resolve(<js>"authenticated/identity"</js>)); + HttpResponse response = httpClient.execute(authenticatedURL); + <jk>try</jk> { + <jk>return</jk> response.getStatusLine().getStatusCode(); + } <jk>finally</jk> { + EntityUtils.<jsm>consume</jsm>(response.getEntity()); + } + } + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="OIDC"></a> + <h4 class='topic' onclick='toggle(this)'>1.2.3 - OIDC Authentication</h4> + <div class='topic'> + <p> + The following example shows how the {@link com.ibm.juno.client.jazz.JazzRestClient} class provides + OIDC authentication support. + </p> + <p class='bcode'> + <jd>/** + * Constructor. + */</jd> + <jk>public</jk> JazzRestClient(URI jazzUri, String user, String pw) <jk>throws</jk> IOException { + ... + } + + <jd>/** + * Override the createHttpClient() method to return an authenticated client. + */</jd> + <ja>@Override</ja> <jc>/* RestClient */</jc> + <jk>protected</jk> CloseableHttpClient createHttpClient() <jk>throws</jk> Exception { + CloseableHttpClient client = <jk>super</jk>.createHttpClient(); + oidcAuthenticate(client); + <jk>return</jk> client; + } + + <jk>private void</jk> oidcAuthenticate(HttpClient client) <jk>throws</jk> IOException { + + HttpGet request = <jk>new</jk> HttpGet(<jf>jazzUri</jf>); + request.setConfig(RequestConfig.<jsm>custom</jsm>().setRedirectsEnabled(<jk>false</jk>).build()); + + <jc>// Charset must explicitly be set to UTF-8 to handle user/pw with non-ascii characters.</jc> + request.addHeader(<js>"Content-Type"</js>, <js>"application/x-www-form-urlencoded; charset=utf-8"</js>); + + HttpResponse response = client.execute(request); + <jk>try</jk> { + <jk>int</jk> code = response.getStatusLine().getStatusCode(); + + <jc>// Already authenticated</jc> + <jk>if</jk> (code == <jsf>SC_OK</jsf>) + <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()); + + <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()); + + <jc>// Handle Bearer Challenge</jc> + HttpGet method = <jk>new</jk> HttpGet(redirectUri + <js>"&prompt=none"</js>); + addDefaultOidcHeaders(method); + + response = client.execute(method); + + 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()); + + 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()); + + method = <jk>new</jk> HttpGet(redirectUri + <js>"&prompt=none"</js>); + + addDefaultOidcHeaders(method); + response = client.execute(method); + + 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()); + + <jc>// Handle JAS Challenge</jc> + method = <jk>new</jk> HttpGet(redirectUri); + addDefaultOidcHeaders(method); + + response = client.execute(method); + + 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()); + + <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>"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>"Cookie"</js>, cookie) + }; + + setDefaultHeaders(Arrays.<jsm>asList</jsm>(defaultHeaders)); + + } <jk>finally</jk> { + EntityUtils.<jsm>consume</jsm>(response.getEntity()); + } + } + + <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>"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>"Cookie"</js>, cookie); + } + } + </p> + </div> + </div> + + <!-- ======================================================================================================== --> + <a id="ResponsePatterns"></a> + <h3 class='topic' onclick='toggle(this)'>1.3 - Using Response Patterns</h3> + <div class='topic'> + <p> + One issue with REST (and HTTP in general) is that the HTTP response code must be set as a header before the + body of the request is sent. This can be problematic when REST calls invoke long-running processes, pipes + 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>). + </p> + <p> + The {@link com.ibm.juno.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 com.ibm.juno.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> + restClient.doPost(<jsf>URL</jsf>) + .successPattern(<js>"SUCCESS"</js>) + .run(); + </p> + <p> + The {@link com.ibm.juno.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> + restClient.doPost(<jsf>URL</jsf>) + .failurePattern(<js>"FAILURE|ERROR"</js>) + .run(); + </p> + <p> + These convenience methods are specialized methods that use the {@link com.ibm.juno.client.RestCall#addResponsePattern(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. + </p> + <h6 class='topic'>Example:</h6> + <p class='bcode'> + <jk>final</jk> List<Number> xList = <jk>new</jk> ArrayList<Number>(); + <jk>final</jk> List<String> yList = <jk>new</jk> ArrayList<String>(); + + String responseText = restClient.doGet(<jsf>URL</jsf>) + .addResponsePattern( + <jk>new</jk> ResponsePattern(<js>"x=(\\d+)"</js>) { + <ja>@Override</ja> + <jk>public void</jk> onMatch(RestCall restCall, Matcher m) <jk>throws</jk> RestCallException { + xList.add(Integer.<jsm>parseInt</jsm>(m.group(1))); + } + <ja>@Override</ja> + <jk>public void</jk> onNoMatch(RestCall restCall) <jk>throws</jk> RestCallException { + <jk>throw new</jk> RestCallException(<js>"No X's found!"</js>); + } + } + ) + .addResponsePattern( + <jk>new</jk> ResponsePattern(<js>"y=(\\S+)"</js>) { + <ja>@Override</ja> + <jk>public void</jk> onMatch(RestCall restCall, Matcher m) <jk>throws</jk> RestCallException { + yList.add(m.group(1)); + } + <ja>@Override</ja> + <jk>public void</jk> onNoMatch(RestCall restCall) <jk>throws</jk> RestCallException { + <jk>throw new</jk> RestCallException(<js>"No Y's found!"</js>); + } + } + ) + .getResponseAsString(); + </p> + <p> + Using response patterns does not affect the functionality of any of the other methods + used to retrieve the response such as {@link com.ibm.juno.client.RestCall#getResponseAsString()} or {@link com.ibm.juno.client.RestCall#getResponse(Class)}.<br> + HOWEVER, if you want to retrieve the entire text of the response from inside the match methods, + use {@link com.ibm.juno.client.RestCall#getCapturedResponse()} since this method will not absorb the response for those other methods. + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="#PipingOutput"></a> + <h3 class='topic' onclick='toggle(this)'>1.4 - Piping Response Output</h3> + <div class='topic'> + <p> + The {@link com.ibm.juno.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 com.ibm.juno.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. + </p> + <h6 class='topic'>Example:</h6> + <p class='bcode'> + <jc>// Pipe output from REST call to System.out in real-time.</jc> + restClient.doPost(<jsf>URL</jsf>).byLines().pipeTo(<jk>new</jk> PrintWriter(System.<jk>out</jk>)).run(); + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="Logging"></a> + <h3 class='topic' onclick='toggle(this)'>1.5 - Logging</h3> + <div class='topic'> + <p> + Use the {@link com.ibm.juno.client.RestClient#logTo(Level,Logger)} and {@link com.ibm.juno.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> + <jk>int</jk> rc = restClient.doGet(<jsf>URL</jsf>).logTo(<jsf>INFO</jsf>, getLogger()).run(); + </p> + <p> + 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 com.ibm.juno.client.RestCallLogger} class and using the + {@link com.ibm.juno.client.RestCall#addInterceptor(RestCallInterceptor)} method. + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="Interceptors"></a> + <h3 class='topic' onclick='toggle(this)'>1.6 - Interceptors</h3> + <div class='topic'> + <p> + The {@link com.ibm.juno.client.RestClient#addInterceptor(RestCallInterceptor)} and {@link com.ibm.juno.client.RestCall#addInterceptor(RestCallInterceptor)} methods + can be used to intercept responses during specific connection lifecycle events. + </p> + <p> + The {@link com.ibm.juno.client.RestCallLogger} class is an example of an interceptor that uses the various lifecycle methods + to log HTTP requests. + </p> + <p class='bcode'> + <jd>/** + * Specialized interceptor for logging calls to a log file. + */</jd> + <jk>public class</jk> RestCallLogger <jk>extends</jk> RestCallInterceptor { + + <jk>private</jk> Level <jf>level</jf>; + <jk>private</jk> Logger <jf>log</jf>; + + <jd>/** + * Constructor. + * + * <ja>@param</ja> level The log level to log messages at. + * <ja>@param</ja> log The logger to log to. + */</jd> + <jk>protected</jk> RestCallLogger(Level level, Logger log) { + <jk>this</jk>.<jf>level</jf> = level; + <jk>this</jk>.<jf>log</jf> = log; + } + + <ja>@Override</ja> <jc>/* RestCallInterceptor */</jc> + <jk>public void</jk> onInit(RestCall restCall) { + <jk>if</jk> (<jf>log</jf>.isLoggable(<jf>level</jf>)) + restCall.captureResponse(); + } + + <ja>@Override</ja> <jc>/* RestCallInterceptor */</jc> + <jk>public void</jk> onConnect(RestCall restCall, <jk>int</jk> statusCode, HttpRequest req, HttpResponse res) { + <jc>// Do nothing.</jc> + } + + <ja>@Override</ja> <jc>/* RestCallInterceptor */</jc> + <jk>public void</jk> onRetry(RestCall restCall, <jk>int</jk> statusCode, HttpRequest req, HttpResponse res) { + <jk>if</jk> (<jf>log</jf>.isLoggable(<jf>level</jf>)) + <jf>log</jf>.log(level, MessageFormat.<jsm>format</jsm>(<js>"Call to {0} returned {1}. Will retry."</js>, req.getRequestLine().getUri(), statusCode)); + } + + <ja>@Override</ja> <jc>/* RestCallInterceptor */</jc> + <jk>public void</jk> onClose(RestCall restCall) <jk>throws</jk> RestCallException { + <jk>try</jk> { + <jk>if</jk> (<jf>log</jf>.isLoggable(<jf>level</jf>)) { + String output = restCall.getCapturedResponse(); + StringBuilder sb = <jk>new</jk> StringBuilder(); + HttpUriRequest req = restCall.getRequest(); + HttpResponse res = restCall.getResponse(); + <jk>if</jk> (req != <jk>null</jk>) { + sb.append(<js>"\n=== HTTP Call =================================================================="</js>); + + sb.append(<js>"\n=== REQUEST ===\n"</js>).append(req); + sb.append(<js>"\n---request headers---"</js>); + <jk>for</jk> (Header h : req.getAllHeaders()) + sb.append(<js>"\n"</js>).append(h); + <jk>if</jk> (req <jk>instanceof</jk> HttpEntityEnclosingRequestBase) { + sb.append(<js>"\n---request entity---"</js>); + HttpEntityEnclosingRequestBase req2 = (HttpEntityEnclosingRequestBase)req; + HttpEntity e = req2.getEntity(); + <jk>if</jk> (e == <jk>null</jk>) + sb.append(<js>"\nEntity is null"</js>); + <jk>else</jk> { + <jk>if</jk> (e.getContentType() != <jk>null</jk>) + sb.append(<js>"\n"</js>).append(e.getContentType()); + <jk>if</jk> (e.getContentEncoding() != <jk>null</jk>) + sb.append(<js>"\n"</js>).append(e.getContentEncoding()); + <jk>if</jk> (e.isRepeatable()) { + <jk>try</jk> { + sb.append(<js>"\n---request content---\n"</js>).append(EntityUtils.<jsm>toString</jsm>(e)); + } <jk>catch</jk> (Exception ex) { + <jk>throw new</jk> RuntimeException(ex); + } + } + } + } + } + <jk>if</jk> (res != <jk>null</jk>) { + sb.append(<js>"\n=== RESPONSE ===\n"</js>).append(res.getStatusLine()); + sb.append(<js>"\n---response headers---"</js>); + <jk>for</jk> (Header h : res.getAllHeaders()) + sb.append(<js>"\n"</js>).append(h); + sb.append(<js>"\n---response content---\n"</js>).append(output); + sb.append(<js>"\n=== END ========================================================================"</js>); + } + <jf>log</jf>.log(<jf>level</jf>, sb.toString()); + } + } <jk>catch</jk> (IOException e) { + <jf>log</jf>.log(Level.<jsf>SEVERE</jsf>, e.getLocalizedMessage(), e); + } + } + } + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="Remoteable"></a> + <h3 class='topic' onclick='toggle(this)'>1.7 - Remotable Proxies</h3> + <div class='topic'> + <p> + Juno 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. + </p> + <p> + Proxy interfaces are retrieved using the {@link com.ibm.juno.client.RestClient#getRemoteableProxy(Class)} method. + The {@link com.ibm.juno.client.RestClient#setRemoteableServletUri(String)} method is used to specify the location + of the remoteable services servlet running on the server. + The remoteable servlet is a specialized subclass of {@link com.ibm.juno.server.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)... + <p class='bcode'> + <jk>public interface</jk> IAddressBook { + Person createPerson(CreatePerson cp) <jk>throws</jk> Exception; + } + </p> + <p> + The client side code for invoking this method is shown below... + </p> + <p class='bcode'> + <jc>// Create a RestClient using JSON for serialization, and point to the server-side remoteable servlet.</jc> + RestClient client = <jk>new</jk> RestClient(JsonSerializer.<jk>class</jk>, JsonParser.<jk>class</jk>) + .setRemoteableServletUri(<js>"https://localhost:9080/juno/sample/remoteable";</js>); + + <jc>// Create a proxy interface.</jc> + IAddressBook ab = client.getRemoteableProxy(IAddressBook.<jk>class</jk>); + + <jc>// Invoke a method on the server side and get the returned result.</jc> + Person p = ab.createPerson( + <jk>new</jk> CreatePerson(<js>"Test Person"</js>, + AddressBook.<jsm>toCalendar</jsm>(<js>"Aug 1, 1999"</js>), + <jk>new</jk> CreateAddress(<js>"Test street"</js>, <js>"Test city"</js>, <js>"Test state"</js>, 12345, <jk>true</jk>)) + ); + </p> + <p> + The requirements for a method to be callable through a remoteable service are: + <ul> + <li>The method must be public. + <li>The parameter and return types must be <a href='../../../../com/ibm/juno/core/package-summary.html#PojoCategories'><u>serializable and parsable</u></a>. + </ul> + </p> + <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. + </p> + <p> + See {@link com.ibm.juno.server.remoteable} for more information. + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="Other"></a> + <h3 class='topic' onclick='toggle(this)'>1.8 - Other Useful Methods</h3> + <div class='topic'> + <p> + The {@link com.ibm.juno.client.RestClient#setRootUrl(String)} 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> + RestClient rc = <jk>new</jk> RestClient().setRootUrl(<js>"http://localhost:9080/foobar";</js>); + String r = rc.doGet(<js>"/baz"</js>).getResponseAsString(); <jc>// Gets "http://localhost:9080/foobar/baz";</jc> + </p> + <p> + The {@link com.ibm.juno.client.RestClient#setProperty(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 com.ibm.juno.core.BeanContextProperties#BEAN_ignoreUnknownBeanProperties} property. + </p> + <p class='bcode'> + <jc>// Create a rest client that ignores unknown fields in the response</jc> + RestClient rc = <jk>new</jk> RestClient(JsonSerializer.<jk>class</jk>, JsonParser.<jk>class</jk>) + .setProperty(<jsf>BEAN_ignoreUnknownBeanProperties</jsf>, <jk>true</jk>); + MyPojo myPojo = rc.doGet(<jsf>URL</jsf>).getResponse(MyPojo.<jk>class</jk>); + </p> + <p> + The {@link com.ibm.juno.client.RestCall#setRetryable(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 + // or a 400+ is received.</jc> + restClient.doGet(<jsf>URL</jsf>) + .setRetryable(180, 10000, RetryOn.<jsf>DEFAULT</jsf>) + .run(); + </p> + </div> +</div> +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/.classpath ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/.classpath b/com.ibm.team.juno.microservice.template/.classpath new file mode 100755 index 0000000..e506ff2 --- /dev/null +++ b/com.ibm.team.juno.microservice.template/.classpath @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> +<classpath> + <classpathentry kind="src" path="src"/> + <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.6"/> + <classpathentry combineaccessrules="false" kind="src" path="/com.ibm.team.juno"/> + <classpathentry combineaccessrules="false" kind="src" path="/com.ibm.team.juno.client"/> + <classpathentry combineaccessrules="false" kind="src" path="/com.ibm.team.juno.microservice"/> + <classpathentry combineaccessrules="false" kind="src" path="/com.ibm.team.juno.server"/> + <classpathentry kind="output" path="bin"/> +</classpath> http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/.project ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/.project b/com.ibm.team.juno.microservice.template/.project new file mode 100755 index 0000000..bd71c23 --- /dev/null +++ b/com.ibm.team.juno.microservice.template/.project @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8"?> +<projectDescription> + <name>com.ibm.team.juno.microservice.template</name> + <comment></comment> + <projects> + </projects> + <buildSpec> + <buildCommand> + <name>org.eclipse.jdt.core.javabuilder</name> + <arguments> + </arguments> + </buildCommand> + </buildSpec> + <natures> + <nature>org.eclipse.jdt.core.javanature</nature> + </natures> +</projectDescription> http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/.settings/org.eclipse.jdt.core.prefs ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/.settings/org.eclipse.jdt.core.prefs b/com.ibm.team.juno.microservice.template/.settings/org.eclipse.jdt.core.prefs new file mode 100755 index 0000000..54e493c --- /dev/null +++ b/com.ibm.team.juno.microservice.template/.settings/org.eclipse.jdt.core.prefs @@ -0,0 +1,11 @@ +eclipse.preferences.version=1 +org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled +org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.6 +org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve +org.eclipse.jdt.core.compiler.compliance=1.6 +org.eclipse.jdt.core.compiler.debug.lineNumber=generate +org.eclipse.jdt.core.compiler.debug.localVariable=generate +org.eclipse.jdt.core.compiler.debug.sourceFile=generate +org.eclipse.jdt.core.compiler.problem.assertIdentifier=error +org.eclipse.jdt.core.compiler.problem.enumIdentifier=error +org.eclipse.jdt.core.compiler.source=1.6 http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/META-INF/MANIFEST.MF ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/META-INF/MANIFEST.MF b/com.ibm.team.juno.microservice.template/META-INF/MANIFEST.MF new file mode 100755 index 0000000..1e8d419 --- /dev/null +++ b/com.ibm.team.juno.microservice.template/META-INF/MANIFEST.MF @@ -0,0 +1,18 @@ +Manifest-Version: 1.0 +Main-Class: com.ibm.juno.microservice.RestMicroservice +Rest-Resources: + com.ibm.juno.microservice.sample.RootResources +Main-ConfigFile: microservice.cfg +Class-Path: + lib/commons-codec-1.9.jar + lib/commons-io-1.2.jar + lib/commons-logging-1.1.1.jar + lib/httpclient-4.5.jar + lib/httpcore-4.4.1.jar + lib/httpmime-4.5.jar + lib/javax.servlet-api-3.0.jar + lib/jetty-all-8.1.0.jar + lib/juno-all-5.2.jar + lib/org.apache.commons.fileupload_1.3.1.jar + + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/HelloWorldResource.class ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/HelloWorldResource.class b/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/HelloWorldResource.class new file mode 100644 index 0000000..458fd52 Binary files /dev/null and b/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/HelloWorldResource.class differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/RootResources.class ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/RootResources.class b/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/RootResources.class new file mode 100644 index 0000000..ef2ac44 Binary files /dev/null and b/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/RootResources.class differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/nls/Messages.properties ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/nls/Messages.properties b/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/nls/Messages.properties new file mode 100755 index 0000000..62b3f1a --- /dev/null +++ b/com.ibm.team.juno.microservice.template/bin/com/ibm/juno/microservice/sample/nls/Messages.properties @@ -0,0 +1,14 @@ +############################################################################### +# Licensed Materials - Property of IBM +# (c) Copyright IBM Corporation 2015, 2016. All Rights Reserved. +# +# Note to U.S. Government Users Restricted Rights: +# Use, duplication or disclosure restricted by GSA ADP Schedule +# Contract with IBM Corp. +############################################################################### + +#-------------------------------------------------------------------------------- +# RootResources +#-------------------------------------------------------------------------------- +RootResources.label = Juno Microservice Template +RootResources.description = Template for creating REST microservices http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/microservice.cfg ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/microservice.cfg b/com.ibm.team.juno.microservice.template/microservice.cfg new file mode 100755 index 0000000..95094ed --- /dev/null +++ b/com.ibm.team.juno.microservice.template/microservice.cfg @@ -0,0 +1,196 @@ +#================================================================================ +# Basic configuration file for SaaS microservices +# Subprojects can use this as a starting point. +#================================================================================ + +#================================================================================ +# Services +#================================================================================ +[Services] +REST = com.ibm.juno.microservice.rest.RestApplication + +#================================================================================ +# REST settings +#================================================================================ +[REST] + +# The HTTP port number to use. +# Default is Rest-Port setting in manifest file, or 8000. +port = 10000 + +# A JSON map of servlet paths to servlet classes. +# Example: +# resourceMap = {'/*':'com.ibm.MyServlet'} +# Either resourceMap or resources must be specified if it's not defined in +# the manifest file. +resourceMap = + +# A comma-delimited list of names of classes that extend from Servlet. +# Resource paths are pulled from @RestResource.path() annotation, or +# "/*" if annotation not specified. +# Example: +# resources = com.ibm.MyServlet +# Default is Rest-Resources in manifest file. +# Either resourceMap or resources must be specified if it's not defined in +# the manifest file. +resources = + +# The context root of the Jetty server. +# Default is Rest-ContextPath in manifest file, or "/". +contextPath = + +# Authentication: NONE, BASIC. +# Default is Rest-AuthType in manifest file, or NONE. +authType = NONE + +# The BASIC auth username. +# Default is Rest-LoginUser in manifest file. +loginUser = + +# The BASIC auth password. +# Default is Rest-LoginPassword in manifest file. +loginPassword = + +# The BASIC auth realm. +# Default is Rest-AuthRealm in manifest file. +authRealm = + +# Stylesheet to use for HTML views. +# The default options are: +# - styles/juno.css +# - styles/devops.css +# Other stylesheets can be referenced relative to the servlet package or working +# directory. +stylesheet = styles/devops.css + +# What to do when the config file is saved. +# Possible values: +# NOTHING - Don't do anything. (default) +# RESTART_SERVER - Restart the Jetty server. +# RESTART_SERVICE - Shutdown and exit with code '3'. +saveConfigAction = RESTART_SERVER + +# Enable SSL support. +# Default is false. +useSsl = false + +#================================================================================ +# Bean properties on the org.eclipse.jetty.util.ssl.SslSocketFactory class +#-------------------------------------------------------------------------------- +# Ignored if REST/useSsl is false. +# Specify any of the following fields: +# allowRenegotiate (boolean) +# certAlias (String) +# crlPath (String) +# enableCRLDP (boolean) +# enableOCSP (boolean) +# excludeCipherSuites (String[]) +# excludeProtocols (String[]) +# includeCipherSuites (String[]) +# includeProtocols (String...) +# keyManagerPassword (String) +# keyStore (String) +# keyStorePassword (String) +# keyStorePath (String) +# keyStoreProvider (String) +# keyStoreType (String) +# maxCertPathLength (int) +# needClientAuth (boolean) +# ocspResponderURL (String) +# protocol (String) +# provider (String) +# secureRandomAlgorithm (String) +# sessionCachingEnabled (boolean) +# sslKeyManagerFactoryAlgorithm (String) +# sslSessionCacheSize (int) +# sslSessionTimeout (int) +# trustAll (boolean) +# trustManagerFactoryAlgorithm (String) +# trustStore (String) +# trustStorePassword (String) +# trustStoreProvider (String) +# trustStoreType (String) +# validateCerts (boolean) +# validatePeerCerts (boolean) +# wantClientAuth (boolean) +#================================================================================ +[REST-SslContextFactory] +keyStorePath = client_keystore.jks +keyStorePassword* = {HRAaRQoT} +excludeCipherSuites = TLS_DHE.*, TLS_EDH.* +excludeProtocols = SSLv3 +allowRenegotiate = false + +#================================================================================ +# Logger settings +# See FileHandler Java class for details. +#================================================================================ +[Logging] + +# The directory where to create the log file. +# Default is "." +logDir = logs + +# The name of the log file to create for the main logger. +# The logDir and logFile make up the pattern that's passed to the FileHandler +# constructor. +# If value is not specified, then logging to a file will not be set up. +logFile = microservice.%g.log + +# Whether to append to the existing log file or create a new one. +# Default is false. +append = + +# The SimpleDateFormat format to use for dates. +# Default is "yyyy.MM.dd hh:mm:ss". +dateFormat = + +# The log message format. +# The value can contain any of the following variables: +# {date} - The date, formatted per dateFormat. +# {class} - The class name. +# {method} - The method name. +# {logger} - The logger name. +# {level} - The log level name. +# {msg} - The log message. +# {threadid} - The thread ID. +# {exception} - The localized exception message. +# Default is "[{date} {level}] {msg}%n". +format = + +# The maximum log file size. +# Suffixes available for numbers. +# See ConfigFile.getInt(String,int) for details. +# Default is 1M. +limit = 10M + +# Max number of log files. +# Default is 1. +count = 5 + +# Default log levels. +# Keys are logger names. +# Values are serialized Level POJOs. +levels = { com.ibm.juno:'INFO' } + +# Only print unique stack traces once and then refer to them by a simple 8 character hash identifier. +# Useful for preventing log files from filling up with duplicate stack traces. +# Default is false. +useStackTraceHashes = true + +# The default level for the console logger. +# Default is WARNING. +consoleLevel = + +#================================================================================ +# System properties +#-------------------------------------------------------------------------------- +# These are arbitrary system properties that are set during startup. +#================================================================================ +[SystemProperties] + +# Configure Jetty for StdErrLog Logging +org.eclipse.jetty.util.log.class = org.eclipse.jetty.util.log.StrErrLog + +# Jetty logging level +org.eclipse.jetty.LEVEL = WARN http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/project-root/.classpath ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/project-root/.classpath b/com.ibm.team.juno.microservice.template/project-root/.classpath new file mode 100755 index 0000000..2563b9e --- /dev/null +++ b/com.ibm.team.juno.microservice.template/project-root/.classpath @@ -0,0 +1,16 @@ +<?xml version="1.0" encoding="UTF-8"?> +<classpath> + <classpathentry kind="src" path="src"/> + <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.6"/> + <classpathentry exported="true" kind="lib" path="lib/commons-codec-1.9.jar"/> + <classpathentry exported="true" kind="lib" path="lib/commons-io-1.2.jar"/> + <classpathentry exported="true" kind="lib" path="lib/commons-logging-1.1.1.jar"/> + <classpathentry exported="true" kind="lib" path="lib/httpclient-4.5.jar"/> + <classpathentry exported="true" kind="lib" path="lib/httpcore-4.4.1.jar"/> + <classpathentry exported="true" kind="lib" path="lib/httpmime-4.5.jar"/> + <classpathentry exported="true" kind="lib" path="lib/javax.servlet-api-3.0.jar"/> + <classpathentry exported="true" kind="lib" path="lib/jetty-all-8.1.0.jar"/> + <classpathentry exported="true" kind="lib" path="lib/juno-all-5.2.jar"/> + <classpathentry exported="true" kind="lib" path="lib/org.apache.commons.fileupload_1.3.1.jar"/> + <classpathentry kind="output" path="bin"/> +</classpath> http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/project-root/.project ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/project-root/.project b/com.ibm.team.juno.microservice.template/project-root/.project new file mode 100755 index 0000000..358082d --- /dev/null +++ b/com.ibm.team.juno.microservice.template/project-root/.project @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8"?> +<projectDescription> + <name>microservice-project</name> + <comment></comment> + <projects> + </projects> + <buildSpec> + <buildCommand> + <name>org.eclipse.jdt.core.javabuilder</name> + <arguments> + </arguments> + </buildCommand> + </buildSpec> + <natures> + <nature>org.eclipse.jdt.core.javanature</nature> + </natures> +</projectDescription> http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/project-root/build.properties ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/project-root/build.properties b/com.ibm.team.juno.microservice.template/project-root/build.properties new file mode 100755 index 0000000..a2aad00 --- /dev/null +++ b/com.ibm.team.juno.microservice.template/project-root/build.properties @@ -0,0 +1,15 @@ +############################################################################### +# +# Licensed Materials - Property of IBM +# (c) Copyright IBM Corporation 2015, 2016. All Rights Reserved. +# +# Note to U.S. Government Users Restricted Rights: +# Use, duplication or disclosure restricted by GSA ADP Schedule +# Contract with IBM Corp. +# +############################################################################### + +jar = microservice.jar +zip = microservice.zip + + http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/project-root/build.xml ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/project-root/build.xml b/com.ibm.team.juno.microservice.template/project-root/build.xml new file mode 100755 index 0000000..1ca6997 --- /dev/null +++ b/com.ibm.team.juno.microservice.template/project-root/build.xml @@ -0,0 +1,50 @@ +<?xml version='1.0'?> +<!-- + Licensed Materials - Property of IBM + (c) Copyright IBM Corporation 2015, 2016. All Rights Reserved. + + Note to U.S. Government Users Restricted Rights: + Use, duplication or disclosure restricted by GSA ADP Schedule + Contract with IBM Corp. + --> + +<!-- + Provides a VERY basic ANT script for creating a microservice zip file. +--> +<project name='Microservice' default='Microservice.Build'> + + <target name='Microservice.Build'> + <tstamp/> + <loadproperties srcFile='build.properties'/> + + <path id='classpath'> + <fileset dir='lib' includes='*.jar'/> + </path> + + <delete dir='build' quiet='true'/> + + <copy todir='build/bin'> + <fileset dir='src' excludes='**/*.java'/> + </copy> + <copy todir='build/microservice'> + <fileset dir='.' includes='*.cfg,lib/**'/> + </copy> + + <javac srcdir='src' destdir='build/bin' fork='true' source='1.6' target='1.6' debug='true' includeantruntime='false'> + <classpath refid='classpath'/> + </javac> + + <jar jarfile='build/microservice/${jar}' basedir='build/bin' duplicate='fail' level='9' manifest='META-INF/MANIFEST.MF'> + <manifest> + <attribute name='Built-By' value='${user.name}'/> + <attribute name='Build-Date' value='${TODAY}'/> + <attribute name='Bundle-Version' value='${version}'/> + </manifest> + </jar> + + <zip basedir='build/microservice' destfile='build/${zip}'/> + + <delete dir='build/bin' quiet='true'/> + </target> + +</project> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/project-root/microservice-project.launch ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/project-root/microservice-project.launch b/com.ibm.team.juno.microservice.template/project-root/microservice-project.launch new file mode 100755 index 0000000..49785df --- /dev/null +++ b/com.ibm.team.juno.microservice.template/project-root/microservice-project.launch @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<launchConfiguration type="org.eclipse.jdt.launching.localJavaApplication"> + <listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_PATHS"> + <listEntry value="/com.ibm.team.juno.microservice/src/com/ibm/juno/microservice/RestMicroservice.java"/> + </listAttribute> + <listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_TYPES"> + <listEntry value="1"/> + </listAttribute> + <stringAttribute key="org.eclipse.jdt.launching.MAIN_TYPE" value="com.ibm.juno.microservice.RestMicroservice"/> + <stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="microservice-project"/> +</launchConfiguration> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/src/com/ibm/juno/microservice/sample/HelloWorldResource.java ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/src/com/ibm/juno/microservice/sample/HelloWorldResource.java b/com.ibm.team.juno.microservice.template/src/com/ibm/juno/microservice/sample/HelloWorldResource.java new file mode 100755 index 0000000..b2da5d5 --- /dev/null +++ b/com.ibm.team.juno.microservice.template/src/com/ibm/juno/microservice/sample/HelloWorldResource.java @@ -0,0 +1,29 @@ +/******************************************************************************* + * Licensed Materials - Property of IBM + * © Copyright IBM Corporation 2014, 2016. All Rights Reserved. + * + * The source code for this program is not published or otherwise + * divested of its trade secrets, irrespective of what has been + * deposited with the U.S. Copyright Office. + *******************************************************************************/ +package com.ibm.juno.microservice.sample; + +import com.ibm.juno.microservice.*; +import com.ibm.juno.server.annotation.*; + +/** + * Sample REST resource that prints out a simple "Hello world!" message. + */ +@RestResource( + label="Hello World example", + description="Simplest possible REST resource" +) +public class HelloWorldResource extends Resource { + private static final long serialVersionUID = 1L; + + /** GET request handler */ + @RestMethod(name="GET", path="/*") + public String sayHello() { + return "Hello world!"; + } +} http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7e4f63e6/com.ibm.team.juno.microservice.template/src/com/ibm/juno/microservice/sample/RootResources.java ---------------------------------------------------------------------- diff --git a/com.ibm.team.juno.microservice.template/src/com/ibm/juno/microservice/sample/RootResources.java b/com.ibm.team.juno.microservice.template/src/com/ibm/juno/microservice/sample/RootResources.java new file mode 100755 index 0000000..09f60b2 --- /dev/null +++ b/com.ibm.team.juno.microservice.template/src/com/ibm/juno/microservice/sample/RootResources.java @@ -0,0 +1,35 @@ +/******************************************************************************* + * Licensed Materials - Property of IBM + * © Copyright IBM Corporation 2015, 2016. All Rights Reserved. + * + * The source code for this program is not published or otherwise + * divested of its trade secrets, irrespective of what has been + * deposited with the U.S. Copyright Office. + *******************************************************************************/ +package com.ibm.juno.microservice.sample; + +import static com.ibm.juno.core.html.HtmlDocSerializerProperties.*; + +import com.ibm.juno.microservice.*; +import com.ibm.juno.microservice.resources.*; +import com.ibm.juno.server.annotation.*; + +/** + * Root microservice page. + */ +@RestResource( + path="/", + label="Juno Microservice Template", + description="Template for creating REST microservices", + properties={ + @Property(name=HTMLDOC_links, value="{options:'$R{servletURI}?method=OPTIONS'}") + }, + children={ + HelloWorldResource.class, + ConfigResource.class, + LogsResource.class + } +) +public class RootResources extends ResourceGroup { + private static final long serialVersionUID = 1L; +}
