InCountry Java SDK

Installation

The InCountry Java SDK requires Java Development Kit 1.8 or newer, the recommended language level is 8.

If you use Maven, please add this section to your dependencies list:

<dependency>
  <groupId>com.incountry</groupId>
  <artifactId>incountry-java-client</artifactId>
  <version>4.2.0</version>
</dependency>

If you use Gradle, please add this line to your dependencies list:

compile "com.incountry:incountry-java-client:4.2.0"

Countries list

For the full list of supported countries and their codes, please check this resource.

Quick start guide

To access your data on the InCountry platform with the Java SDK, you need to create an instance of the Storage class using the getInstance method and pass the StorageConfig object to it. You can get the clientId, clientSecret, and environmentId values on the InCountry Portal.

SecretsData secretsData = SecretsDataGenerator.fromPassword("<encryption_secret>");
StorageConfig config = new StorageConfig()
        .setEnvironmentId("<environment_id>")
        .setClientId("<client_id>")
        .setClientSecret("<client_secret>")
        .setSecretKeyAccessor(() -> secretsData);
Storage storage = StorageImpl.getInstance(config);

Storage configuration

Below you can find the full list of possible configuration options for creating a Storage instance.

/**
 * container with Storage configuration, using pattern 'builder'
 */
public class StorageConfig {
   //...
   /** Required. Optional if the INC_ENVIRONMENT_ID environment variable is provided */
   private String environmentId;
   /** Required when using OAuth authorization, it can be also set using the INC_CLIENT_ID variable */
   private String clientId;
   /** Required when using OAuth authorization, it can be also set using the INC_CLIENT_SECRET variable */
   private String clientSecret;
   /** Optional. Defines a custom API URL, it can also be set using the INC_ENDPOINT variable */
   private String endPoint;
   /** Optional. Object implementing the SecretKeyAccessor interface. 
    * Used to fetch an encryption secret */
   private SecretKeyAccessor secretKeyAccessor;
   /** Optional. Provider for custom encryption ciphers. If null, the default AES GCM cipher is used */
   private CryptoProvider cryptoProvider;
   /** Optional. If set as 'true', all keys are stored as lowercase. The default value is 'false' */
   private boolean normalizeKeys;
   /** Optional. The endpointMask parameter is used to switch from the `default` InCountry domain
    *  pattern (-mt-01.api.incountry.io) to a custom one */
   private String endpointMask;
   /** Optional. A custom endpoint for loading the countries list */
   private String countriesEndpoint;
   /** Optional. HTTP requests timeout. It should be greater than 0.
    * The default value is 30 seconds */
   private Integer httpTimeout;
   /** Optional. A dictionary to customize OAuth server endpoints by region (key-region, value-endpoint).
    * Can be used only with {@link #defaultAuthEndpoint}
    * Valid format: key = region, value = authorization server URL for a specific region */
   private Map<String, String> authEndpoints;
   /** Sets a custom OAuth authorization server URL that will be used as the default one.
    * It cannot be null when the {@link #authEndpoints} parameter is used */
   private String defaultAuthEndpoint;
   /** Optional. Sets an HTTP connections pool size. Can take null or a positive integer.
    * The default value is 20 */
   private Integer maxHttpPoolSize;
   /** Optional. Sets the limit of HTTP connections per route.
    * It can take null or a positive integer.
    * The default value == {@link #maxHttpPoolSize} */
   private Integer maxHttpConnectionsPerRoute;
   /** Optional. If set as 'false', the key1-key20 fields are not hashed. The default value is 'true' */
   private boolean hashSearchKeys = true;
   /** Optional. Used to provide/acquire an OAuth2 token */
   private OauthTokenAccessor oauthTokenAccessor;
   /** Optional. Sets a custom initial retry delay in seconds.
    * If set as null, the default 1-second delay is used */
   private Integer retryBaseDelay;
   /** Optional. Sets a custom maximum retry delay in seconds.
    * If set as null, the default 32-second delay is used */
   private Integer retryMaxDelay;
   //...
}

OAuth options configuration

The Java SDK allows you to precisely configure OAuth2 authorization endpoints if needed. Use this option only if your configuration plan requires so.

Below you can find an example of how to create a storage instance with custom OAuth endpoints:

Map<String, String> authEndpointsMap = new HashMap<>();
authEndpointsMap.put("emea", "https://auth-server-emea.com");
authEndpointsMap.put("apac", "https://auth-server-apac.com");
authEndpointsMap.put("amer", "https://auth-server-amer.com");

StorageConfig config = new StorageConfig()
   .setClientId(CLIENT_ID)
   .setClientSecret(SECRET)
   .setAuthEndpoints(authEndpointsMap)
   .setDefaultAuthEndpoint("https://auth-server-default.com")
   .setEndpointMask(ENDPOINT_MASK)
   .setEnvironmentId(ENVIRONMENT_ID)
Storage storage = StorageImpl.getInstance(config);

StorageConfig config = new StorageConfig()
   .setCountriesEndpoint(countriesEndpoint)
   //...
Storage storage = StorageImpl.getInstance(config);

The Java SDK also allows you to use the previously acquired OAuth tokens if needed or pass a token-acquiring function. In this mode, the SDK is not responsible for the automatic renewal of OAuth tokens. SDK users should implement the regular token renewal themselves.

Below you can find an example of how to specify the OAuth token while creating a Storage instance:

//pass a constant token
String oauthToken = yourGetTokenFunction();
StorageConfig config = new StorageConfig()
        .setEnvironmentId("<environment_id>")
        .setOauthToken(oauthToken);
Storage storage = StorageImpl.getInstance(config);

//pass a function returning an OAuth2 token
StorageConfig config = new StorageConfig()
        .setEnvironmentId("<environment_id>")
        .setOauthTokenAccessor(() -> yourGetTokenFunction());
Storage storage = StorageImpl.getInstance(config);

Encryption key/secret

You can use the SecretKeyAccessor interface to pass your own secrets/keys to the SDK.

/**
 * Secrets accessor. Method {@link SecretKeyAccessor#getSecretsData()} is invoked
 * for each encryption/decryption.
 */
public interface SecretKeyAccessor {

    /**
     * Get your container with secrets
     *
     * @return SecretsData
     * @throws StorageClientException when issues occur while acquiring secrets
     */
    SecretsData getSecretsData() throws StorageClientException;
}


public class SecretsData {
   /**
    * Creates a container with secrets
    *
    * @param secrets       a non-empty list of secrets
    * @param currentSecret a secret used for encryption
    *                      (should be one of the secrets provided
    *                       in the 'secrets' parameter {@link #secrets})
    * @throws StorageClientException when parameter validation fails
    */
    public SecretsData(List<Secret> secrets, Secret currentSecret)
            throws StorageClientException {
    //...
}

public abstract class Secret {
    private final int version;
    private final byte[] secretBytes;
    //...
}

You can use the StorageConfig class to pass your own secrets/keys by specifying the secretKeyAccessor parameter. You can provide your secrets in the following ways:

1. As a constant SecretsData object:

   SecretsData secretsData = new SecretsData(secretsList, currentSecret);
   StorageConfig config = new StorageConfig()
           .setSecretKeyAccessor(() -> secretsData)
   //...
   

2. As a function that dynamically fetches secrets:

   SecretKeyAccessor accessor = () -> loadSecretsData();
   StorageConfig config = new StorageConfig()
           .setSecretKeyAccessor(accessor)
   //...
   
   private SecretsData loadSecretsData()  {
       String url = "<your_secret_url>";
       String responseJson = loadFromUrl(url).asJson();
       return SecretsDataGenerator.fromJson(responseJson);
   }
   

You can also use the SecretsDataGenerator class to create instances of the SecretsData class:

1. from a string password:

   SecretsData secretsData = SecretsDataGenerator.fromPassword("<password>");
   

2. from a JSON string representing the SecretsData object:

   SecretsData secretsData = SecretsDataGenerator.fromJson(jsonString);
   

   {
       "secrets": [
           {
               "secret": "secret_password_0",
               "version": 0,
               "isKey": false
           },
           {
               "secret": "secret_password_1",
               "version": 1,
               "isKey": false
           }
       ],
       "currentVersion": 1
   }
   

The SecretsData object allows you to define multiple keys/secrets that the SDK will use for data decryption based on the version of the key or the secret used for its encryption.

By the way, the SDK encrypts data only with the key/secret that matches the сurrentSecret parameter provided in the SecretsData object. This provides the flexibility required to support the Key Rotation Policy when secrets/keys should be changed over time.

The SDK encrypts data with the current secret/key while maintaining the ability to decrypt records encrypted with previous versions of the key/secret. The SDK also provides a method to migrate data that allows you to re-encrypt data with the latest key/secret. For details, please see the migrate method.

The SDK allows you to use custom encryption keys instead of secrets. Please note that the user-defined encryption key should be a 32-byte-long key as it is required by the AES-256 cryptographic algorithm (base64 encoded when the secrets data is loaded from JSON).

Normalizing and hashing record keys

The StorageConfig instance allows you to perform particular data transformations before passing this data to the InCountry storage service.

By setting the normalizeKeys option as true, all the string keys of any record will be stored in lowercase (except body and precommitBody).

Below you can find an example of how to use the normalizeKeys option:

StorageConfig config = new StorageConfig();
//...
config.setNormalizeKeys(true);
Storage storage = StorageImpl.getInstance(config);

Record newRecord = new Record("Some Record key")  //will be stored as 'some record key'
   .setBody("Example of PII data")                //will be stored as-is
   .setKey1("Key 1 Value");                       //will be stored as 'key 1 value'

// The method returns a record with normalized string keys (converted to lowercase)
newRecord = storage.write(countryCode, newRecord);

By setting the hashSearchKeys option as false, you can store the key1-key20 record fields unhashed, which enables the partial match search (see Partial text match search for details).

Below you can find an example of how to use the hashSearchKeys option:

StorageConfig config = new StorageConfig();
//...
config.setHashSearchKeys(false);
Storage storage = StorageImpl.getInstance(config);

Record record = new Record("Some Record key")
   .setBody("Example of PII data")
   .setKey1("Key 1 Value");

storage.write(countryCode, newRecord);

Managing records

This section provides the list of available SDK methods to manage records stored on the InCountry platform.

Writing a single record

You can use the write method to write new records.

public interface Storage {
    /**
     * Writes data to a remote data store
     *
     * @param country    a country identifier
     * @param newRecord  Record object to send to the InCountry platform
     * @return written record
     * @throws StorageClientException when parameter validation fails
     * @throws StorageServerException when a server connection fails or upon a server response error
     * @throws StorageCryptoException when encryption fails
     */
    Record write(String country, Record newRecord)
          throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

To store data records on the InCountry platform, you need to initialize the Record object.

public class Record {
   /**
    * Minimalistic constructor
    *
    * @param recordKey record key
    */
    public Record(String recordKey) {...};

   /**
    * Overloaded constructor
    *
    * @param recordKey record key
    * @param body      data to be stored and encrypted
    */
    public Record(String recordKey, String body) {...}
    //...
}

Below you can find an example of how to write a single record:

Record record = new Record("some_key")
    .setBody("some PII data")
    .setProfileKey("customer")
    .setKey1("hatchback")
    .setKey2("english")
    .setKey3("insurance")
    .setRangeKey1(10_000L)
storage.write("us", record);

List of available record fields

Below you can find the exhaustive list of record fields available on the InCountry platform, as well as their types and storage methods. Each field is either encrypted, hashed, or stored, as follows:

public class Record {
    //String fields
    private String recordKey;
    private String parentKey;
    private String profileKey;
    private String serviceKey1;
    private String serviceKey2;
    private String serviceKey3;
    private String serviceKey4;
    private String serviceKey5;
    private String key1;
    private String key2;
    private String key3;
    private String key4;
    private String key5;
    private String key6;
    private String key7;
    private String key8;
    private String key9;
    private String key10;
    private String key11;
    private String key12;
    private String key13;
    private String key14;
    private String key15;
    private String key16;
    private String key17;
    private String key18;
    private String key19;
    private String key20;
    //String fields, encrypted
    private String body;
    private String precommitBody;
    //Long fields, plain
    private Long rangeKey1;
    private Long rangeKey2;
    private Long rangeKey3;
    private Long rangeKey4;
    private Long rangeKey5;
    private Long rangeKey6;
    private Long rangeKey7;
    private Long rangeKey8;
    private Long rangeKey9;
    private Long rangeKey10;
    //ZonedDateTime field
    private ZonedDateTime expiresAt;
    //Readonly service fields, ZonedDateTime
    protected ZonedDateTime createdAt;
    protected ZonedDateTime updatedAt;

You can access all the properties by using the appropriate getters and setters, for example:

String key2 = record.getKey2();
String body = record.getBody();

record.setProfileKey("customer")
    .setRangeKey1(1_000L)
    .setKey3("grey");

Date fields

You can use the createdAt and updatedAt fields to access the date-related information about your records.

• The createdAt field contains the date when the record was initially created in the target country.

• The updatedAt field contains the date of the latest write operation for a specific recordKey field.

• The expiresAt field defines the lifespan of a record stored on the InCountry platform. The record will be automatically deleted upon reaching the specified date. This field can be set by the user. The date value is stored and returned in the UTC+00:00 format.

Writing multiple records

You can use the batchWrite method to write multiple records to the storage in a single request.

public interface Storage {
     /**
      * Writes multiple records at once to the remote storage
      *
      * @param country a country identifier
      * @param records a records list
      * @return BatchRecord object that contains a list of written records
      * @throws StorageClientException when parameter validation fails
      * @throws StorageServerException when a server connection fails or upon a server response error
      * @throws StorageCryptoException when encryption fails
      */
     BatchRecord batchWrite(String country, List<Record> records)
          throws StorageClientException, StorageServerException, StorageCryptoException;
     //...
}

Below you can find an example of how to write multiple records:

List<Record> list = new ArrayList<>();
list.add(new Record("some_record_key", "some PII data"));
list.add(new Record("another_record_key", "another PII data"));
storage.batchWrite("us", list);

Reading records

You can use the read method to read a particular record from the storage by passing its identifier:

public interface Storage {
   /**
    * Reads data from the remote data store
    *
    * @param country   a country identifier
    * @param recordKey a unique record identifier
    * @return Record object that contains required data or null
    * @throws StorageClientException when parameter validation fails
    * @throws StorageServerException when a server connection fails or upon a server response error
    * @throws StorageCryptoException when decryption fails
    */
    Record read(String country, String recordKey)
        throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

Below you can find an example of how to read a record:

String recordKey = "user_1";
Record record = storage.read("us", recordKey);
String decryptedBody = record.getBody();

Searching for records

You can look up data records either by using the exact match search operators or partial text match operator in almost any combination.

You can use the find method to search for records by their keys.

public interface Storage {
   /**
    * Finds records in the remote data store according to filters
    *
    * @param country a country identifier
    * @param filter  an object containing the find filters and search options
    * @return FindResult object containing required records
    * @throws StorageClientException when parameter validation fails
    * @throws StorageServerException when a server connection fails or upon a server response error
    * @throws StorageCryptoException when decryption fails
    */
    FindResult find(String country, FindFilter filter)
         throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

You can use the FindFilter class to define your search request.

Exact match search

Below you can find an example of how to perform an exact match search with the FindFilter class:

FindFilter filter = new FindFilter()
                  .keyEq(StringField.KEY2, "someKey")
                  .keyEq(StringField.KEY3, "firstValue", "secondValue")
                  .keyEq(NumberField.RANGE_KEY1, 123L, 456L);

FindResult findResult = storage.find("us", filter);
if (findResult.getCount() > 0) {
    Record record = findResult.getRecords().get(0);
    //...
}

The request will return records filtered according to the following pseudo-SQL pattern:

key2 = 'someKey' AND key3 in ('firstValue' , 'secondValue') AND (123 < = `rangeKey1` < = 456)

All the conditions added through the FindFilter class are joined with the logical AND operator. You cannot add multiple conditions for the same key. If you do this, only the last condition will be used.

The SDK returns 100 records at most. Use the limit and offset parameters to iterate through your records.

FindFilter filter = new FindFilter()
                  //...
                  .limitAndOffset(20, 80);
FindResult findResult = storage.find("us", filter);

The following predicate types are available for each string key field of the Record class through individual methods of the FindFilter class:

EQUALS              (FindFilter::keyEq)
NOT_EQUALS          (FindFilter::keyNotEq)
IS_NULL             (FindFilter::keyIsNull)
IS_NOT_NULL         (FindFilter::keyIsNotNull)

You can use the following builder methods for filtering records by numerical fields:

EQUALS              (FindFilter::keyEq)
NOT_EQUALS          (FindFilter::keyNotEq)
IS_NULL             (FindFilter::keyIsNull)
IS_NOT_NULL         (FindFilter::keyIsNotNull)
GREATER             (FindFilter::keyGreater)
LESS                (FindFilter::keyLess)
BETWEEN             (FindFilter::keyBetween)

You can use the following builder methods for filtering records by date fields:

EQUALS                      (FindFilter::keyEq)
NOT_EQUALS                  (FindFilter::keyNotEq)
IS_NULL                     (FindFilter::keyIsNull) //for the 'ExpiresAt' field only
IS_NOT_NULL                 (FindFilter::keyIsNotNull) //for the 'ExpiresAt' field only
GREATER(OR EQUALS)          (FindFilter::keyGreater)
LESS(OR EQUALS)             (FindFilter::keyLess)
BETWEEN                     (FindFilter::keyBetween)

The Find method returns the FindResult object that contains a list of Record objects and their metadata:

class FindResult {
    private int count;
    private int limit;
    private int offset;
    private int total;
    private List<Record> records;
    //...
}

You can access these fields by using getters, for example:

int total = findResult.getTotal();

You can use the FindResult.getErrors() method to get the list of the RecordException objects that contains detailed information about records that were not processed correctly during the execution of the find request.

Partial text match search

You can also look up data records by partial match with the searchKeysLike method of the FindFilter class. It provides a partial match search (similar to the LIKE SQL operator without special characters) against the record’s string fields key1, key2, ..., key20.

// Matches all records where
// Record.key1 LIKE 'abc' OR Record.key2 LIKE 'abc' OR ... OR Record.key20 LIKE 'abc'
FindFilter filter = new FindFilter()
    .searchKeysLike("abc");

// Matches all records where
// (Record.key1 LIKE 'abc' OR Record.key2 LIKE 'abc' OR ... OR Record.key20 LIKE 'abc')
// AND (Record.rangeKey1 = 1 OR Record.rangeKey1 = 2)
FindFilter filter = new FindFilter()
    .searchKeysLike("abc")
    .keyEq(NumberField.RANGE_KEY1, 1L, 2L);

// Causes a validation error (StorageClientException)
FindFilter filter = new FindFilter()
    .searchKeysLike("abc")
    .keyEq(StringField.KEY1, "def");

Sorting records

By default, records in search results are not sorted. To sort the returned records by one or multiple keys, use the sortBy method from the FindFilter class.

FindFilter filter = new FindFilter()
                  //...
                  .sortBy(SortField.CREATED_AT, SortOrder.ASC)
                  .sortBy(SortField.RANGE_KEY1, SortOrder.DESC)
FindResult findResult = storage.find("us", filter);

The request will return records sorted according to the following pseudo-SQL pattern:

SELECT * FROM record WHERE ...  ORDER BY created_at asc, range_key1 desc

Records can be sorted by the following fields:

public enum SortField {
   KEY1,
   KEY2,
   KEY3,
   KEY4,
   KEY5,
   KEY6,
   KEY7,
   KEY8,
   KEY9,
   KEY10,
   KEY11,
   KEY12,
   KEY13,
   KEY14,
   KEY15,
   KEY16,
   KEY17,
   KEY18,
   KEY19,
   KEY20,
   RANGE_KEY1,
   RANGE_KEY2,
   RANGE_KEY3,
   RANGE_KEY4,
   RANGE_KEY5,
   RANGE_KEY6,
   RANGE_KEY7,
   RANGE_KEY8,
   RANGE_KEY9,
   RANGE_KEY10,
   CREATED_AT,
   UPDATED_AT,
   EXPIRES_AT
}

Searching for one record

If you need to find only the first record matching a specific filter, you can use the findOne method:

public interface Storage {
   /**
    * Finds only the first record in a remote storage according to the provided filter
    *
    * @param country a country identifier
    * @param filter  an object containing the find filters and search options
    * @return a found record or null
    * @throws StorageClientException when parameter validation fails
    * @throws StorageServerException when a server connection fails or upon a server response error
    * @throws StorageCryptoException when decryption fails
    */
    Record findOne(String country, FindFilter filter)
           throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

It works the same way as the find method but returns the first record or null if no records are found.

Below you can find an example of how to search for one specific record:

FindFilter filter = new FindFilter()
                  .keyEq(StringField.KEY2, "someKey")
                  .keyEq(StringField.KEY3, "firstValue", "secondValue")
                  .keyEq(NumberField.RANGE_KEY1, 123L, 456L);

Record record = storage.findOne("us", filter);
//...

Deleting a single record

You can use the delete method to delete a single record from the InCountry platform by its RecordKey field.

public interface Storage {
    /**
    * Deletes a record from the remote storage
    *
    * @param country   a country identifier
    * @param recordKey a unique record identifier
    * @return 'true' if record was successfully deleted
    * @throws StorageClientException when parameter validation fails
    * @throws StorageServerException when server connection fails or upon a server response error
    */
    boolean delete(String country, String recordKey)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to delete a single record:

String recordKey = "user_1";
storage.delete("us", recordKey);

Deleting multiple records

You can use the batchDelete method to delete multiple records from the InCountry platform. For now, the SDK supports the deletion of records only by providing a list of the RecordKey values via the FindFilter instance.

public interface Storage {
    /**
     * Deletes a records list from a remote storage
     *
     * @param country a country identifier
     * @param filter  a filter with a non-null non-empty list for the 'RecordKey' field
     * @return 'true' if records were successfully deleted
     * @throws StorageClientException when parameter validation fails
     * @throws StorageServerException when a server connection fails or upon a server response error
     */
    boolean batchDelete(String country, FindFilter filter)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to delete multiple records:

String recordKey1 = "user_1";
String recordKey2 = "user_2";
String recordKey3 = "user_3";
FindFilter filter = new FindFilter()
       .keyEq(StringField.RECORD_KEY, recordKey1, recordKey2, recordKey3);
storage.batchDelete("us", filter);

Attaching files to a record

The InCountry platform allows you to attach files to the previously created records. Instances of the AttachmentMeta class represent metadata of attachments available through the Attachments field of the Record class instances that are returned by the read, find, and findOne methods of the Storage class.

public class Record {
    /** ... other fields ...  */
    private List<AttachmentMeta> attachments;
}

public class AttachmentMeta {
    private ZonedDateTime createdAt;
    private ZonedDateTime updatedAt;
    private String downloadLink;
    private String fileId;
    private String filename;
    private String hash;
    private String mimeType;
    private int size;
    //...
}

Adding attachments

You can use the addAttachment method of the Storage class to add or replace attachments.

public interface Storage {
    /**
     * Attaches a file to the existing record
     *
     * @param country         a country identifier
     * @param recordKey       a unique record identifier
     * @param fileInputStream input data stream
     * @param fileName        a file name
     * @param upsert          If 'true', the method will overwrite the existing file having the same name.
     *                        Otherwise an exception will be thrown when trying to overwrite an existing file
     * @param mimeType        MIME type of the attached file
     * @return AttachmentMeta an object with attachment metadata, such as fileId, mimeType, size, etc.
     * @throws StorageClientException when parameter validation fails
     * @throws StorageServerException when a server connection fails or upon a server response error
     */
    AttachmentMeta addAttachment(String country, String recordKey, InputStream fileInputStream,
                                 String fileName, boolean upsert, String mimeType)
             throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to add an attachment to the existing record:

File initialFile = new File("example.txt");
InputStream stream = new FileInputStream(initialFile);
storage.addAttachment(COUNTRY, RECORD_KEY, stream, "example.txt", false, MIME_TYPE);

Deleting attachments

You can use the deleteAttachment method to delete attachments by their fileId.

public interface Storage {
    /**
     * Deletes an attached file from the existing record
     *
     * @param country   a country identifier
     * @param recordKey unique record identifier
     * @param fileId    a file identifier
     * @return 'true' if a file was sucessfully deleted
     * @throws StorageClientException when parameter validation fails
     * @throws StorageServerException when a server connection fails or upon a server response error
     */
    boolean deleteAttachment(String country, String recordKey, String fileId)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to delete an attachment from the existing record:

storage.deleteAttachment(COUNTRY, RECORD_KEY, fileId);

Downloading attachments

You can use the getAttachmentFile method of the Storage class to download attachments.

public interface Storage {
    /**
     * Gets an attached file of the existing record
     *
     * @param country   a country identifier
     * @param recordKey a unique record identifier
     * @param fileId    a file identifier
     * @return AttachedFile an object that contains a required file
     * @throws StorageClientException when parameter validation fails
     * @throws StorageServerException when a server connection fails or upon a server response error
     */
    AttachedFile getAttachmentFile(String country, String recordKey, String fileId)
            throws StorageClientException, StorageServerException;
    //...
}

It returns an instance of the AttachedFile class with a readable file data stream and a file name.

public class AttachedFile {
private final InputStream fileContent;
private final String fileName;
//...
}

Below you can find an example of how to download attachments:

AttachedFile attachement = storageForAttachment.getAttachmentFile(COUNTRY, RECORD_KEY, fileId);
File file = new File(attachement.getFileName());
FileUtils.copyInputStreamToFile(attachement.getFileContent(), file);

Managing attachment metadata

Here you can find the available methods to manage attachment metadata.

Getting attachment metadata

You can use the getAttachmentMeta of the Storage class to retrieve the attachment metadata using its fileId.

public interface Storage {
    /**
     * Gets metadata of an attachment
     *
     * @param country   a country identifier
     * @param recordKey a unique record identifier
     * @param fileId    a file identifier
     * @return AttachmentMeta an object that contains required metadata, such as fileId,
     * mimeType, size, filename, downloadLink, updatedAt, and createdAt
     * @throws StorageClientException when parameter validation fails
     * @throws StorageServerException when a server connection fails or upon a server response error
     */
    AttachmentMeta getAttachmentMeta(String country, String recordKey, String fileId)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to retrieve the attachment metadata:

AttachmentMeta meta = storageForAttachment.getAttachmentMeta(COUNTRY, RECORD_KEY, fileId);

Updating attachment metadata

You can use the updateAttachmentMeta method of the Storage class to update the attachment metadata (MIME type and file name).

public interface Storage {
    /**
     * Updates the attachment metadata
     *
     * @param country   a country identifier
     * @param recordKey a unique record identifier
     * @param fileId    a file identifier
     * @param fileName  a new file name. Optional if the mimeType parameter is provided
     * @param mimeType  new file MIME type. Optional if the fileName parameter is provided
     * @return AttachmentMeta object that contains updated fields
     * @throws StorageClientException when parameter validation fails
     * @throws StorageServerException when a server connection fails or upon a server response error
     */
    AttachmentMeta updateAttachmentMeta(String country, String recordKey, String fileId,
                                        String fileName, String mimeType)
            throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to update the attachment metadata:

AttachmentMeta meta = storage
        .updateAttachmentMeta(COUNTRY, RECORD_KEY, fileId, NEW_FILE_NAME, NEW_MIME_TYPE);

Health check

You can use the healthCheck method of the Storage class to check the availability of a remote storage service by a country identifier.

public interface Storage {
   /**
     * Performs a health check of the storage service endpoint for the specified country
     *
     * @param country a country identifier
     * @return 'true' if the country's endpoint is available, otherwise it returns 'false'
     * @throws StorageClientException when parameter validation fails
     * @throws StorageServerException when a server connection fails or upon a server response error
     */
    boolean healthCheck(String country) throws StorageClientException, StorageServerException;
    //...
}

Below you can find an example of how to perform a health check:

bool status = storage.healthCheck(COUNTRY);

Data migration and key rotation support

The SecretKeyAccessor parameter of the StorageConfig class allows you to provide the SecretsData object that enables key rotation and data migration support.

The SDK introduces the migrate method:

public interface Storage {
   /**
    * Performs record re-encryption using the latest encryption key
    *
    * @param country a country identifier
    * @param limit   the batch-limit parameter
    * @return MigrateResult object that contains the total number of records
    *        left to migrate and total number of migrated records
    * @throws StorageClientException when parameter validation fails
    * @throws StorageServerException when a server connection fails or upon a server response error
    * @throws StorageCryptoException when decryption failed
    */
    MigrateResult migrate(String country, int limit)
           throws StorageClientException, StorageServerException, StorageCryptoException;
    //...
}

It allows you to re-encrypt data encrypted with older versions of the secret. You should specify the country parameter that defines the country you want to perform migration in and set the limit parameter for a precise number of records to migrate. The migrate method returns the MigrateResult object that contains information about the migration:

• migrated - the number of records migrated.

• totalLeft - the number of records left to migrate. This basically means the number of records with the version different from Version of CurrentSecret provided in the SecretsData object.

public class MigrateResult {
    private int migrated;
    private int totalLeft;
    //...
}

For a detailed example of migration usage, please check this resource.

AWS KMS integration

The Java SDK supports the usage of any 32-byte (256-bit) AES key, including the ones produced by an AWS KMS symmetric master key (CMK).

The suggested use case assumes that an AWS user already got their KMS encrypted data key (AES_256) generated. Afterward, the key is decrypted using the AWS KMS Java client library and then provided to the StorageConfig class instance of the InCountry Java SDK.

For a detailed example of AWS KMS keys usage, please check this resource.

Error Handling

The InCountry Java SDK may throw the following exceptions:

• StorageClientException is used for various input validation errors.

• StorageServerException is thrown when the SDK fails to communicate with InCountry servers or if server response validation fails.

• StorageCryptoException is thrown during encryption/decryption procedures (both default and custom). This may be a sign of malformed/corrupted data or a wrong encryption key provided to the SDK.

• StorageException is a general exception. Inherited by all the other exceptions.

We strongly recommend that you gracefully handle all the possible exceptions:

public void test() {
    try {
        // use InCountry Storage instance here
    } catch (StorageClientException e) {
        // some input validation error
    } catch (StorageServerException e) {
        // some server error
    } catch (StorageCryptoException e) {
        // some encryption error
    } catch (StorageException e) {
        // general error
    } catch (Exception e) {
        // something else happened not related to the InCountry Java SDK
    }
}

Custom encryption support

The Java SDK supports the provision of custom encryption/decryption methods if you decide to use your own algorithm instead of the default one.

You need to set the cryptoProvider attribute of the StorageConfig class instance with registered custom cipher implementations:

Cipher customCipher = new FernetCipher("Fernet cipher demo");
Cipher anotherCipher = new AnotherCustomCipher();
CryptoProvider provider = new CryptoProvider(customCipher);
provider.registerCipher(anotherCipher);
StorageConfig config = new StorageConfig();
//...
config.setCryptoProvider(provider);
Storage storage = StorageImpl.getInstance(config);

To use custom encryption, you need to create an implementation of the following abstract class:

public abstract class AbstractCipher implements Cipher {

    protected AbstractCipher(String name) throws StorageClientException {
        //...
    }

    /**
     * Encrypts data with a secret
     *
     * @param textBytes data for encryption
     * @param secretKey encryption secret bytes
     * @return encrypted data as a string
     * @throws StorageClientException when parameters validation fails
     * @throws StorageCryptoException when encryption fails
     */
    public abstract String encrypt(byte[] textBytes, CustomEncryptionKey secretKey)
            throws StorageClientException, StorageCryptoException;

    /**
     * Decrypts data with a secret
     *
     * @param cipherTextBytes encrypted data
     * @param secretKey       encryption secret bytes
     * @return decrypted data as a string
     * @throws StorageClientException when parameters validation fails
     * @throws StorageCryptoException when decryption fails
     */
    public abstract String decrypt(byte[] cipherTextBytes, CustomEncryptionKey secretKey)
            throws StorageClientException, StorageCryptoException;
    //...
}

You should provide an instance of the CustomEncryptionKey class through the SecretsData class instance passed to the SecretKeyAccessor parameter of the StorageConfig class:

public class CustomEncryptionKey extends Secret {
    public CustomEncryptionKey(int version, byte[] secretBytes)
            throws StorageClientException {
        //...
    }
    //...
}

You can also specify a key for custom encryption by setting the isForCustomEncryption parameter in the SecretsData JSON representation:

secrets_data = {
  "secrets": [{
     "secret": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwQUI=", //base64-encoded key (32 byte key)
     "version": 1,
     "isForCustomEncryption": true,
    }
  }],
  "currentVersion": 1,
}

The name parameter of the AbstractCipher constructor is used to differentiate custom encryption implementations from each other and from the default encryption as well. This way the SDK is able to successfully decrypt any old data records if encryption has changed over time.

You can set the current cipher implementation through the constructor of the CryptoProvider class. Such cipher will be used for encryption.

If none of the custom implementations of AbstractCipher are defined, the SDK will use the default encryption to encrypt stored data. At the same time, it will keep the ability to decrypt old data records that was encrypted with custom encryption (if any was used).

You can see an implementation example of custom encryption (using Fernet encryption at this resource).

Project dependencies

Below you can find the list of dependencies for the application compilation.

GroupId	ArtifactId	Version	Type
javax.xml.bind	jaxb-api	2.3.1	jar
javax.activation	javax.activation-api	1.2.0	jar
commons-codec	commons-codec	1.15	jar
commons-logging	commons-logging	1.2	jar
commons-io	commons-io	2.8.0	jar
org.apache.logging.log4j	log4j-api	2.14.1	jar
org.apache.logging.log4j	log4j-core	2.14.1	jar
org.apache.logging.log4j	log4j-core-jcl	2.14.1	jar
org.apache.httpcomponents	httpclient	4.5.13	jar
org.apache.httpcomponents	httpcore	4.4.13	jar
com.google.code.gson	gson	2.8.6	jar

Dependency Tree

compileClasspath - Compile classpath for source set 'main'.
+--- javax.xml.bind:jaxb-api:2.3.1
|    \--- javax.activation:javax.activation-api:1.2.0
+--- commons-codec:commons-codec:1.15
+--- com.google.code.gson:gson:2.8.6
+--- org.apache.logging.log4j:log4j-api:2.14.1
+--- org.apache.logging.log4j:log4j-core:2.14.1
|    \--- org.apache.logging.log4j:log4j-api:2.14.1
+--- org.apache.logging.log4j:log4j-jcl:2.14.1
|    +--- commons-logging:commons-logging:1.2
|    \--- org.apache.logging.log4j:log4j-api:2.14.1
+--- org.apache.httpcomponents:httpclient:4.5.13
|    +--- org.apache.httpcomponents:httpcore:4.4.13
|    +--- commons-logging:commons-logging:1.2
|    \--- commons-codec:commons-codec:1.11 -> 1.15
+--- commons-io:commons-io:2.8.0
\--- org.apache.httpcomponents:httpmime:4.5.13
     \--- org.apache.httpcomponents:httpclient:4.5.13 (*)