Storage Adapter Overview

This service allows management of of key-values, abstracting the storage service semantic and presenting a simple interface to store data of any format using Azure Cosmos DB. DocDb is used in the service but could be easily swapped with a different store.

Values are organized in collections, it is possible to work with individual values and entire collections. Complex data structures are serialized by clients and managed as a simple text payload.

The service provides a RESTful endpoint to Create-Read-Update-Delete values, where each value has a unique Id referenced also as "Key", supporting concurrency.

IDs can be provided by the client or automatically generated by the service (i.e. UUIDs).

Dependencies

• Azure Cosmos DB account with API type DocumentDB

How to use the microservice

Quickstart - Running the service with Docker

1. Install Docker: https://docs.docker.com/engine/installation
2. Create your Azure Cosmos DB account with API type DocumentDB
3. Find your Azure Cosmos DB account connection string. See Update your Connection Strings if you need help finding it.
4. Store the "Azure Cosmos DB account connection string" in the env-vars-setup script, then run the script.
5. Run the Storage Adapter service using the Docker run.
6. Use an HTTP client such as Postman, to exercise the RESTful API to create a collection.

Running the service with IntelliJ

Intellij IDEA lets you open the application without using a command prompt, without configuring anything outside of the IDE. The SBT build tool takes care of downloading appropriate libraries, resolving dependencies and building the project (more info here).

Steps using IntelliJ IDEA Community 2017, with SBT plugin enabled:

• "Open" the project with IntelliJ, the IDE should automatically recognize the SBT structure. Wait for the IDE to download some dependencies (see IntelliJ status bar)
• Create a new Run Configuration, of type "SBT Task", with any name.
  • Enter "run 9022" (including the double quotes) in Tasks. This ensures that the service starts using the TCP port 9022. If you desire to use a different port, feel free to change it.
  • Define the following environment variable:
    1. PCS_STORAGEADAPTER_DOCUMENTDB_CONNSTRING = {your CosmosDb DocumentDb connection string}
• Either from the toolbar or the Run menu, execute the configuration just created, using the Debug command/button
• Test that the service is up and running pointing your browser to http://127.0.0.1:9022/v1/status

And as a nice extra: if you edit the code, you don't need to stop/build/restart the application. Play and SBT automatically recompile the files modified on the fly. You can also see the re-build log in the Run Tool Window.

Run and Debug with Eclipse

The integration with Eclipse requires the

sbteclipse plugin, already included, and an initial setup via command line (more info here).

Steps using Eclipse Oxygen ("Eclipse for Java Developers" package):

• Open a console (either Bash or Windows CMD), move into the project folder, execute sbt compile and then sbt eclipse. This generates some files required by Eclipse to recognize the project.
• Open Eclipse, and from the Welcome screen "Import" an existing project, navigating to the root folder of the project.
• From the console run sbt -jvm-debug 9999 "run 900X" to start the project
• Test that the service is up and running pointing your browser to http://127.0.0.1:900X/v1/status
• In Eclipse, select "Run -> Debug Configurations" and add a "Remote Java Application", using "localhost" and port "9999".
• After saving this configuration, you can click "Debug" to connect to the running application.

Project Structure

This microservice contains the following projects:

--todo--

Build and Run from the command line

The scripts folder contains scripts for many frequent tasks:

• build: compile all the projects and run the tests.
• compile: compile all the projects.
• run: compile the projects and run the service. This will prompt for elevated privileges in Windows to run the web service.

Updating the Docker image

The scripts folder includes a docker subfolder with the files required to package the service into a Docker image:

• Dockerfile: docker images specifications
• build: build a Docker container and store the image in the local registry
• run: run the Docker container from the image stored in the local registry
• content: a folder with files copied into the image, including the entry point script

Configuration and Environment variables

The service configuration is stored using Akka's HOCON format in application.conf.

The HOCON format is a human readable format, very close to JSON, with some useful features:

• Ability to write comments
• Support for substitutions, e.g. referencing environment variables
• Supports JSON notation

The configuration file in the repository references some environment variables that need to created at least once. Depending on your OS and the IDE, there are several ways to manage environment variables:

• For Windows users, the env-vars-setup.cmd script needs to be prepared and executed just once. When executed, the settings will persist across terminal sessions and reboots.
• For Linux and OSX environments, the env-vars-setup script needs to be executed every time a new console is opened. Depending on the OS and terminal, there are ways to persist values globally, for more information these pages should help:
  • https://stackoverflow.com/questions/13046624/how-to-permanently-export-a-variable-in-linux
  • https://stackoverflow.com/questions/135688/setting-environment-variables-in-os-x
  • https://help.ubuntu.com/community/EnvironmentVariables
• IntelliJ IDEA: env. vars can be set in each Run Configuration, see https://www.jetbrains.com/help/idea/run-debug-configuration-application.html

Contributing to the solution

Please follow our contribution guildelines. We love PRs too.

Troubleshooting

Feedback

Please enter issues, bugs, or suggestions as GitHub Issues here: https://github.com/Azure/pcs-storage-adapter-java/issues.