Compare commits

..

5 Commits

15 changed files with 245 additions and 108 deletions

34
pom.xml
View File

@ -6,7 +6,7 @@
<groupId>com.inteligr8</groupId>
<artifactId>common-rest-client</artifactId>
<version>2.0-SNAPSHOT</version>
<version>3.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>ReST API Client for Java</name>
@ -40,19 +40,19 @@
<properties>
<project.build.sourceEncoding>utf-8</project.build.sourceEncoding>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
<junit.version>5.7.2</junit.version>
<spring.version>5.3.27</spring.version>
<jackson.version>2.15.1</jackson.version>
<junit.version>5.12.0</junit.version>
<spring.version>6.0.23</spring.version>
<jackson.version>2.17.3</jackson.version>
</properties>
<dependencies>
<dependency>
<groupId>javax.annotation</groupId>
<artifactId>javax.annotation-api</artifactId>
<version>1.3.2</version>
<groupId>jakarta.annotation</groupId>
<artifactId>jakarta.annotation-api</artifactId>
<version>2.1.1</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
@ -65,8 +65,8 @@
<version>${jackson.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.jaxrs</groupId>
<artifactId>jackson-jaxrs-json-provider</artifactId>
<groupId>com.fasterxml.jackson.jakarta.rs</groupId>
<artifactId>jackson-jakarta-rs-json-provider</artifactId>
<version>${jackson.version}</version>
</dependency>
<dependency>
@ -77,17 +77,17 @@
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.14.0</version>
<version>3.17.0</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>1.7.36</version>
<version>2.0.17</version>
</dependency>
<dependency>
<groupId>jakarta.ws.rs</groupId>
<artifactId>jakarta.ws.rs-api</artifactId>
<version>2.1.6</version>
<version>3.1.0</version>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
@ -113,7 +113,7 @@
<plugins>
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.1.0</version>
<version>3.4.0</version>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
@ -124,7 +124,7 @@
</plugin>
<plugin>
<artifactId>maven-failsafe-plugin</artifactId>
<version>3.1.0</version>
<version>3.4.0</version>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
@ -180,7 +180,7 @@
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<version>1.6.13</version>
<version>1.6.14</version>
<configuration>
<serverId>ossrh</serverId>
<nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>

View File

@ -14,7 +14,7 @@
*/
package com.inteligr8.rs;
import javax.ws.rs.client.ClientRequestFilter;
import jakarta.ws.rs.client.ClientRequestFilter;
/**
* This is a marker that allows the developer to segregate, restrict, or limit

View File

@ -17,8 +17,8 @@ package com.inteligr8.rs;
import java.io.UnsupportedEncodingException;
import java.util.Base64;
import javax.ws.rs.client.ClientRequestContext;
import javax.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.core.HttpHeaders;
import org.apache.commons.lang3.StringUtils;
@ -34,6 +34,8 @@ public class BasicAuthorizationFilter implements AuthorizationFilter {
private final String password;
/**
* This constructor instantiates the filter with required fields.
*
* @param username A username or access key.
* @param password A password or secret key.
*/

View File

@ -14,8 +14,8 @@
*/
package com.inteligr8.rs;
import javax.ws.rs.client.ClientRequestContext;
import javax.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.core.HttpHeaders;
/**
* This class implements a simple long living or proxied token-based
@ -32,6 +32,8 @@ public class BearerTokenAuthorizationFilter implements AuthorizationFilter {
private final String token;
/**
* This constructor instantiates the filter with required fields.
*
* @param token A 'Bearer' token.
*/
public BearerTokenAuthorizationFilter(String token) {

View File

@ -16,34 +16,39 @@ package com.inteligr8.rs;
import java.util.concurrent.TimeUnit;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;
import jakarta.ws.rs.client.ClientBuilder;
import jakarta.ws.rs.client.WebTarget;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider;
import com.fasterxml.jackson.jakarta.rs.json.JacksonJsonProvider;
/**
* A class that provides pre-configured JAX-RS Client &amp; WebTarget objects.
* A class that provides pre-configured Jakarta RS Client &amp; WebTarget objects.
*
* @author brian@inteligr8.com
*/
public abstract class Client {
private final Object sync = new Object();
private javax.ws.rs.client.Client client;
private jakarta.ws.rs.client.Client client;
/**
* This method retrieves the configuration for the client.
*
* @return The client configuration.
*/
public abstract ClientConfiguration getConfig();
/**
* @return A pre-configured JAX-RS client (no URL) with configured authorization.
* This method retrieves an anonymous cached instance of the underlying
* Jakarta RS client.
*
* @return A pre-configured Jakarta RS client (no URL) with configured authorization.
*/
public final javax.ws.rs.client.Client getClient() {
public final jakarta.ws.rs.client.Client getClient() {
synchronized (this.sync) {
if (this.client == null)
this.client = this.buildClient((AuthorizationFilter)null);
@ -53,10 +58,13 @@ public abstract class Client {
}
/**
* This method retrieves either an anonymous cached instance or builds an
* authorized instance of the underlying Jakarta RS client.
*
* @param authFilter A dynamic authorization filter.
* @return A pre-configured JAX-RS client (no URL) with the specified authorization.
* @return A pre-configured Jakarta RS client (no URL) with the specified authorization.
*/
public javax.ws.rs.client.Client getClient(AuthorizationFilter authFilter) {
public jakarta.ws.rs.client.Client getClient(AuthorizationFilter authFilter) {
if (authFilter == null) {
return this.getClient();
} else {
@ -65,15 +73,17 @@ public abstract class Client {
}
/**
* This method builds a new Jakarta RS client with optional authorization.
*
* @param authFilter A dynamic authorization filter.
* @return A pre-configured JAX-RS client (no URL) with the specified authorization.
* @return A pre-configured Jakarta RS client (no URL) with the specified authorization.
*/
public final javax.ws.rs.client.Client buildClient(AuthorizationFilter authFilter) {
public final jakarta.ws.rs.client.Client buildClient(AuthorizationFilter authFilter) {
ObjectMapper om = new ObjectMapper();
om.registerModules(new JavaTimeModule());
this.getConfig().configureJacksonMapper(om);
JacksonJaxbJsonProvider provider = new JacksonJaxbJsonProvider(om, JacksonJaxbJsonProvider.DEFAULT_ANNOTATIONS);
JacksonJsonProvider provider = new JacksonJsonProvider(om, JacksonJsonProvider.BASIC_ANNOTATIONS);
this.getConfig().configureJacksonProvider(provider);
if (this.getConfig().isWrapRootValueEnabled())
@ -101,14 +111,19 @@ public abstract class Client {
}
/**
* @param clientBuilder A client builder
* This method allows sub-classes to extend the Jakarta RS client builder
* before the client is built.
*
* @param clientBuilder A Jakarta RS client builder.
*/
public void buildClient(ClientBuilder clientBuilder) {
// for extension purposes
}
/**
* @return A pre-configured JAX-RS target (client w/ base URL) with configured authorization.
* This method builds an anonymous Jakarta RS target.
*
* @return A pre-configured Jakarta RS target (client w/ base URL) with configured authorization.
*/
public final WebTarget getTarget() {
return this.getClient()
@ -116,8 +131,10 @@ public abstract class Client {
}
/**
* This method builds an authorized Jakarta RS target.
*
* @param authFilter A dynamic authorization filter.
* @return A pre-configured JAX-RS target (client w/ base URL) with the specified authorization.
* @return A pre-configured Jakarta RS target (client w/ base URL) with the specified authorization.
*/
public WebTarget getTarget(AuthorizationFilter authFilter) {
if (authFilter == null) {
@ -129,10 +146,10 @@ public abstract class Client {
}
/**
* This method retrieves a JAX-RS implementation of the specified API.
* This method retrieves a Jakarta RS implementation of the specified API.
*
* @param <T> A JAX-RS annotated API class.
* @param apiClass A JAX-RS annotated API class.
* @param <T> A Jakarta RS annotated API class.
* @param apiClass A Jakarta RS annotated API class.
* @return An instance of the API class.
*/
public final <T> T getApi(Class<T> apiClass) {
@ -140,12 +157,12 @@ public abstract class Client {
}
/**
* This method retrieves a JAX-RS implementation of the specified API with
* This method retrieves a Jakarta RS implementation of the specified API with
* the specified authorization.
*
* @param <T> A JAX-RS annotated API class.
* @param <T> A Jakarta RS annotated API class.
* @param authFilter A dynamic authorization filter.
* @param apiClass A JAX-RS annotated API class.
* @param apiClass A Jakarta RS annotated API class.
* @return An instance of the API class.
*/
public abstract <T> T getApi(AuthorizationFilter authFilter, Class<T> apiClass);

View File

@ -16,10 +16,10 @@ package com.inteligr8.rs;
import java.net.URI;
import javax.ws.rs.client.ClientBuilder;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider;
import com.fasterxml.jackson.jakarta.rs.json.JacksonJsonProvider;
import jakarta.ws.rs.client.ClientBuilder;
/**
* This interface defines the configurable parameters of the clients; primarily
@ -30,89 +30,127 @@ import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider;
public interface ClientConfiguration {
/**
* @return The base or root URL of the service.
* This method retrieves the base/root URL of the client service.
*
* @return The URL.
*/
String getBaseUrl();
/**
* @return The username for BASIC authentication.
* This method retrieves the username to use in HTTP BASIC authentication/authorization.
*
* @return A username.
*/
default String getBasicAuthUsername() {
return null;
}
/**
* @return The corresponding password for the username in BASIC authentication.
* This method retrieves the password to use in HTTP BASIC authentication/authorization.
*
* @return The corresponding password for the username.
*/
default String getBasicAuthPassword() {
return null;
}
/**
* @return The client ID for Client Enforcement authentication.
* This method retrieves the client identifier to use in Client Enforcement authorization.
*
* @return A client identifier.
*/
default String getClientId() {
return null;
}
/**
* @return The corresponding client secret for the client ID in Client Enforcement authentication.
* This method retrieves the client secret to use in Client Enforcement authorization.
*
* @return The corresponding client secret for the client identifier.
*/
default String getClientSecret() {
return null;
}
/**
* @return The token for BEARER authorization.
* This method retrieves the token to use in HTTP BEARER authorization.
* This is provided in a response to the token URL.
*
* @return An access token.
*/
default String getBearerToken() {
return null;
}
/**
* @return The token URL for OAuth authorization.
* This method retrieves the token URL to use for OAuth authorization.
* The value can be pulled from OAuth endpoint well-known meta-data. That
* endpoint or the token URL itself may also be provided OAuth IdP
* administrator.
*
* @return An OAuth token URL.
*/
default String getOAuthTokenUrl() {
return null;
}
/**
* @return The client ID provided by the OAuth IdP administrator.
* This method retrieves the client identifier to use in OAuth
* authorization. This is provided by the OAuth IdP administrator or
* tooling.
*
* @return A client identifier.
*/
default String getOAuthClientId() {
return this.getClientId();
}
/**
* @return The corresponding client secret for the client ID provided by the OAuth IdP administrator.
* This method retrieves the client secret to use in OAuth authorization.
* This is provided by the OAuth IdP administrator or tooling.
*
* @return The corresponding client secret for the client identifier.
*/
default String getOAuthClientSecret() {
return this.getClientSecret();
}
/**
* @return The authorization code used in the OAuth Authorization Code flow.
* This method retrieves the authorization code to use in OAuth
* Authorization Code flow. This is provided by the OAuth IdP
* administrator or tooling.
*
* @return An authorization code.
*/
default String getOAuthAuthCode() {
return null;
}
/**
* @return The redirect URL used in the OAuth Authorization Code flow.
* This method retrieves the redirect URL to use in OAuth Authorization
* Code flow. This has meaning to the client-side web application.
*
* @return A URL for the OAuth flow to redirect to when complete.
*/
default String getOAuthAuthRedirectUri() {
return null;
}
/**
* @return The username used in the OAuth Password Grant flow.
* This method retrieves the username to use in OAuth Password Grant flow.
* This is provided by the OAuth IdP administrator or tooling.
*
* @return A username.
*/
default String getOAuthUsername() {
return null;
}
/**
* @return The corresponding password for the username used in the OAuth Password Grant flow.
* This method retrieves the password to use in OAuth Password Grant flow.
* This is provided by the OAuth IdP administrator or tooling.
*
* @return The corresponding password for the username.
*/
default String getOAuthPassword() {
return null;
@ -120,10 +158,22 @@ public interface ClientConfiguration {
/**
* This method retrieves the connection (before request sent) timeout for
* the client.
*
* @return A timeout in milliseconds.
*/
default Integer getConnectTimeoutInMillis() {
return null;
}
/**
* This method retrieves the response (after request sent) timeout for the
* client.
*
* @return A timeout in milliseconds.
*/
default Integer getResponseTimeoutInMillis() {
return null;
}
@ -131,29 +181,38 @@ public interface ClientConfiguration {
/**
* @return true to enable Jackson UNWRAP_ROOT_VALUE feature; false otherwise.
* This method enables/disables the JackSON UNWRAP_ROOT_VALUE feature.
*
* @return `true` to enable; `false` otherwise.
*/
default boolean isUnwrapRootValueEnabled() {
return false;
}
/**
* @return true to enable Jackson WRAP_ROOT_VALUE feature; false otherwise.
* This method enables/disables the JackSON WRAP_ROOT_VALUE feature.
*
* @return `true` to enable; `false` otherwise.
*/
default boolean isWrapRootValueEnabled() {
return false;
}
/**
* @param mapper A Jackson object mapper to configure.
* This method allows sub-classes to extend the JackSON mapper
* configuration and behavior.
*
* @param mapper A JackSON object mapper.
*/
default void configureJacksonMapper(ObjectMapper mapper) {
}
/**
* @param provider A Jackson JAX-RS provider to configure.
* This method allows sub-classes to extend the JackSON JSON provider.
*
* @param provider A JackSON Jakarta RS provider.
*/
default void configureJacksonProvider(JacksonJaxbJsonProvider provider) {
default void configureJacksonProvider(JacksonJsonProvider provider) {
}

View File

@ -14,7 +14,7 @@
*/
package com.inteligr8.rs;
import javax.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.client.ClientRequestContext;
import org.apache.commons.lang3.StringUtils;

View File

@ -14,15 +14,15 @@
*/
package com.inteligr8.rs;
import javax.annotation.PostConstruct;
import javax.ws.rs.client.ClientBuilder;
import jakarta.annotation.PostConstruct;
import jakarta.ws.rs.client.ClientBuilder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* A class that provides pre-configured JAX-RS Client &amp; WebTarget objects
* for Jersey.
* A class that provides pre-configured Jakarta RS Client &amp; WebTarget
* objects.
*
* @author brian@inteligr8.com
*/
@ -34,6 +34,7 @@ public class ClientImpl extends Client {
/**
* This constructor is for Spring or POJO use.
*
* @param config The client configuration.
*/
public ClientImpl(ClientConfiguration config) {
@ -41,36 +42,22 @@ public class ClientImpl extends Client {
}
/**
* This method registers the Jersey library as the default provider for the
* JAX-RS specification.
* This method is a placeholder.
*/
@PostConstruct
public void register() {
this.logger.info("API Base URL: {}", this.getConfig().getBaseUrl());
}
/**
* @param clientBuilder A client builder.
*/
@Override
public void buildClient(ClientBuilder clientBuilder) {
}
/**
* @return The client configuration.
*/
@Override
public ClientConfiguration getConfig() {
return this.config;
}
/**
* This method retrieves a JAX-RS implementation of the specified API with
* the specified authorization.
*
* @param authFilter A dynamic authorization filter.
* @param apiClass A JAX-RS annotation API class.
* @return An instance of the API class.
*/
@Override
public <T> T getApi(AuthorizationFilter authFilter, Class<T> apiClass) {
throw new UnsupportedOperationException();

View File

@ -14,8 +14,8 @@
*/
package com.inteligr8.rs;
import javax.ws.rs.client.ClientRequestContext;
import javax.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.core.HttpHeaders;
/**
* This class implements a proxied or forwarded authorization header based
@ -32,6 +32,8 @@ public class ForwardingAuthorizationFilter implements AuthorizationFilter {
private final String authorizationHeaderValue;
/**
* This constructor instantiates the filter with required fields.
*
* @param authorizationHeaderValue A previously used or formulated 'Authorization' header.
*/
public ForwardingAuthorizationFilter(String authorizationHeaderValue) {

View File

@ -0,0 +1,68 @@
/*
* This program is free software: you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or (at your
* option) any later version.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
* more details.
*
* You should have received a copy of the GNU General Public License along
* with this program. If not, see <https://www.gnu.org/licenses/>.
*/
package com.inteligr8.rs;
import java.io.UnsupportedEncodingException;
import java.util.List;
import java.util.Map.Entry;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import jakarta.ws.rs.client.ClientRequestContext;
/**
* This class implements a header-based authorization filter.
*
* @author brian@inteligr8.com
*/
public class HeaderAuthorizationFilter implements AuthorizationFilter {
private final MultiValueMap<String, Object> headers = new LinkedMultiValueMap<>();
/**
* This constructor instantiates the filter with required fields.
*
* @param headerName A header name.
* @param headerValue A header value.
*/
public HeaderAuthorizationFilter(String headerName, Object headerValue) {
this.headers.add(headerName, headerValue);
}
/**
* This method adds another header name/value to outgoing requests.
*
* @param headerName A header name.
* @param headerValue A header value.
* @return This class for fluent chaining.
*/
public HeaderAuthorizationFilter add(String headerName, Object headerValue) {
this.headers.add(headerName, headerValue);
return this;
}
/**
* This method applies the 'Authorization' header to the {@link ClientRequestContext}.
*
* @param requestContext A request context.
*/
@Override
public void filter(ClientRequestContext requestContext) throws UnsupportedEncodingException {
for (Entry<String, List<Object>> header : this.headers.entrySet())
requestContext.getHeaders().put(header.getKey(), header.getValue());
}
}

View File

@ -16,12 +16,12 @@ package com.inteligr8.rs;
import java.io.IOException;
import javax.ws.rs.client.ClientRequestContext;
import javax.ws.rs.client.ClientRequestFilter;
import javax.ws.rs.client.ClientResponseContext;
import javax.ws.rs.client.ClientResponseFilter;
import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;
import jakarta.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.client.ClientRequestFilter;
import jakarta.ws.rs.client.ClientResponseContext;
import jakarta.ws.rs.client.ClientResponseFilter;
import jakarta.ws.rs.core.Form;
import jakarta.ws.rs.core.MediaType;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

View File

@ -16,7 +16,7 @@ package com.inteligr8.rs;
import java.net.URI;
import javax.ws.rs.core.Form;
import jakarta.ws.rs.core.Form;
import org.apache.commons.lang3.StringUtils;
import org.slf4j.Logger;

View File

@ -16,22 +16,22 @@ package com.inteligr8.rs;
import java.util.Map;
import javax.ws.rs.WebApplicationException;
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.ClientRequestContext;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.Form;
import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status.Family;
import jakarta.ws.rs.WebApplicationException;
import jakarta.ws.rs.client.Client;
import jakarta.ws.rs.client.ClientBuilder;
import jakarta.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.client.Entity;
import jakarta.ws.rs.client.WebTarget;
import jakarta.ws.rs.core.Form;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.Response.Status.Family;
import org.apache.commons.lang3.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider;
import com.fasterxml.jackson.jakarta.rs.json.JacksonJsonProvider;
/**
* This class is the base for implementations of OAuth authorization flows.
@ -159,7 +159,7 @@ public abstract class OAuthAuthorizationFilter implements AuthorizationFilter {
Entity<Form> entity = Entity.form(form);
Client client = ClientBuilder.newBuilder()
.register(new JacksonJaxbJsonProvider())
.register(new JacksonJsonProvider())
.build();
WebTarget target = client.target(this.tokenUrl);

View File

@ -14,7 +14,7 @@
*/
package com.inteligr8.rs;
import javax.ws.rs.core.Form;
import jakarta.ws.rs.core.Form;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

View File

@ -14,7 +14,7 @@
*/
package com.inteligr8.rs;
import javax.ws.rs.core.Form;
import jakarta.ws.rs.core.Form;
import org.apache.commons.lang3.StringUtils;
import org.slf4j.Logger;