Java API that allows storing in 2 DynamoDB tables multiple entities identified by a simple key or a key composed of 2 attributes in a simplified way
Represent entities (f.e Customer, Invoice, Session) using non-relational databases requires some "obscure" coding, turning our code difficult to read (understand), debug and reuse. This API makes it easy and clean to manage insert/delete/query operations. It's strongly recommended to understand the DynamoDB best practices.
With a few lines records can be added:
// Creates secondary attributes name and age
Collection<Attribute> attributes = new LinkedList<Attribute>();
attributes.add(new Attribute("name", TYPE.CHAR, "John Smith"));
attributes.add(new Attribute("age", TYPE.INT, 29));
// Add the customer with id 5555555000 to table customer
db.addItem("Customer", "5555555000", attributes);
Adding JSON attributes it's also possible (and recommended):
String customerInfo = "{\r\n" +
" \"name\":\"John Smith\",\r\n" +
" \"age\":29,\r\n" +
" \"phones\":[\r\n" +
" {\r\n" +
" \"phone\":\"(+1)555-555-555\",\r\n" +
" \"type\":\"home\"\r\n" +
" },\r\n" +
" {\r\n" +
" \"phone\":\"(+1)111-111-111\",\r\n" +
" \"type\":\"work\"\r\n" +
" }\r\n" +
" ]\r\n" +
"}";
attributes = new LinkedList<Attribute>();
attributes.add(new Attribute("CustomerInfo", TYPE.JSON, customerInfo));
db.addItem("Customer", "5555555000", attributes);
It also provides an easy way to copy items between AWS regions and DynamoDB tables:
// All records are copied from SA_EAST_1 to EU_CENTRAL_1
GeneralDB target = new GeneralDB(Regions.EU_CENTRAL_1);
db.copy_SK_ToTarget(target); // Copy all the single key tables
db.copyToTarget(target); // Copy all the composed key tables
// All record are copied to new dynamodb tables for testing purpose. This tables will have the prefix "TEST-"
target = new GeneralDB("TEST-");
db.copy_SK_ToTarget(target); // Copy all the single key tables
db.copyToTarget(target); // Copy all the composed key tables
API asummes 2 DynamoDB tables were created:
- GeneralSK: DynamoDB table named "GeneralSK" with a single primary key named "generalkey" used to store single key entities
- GeneralDK: DynamoDB table named "GeneralDK" with primary key named "generapk" and range key named "generalrk" used to store composed key entities
See documentation on how to create a DynamoDB table
A small but playful example is the following. Suppose the tables below with Customers and Invoices information:
Customers:
Id | CustomerInfo |
5555555000 | { "name":"John Smith", "age":29, "phones":[{"phone":"(+1)555-555-555","type":"home"},{"phone":"(+1)111-111-111","type":"work"}] } |
2222222000 | { "name":"Jane Doe", "age":21, "phones":[ { "phone":"(+1)222-222-222", "type":"home"}] } |
Invoices.
Id | InvoiceTotal |
2345 | $ 5000 |
3111 | $ 322 |
Using the following code, this information is added to dynamoDB:
:
db.addItem("Customer", "5555555000", attributes);
db.addItem("Customer", "2222222000", attributes);
:
db.addItem("invoice", "2345", attributes);
db.addItem("invoice", "3111", attributes);
As a result, the GeneralSK have the following records:
generalkey | CustomerInfo | InvoiceTotal |
customer-5555555000 | { "name":"John Smith", "age":29, "phones":[{"phone":"(+1)555-555-555","type":"home"},{"phone":"(+1)111-111-111","type":"work"}] } |
|
customer-2222222000 | { "name":"Jane Doe", "age":21, "phones":[ { "phone":"(+1)222-222-222", "type":"home"}] } |
|
invoice-2345 | $ 5000 | |
invoice-3111 | $ 322 |
Another feature included is the use of environments. The motivation of environments is to allow having multiple versions of the DynamoDB tables to be used from different execution environments (f.e TEST, PREPROD, DESA) in a transparent way. If no environment is defined then the GeneralSK and GeneralDB tables will be used. If an environment named "TEST-" is configured, then the GeneralDB instances will use the DynamoDB tables TEST-GeneralSK and TEST-GeneralDK tables.
The environment can be set in 3 ways:
- Using the java property com.moleculateam.aws.env:
..-Dcom.moleculateam.aws.env="TEST-"...
- Setting the static APIStatus field "env"
APIStatus.env = "TEST-"
- Using the GeneralDB constructor
GeneralDB target = new GeneralDB("TEST-");
Any GeneralDB instance will define the environment to use following these rules in order:
- If Environment is defined using GeneralDB constructor it will be the environment used by the instance.
- If Environment is NOT defined using GeneralDB constructor then, the APIStatus value will be used
- If Environment is NOT defined using APIStatus then, the java property will be used
- If Environment is NOT defined using the java property then Environment is assumed to be empty so GeneralSK and GeneralDB tables will be used.
The DynamoDBExamples.java provides a series of examples to understand how to use de API.
- As mentioned above the creation of GeneralSK and GeneralDK tables are not included as part of the solution.
- It is assumed that the AWS credentials are correctly configured.
This library is available as open source under the terms of the GNU General Public License v3.0