io.castle.client.Castle Maven / Gradle / Ivy
Show all versions of castle-java Show documentation
package io.castle.client;
import com.google.common.hash.HashFunction;
import io.castle.client.api.CastleApi;
import io.castle.client.internal.CastleApiImpl;
import io.castle.client.internal.config.CastleConfiguration;
import io.castle.client.internal.config.CastleConfigurationBuilder;
import io.castle.client.internal.config.CastleSdkInternalConfiguration;
import io.castle.client.internal.json.CastleGsonModel;
import io.castle.client.internal.utils.CastleContextBuilder;
import io.castle.client.model.CastleSdkConfigurationException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.servlet.http.HttpServletRequest;
/**
* Through static methods, creates a singleton instance of this class, which provides instances of {@code CastleAPI}
* and keeps in its internal configuration all application level settings.
*
* This also provides methods for initialization of the SDK.
* {@code this#verifySdkConfigurationAndInitialize()} must be called once in the lifetime of an application using the SDK
* during its initialization process.
*
* After initialization, {@code this#sdk()} will return the singleton instance of this class, which grants access to
* its non-static methods.
*/
public class Castle {
public static final Logger logger = LoggerFactory.getLogger(Castle.class);
private final CastleSdkInternalConfiguration internalConfiguration;
/**
* Public constructor for test proposes only.
*
* Please use the static sdk() method to get the SDK instance.
*
* @param internalConfiguration a test internal configuration for the SDK
*/
public Castle(CastleSdkInternalConfiguration internalConfiguration) {
this.internalConfiguration = internalConfiguration;
}
private static Castle instance;
/**
* Gets the SDK singleton instance.
*
* @return the singleton instance of {@code this}
* @throws IllegalStateException when the SDK has not been properly initialized
*/
public static Castle sdk() throws IllegalStateException {
if (instance == null) {
throw new IllegalStateException("Castle SDK must be initialized. Call `Castle.initialize()` first");
}
return instance;
}
/**
* Creates a API client instance for sending a request
* @return A new instance of the API client {@code CastleApiImpl}
* @throws IllegalStateException when the SDK has not been properly initialized
*/
public static CastleApi client() throws IllegalStateException {
return sdk().buildApiClient(false);
}
/**
* Creates a API client instance for sending a request
* @param doNotTrack when true, the API calls will be not realized and default values will be provided
* @return A new instance of the API client {@code CastleApiImpl}
* @throws IllegalStateException when the SDK has not been properly initialized
*/
public static CastleApi client(boolean doNotTrack) throws IllegalStateException {
return sdk().buildApiClient(doNotTrack);
}
/**
* Verifies the SDK's internalConfiguration and initializes its internal Configuration.
*
* @throws CastleSdkConfigurationException if the provided settings in the environment of classpath have invalid values
*/
public static void verifySdkConfigurationAndInitialize() throws CastleSdkConfigurationException {
initializeSDK();
}
private static synchronized void initializeSDK() throws CastleSdkConfigurationException {
CastleSdkInternalConfiguration loadedConfig = CastleSdkInternalConfiguration.getInternalConfiguration();
instance = new Castle(loadedConfig);
}
/**
* Initialize and configure the Castle SDK using a configuration object
*
* @param config CastleConfiguration object
* @throws CastleSdkConfigurationException Configuration options missing or
* invalid
*/
public static synchronized void initialize(CastleConfiguration config) throws CastleSdkConfigurationException {
instance = new Castle(
CastleSdkInternalConfiguration.buildFromConfiguration(config)
);
}
/**
* Initialize the Castle SDK using default settings and variables from ENV
*
* @throws CastleSdkConfigurationException Configuration options missing or
* invalid
*/
public static void initialize() throws CastleSdkConfigurationException {
initialize(configurationBuilder().build());
}
/**
* Initialize the Castle SDK using only the API secret key
* @param secret API Secret
* @throws CastleSdkConfigurationException Configuration options missing or
* invalid
*/
public static void initialize(String secret) throws CastleSdkConfigurationException {
initialize(configurationBuilder().apiSecret(secret).build());
}
public static CastleConfigurationBuilder configurationBuilder() {
return CastleSdkInternalConfiguration.builderFromConfigurationLoader();
}
/**
* Returns a new builder object for constructing a CastleContext
* @return Return CatleContextBuilder object
*/
public static CastleContextBuilder contextBuilder() {
return instance.buildContextBuilder();
}
/**
* Create a new instance of a request context builder
* @return a new instance of {@code CastleContextBuilder}
*/
public CastleContextBuilder buildContextBuilder() {
return new CastleContextBuilder(
getSdkConfiguration(),
getGsonModel()
);
}
public CastleApi buildApiClient() {
return buildApiClient(false);
}
public CastleApi buildApiClient(boolean doNotTrack) {
return new CastleApiImpl(internalConfiguration, doNotTrack);
}
/**
* Create a API context for the given request.
* Tracking is ON by default.
*
* @param request The request for data extraction
* @return a API reference to make backend calls to the castle.io rest api.
*/
public CastleApi onRequest(HttpServletRequest request) {
return onRequest(request, false);
}
/**
* Create a API context for the given request.
*
* @param request The request for data extraction
* @param doNotTrack when true, the API calls will be not realized and default values will be provided
* @return a API reference to make backend calls to the castle.io rest api.
*/
public CastleApi onRequest(HttpServletRequest request, boolean doNotTrack) {
return new CastleApiImpl(request, doNotTrack, internalConfiguration);
}
/**
* Gets the SDK's configuration stored in an instance of {@code CastleConfiguration}.
*
* @return the SDK's configuration
*/
public CastleConfiguration getSdkConfiguration() {
return internalConfiguration.getConfiguration();
}
/**
* Get Gson model for serialization and deserialization
* @return the Gson model
*/
public CastleGsonModel getGsonModel() {
return internalConfiguration.getModel();
}
/**
* Package accessible method for testing purposes.
*
* @return the internal sdk configuration
*/
CastleSdkInternalConfiguration getInternalConfiguration() {
return internalConfiguration;
}
/**
* Calculate the secure userId HMAC using the internal API Secret.
* @param userId raw user Id
* @return the HMAC of the userId
*/
public String secureUserID(String userId) {
HashFunction hashFunction = internalConfiguration.getSecureHashFunction();
return hashFunction.hashString(userId,com.google.common.base.Charsets.UTF_8).toString();
}
}