Providence Customizable Serialization with Generated Models

• Getting Started
• New features in 2.0
• Upgrading from 1.10
• Downloads & Releases
• Build Status
• JavaDoc
• Test Coverage
• Providence
• Providence Features
• Annotations
• vs Apache Thrift
• Services
• Models
• Documentation
• Core : Jackson
• Core : Server
• Core : Client
• Core
• Utilities
• Thrift Bridge
• JDBI
• Storage
• Testing
• Config
• Reflect
• Utilities in Beta
• GraphQL
• Javax WS RS
• Storage - Hazelcast
• Build Tooling
• Java Generator
• Generator
• Gradle Plugin
• Maven Plugin
• CLI Tools
• Config Helper
• RPC Tool
• Data Converter
• Code Generator
• Development Docs
• JSON Serializer
• Fast Binary Serializer
• Binary Serializer
• IDEA Plugin
• Integration Testing
• Release Process

The "Eye of Providence" symbol, used among others by the Free-masons, US Treasury (found on the $1 bill) and attributed to the fabled Illuminati.

The providence project was made in order to make an immutable model java library for thrift. It is mostly separate from the thrift library, but can use the standard thrift protocols to serialize and serialize messages. It is mainly based on the Facebook / Apache thrift library, but with some differences and limitations.

Note that providence requires java >= 8.

Getting Providence CLI

See here for instructions on how to get morimekta.net CLI tools installed on your system. It has instructions for RedHat / YUM, Debian and Homebrew (for Mac):

• http://dl.morimekta.net/

Developer Setup

In order to compile providence itself, you need the java 8 java and javac commands (I recommend openjdk8-jdk), and maven (3.5). Then check out git@gitlab.com:morimekta/providence.git and build with:

mvn clean install -Plib

There is also a Makefile for updating pre-compiled providence and thrift files. These need make and docker installed to work, but is not required for most development.

Contributing

You can send me an email to suggest a feature. Or you can make it yourself by cloning the project, and create a merge request for your change.

Make sure to name it properly, and describe what the change does, and assign the request to @morimekta. That should send me an email, so I know it’s there and take care of it.

Terms and Definitions

Throughout the providence documentation I use a number of terms that easily can be confused.

• [thrift]: A system of converting files that follow the thrift IDL specification found here to some form of code or data. I currently know of 5 thrift systems, other than providence:
  • Apache Thrift: The “main” thrift implementation containing lots of languages.
  • FB Thrift: A FaceBook managed fork of thrift with changes and features that FaceBook wants.
  • Thrift-Nano: A version of thrift optimized for low memory consumption e.g. for using on low-power embedded systems.
  • Thrifty: A compact and simple java version of thrift aimed at mobile platforms.
  • ThriftPy: An alternative python library and compiler for thrift.
• [Apache Thrift]: Is the “official” Apache hosted implementation of thrift. This is essentially what is compared with for determining compatibility.
• [Providence]: Is all of this project (including some off-repository parts like providence-gradle-plugin).

Also inside providence, we use a little different set of definitions from Apache Thrift.

• [message]: Message is the base type of all the structured data typed defined in a thrift file, including struct, exception and union. This is variantly called struct and base type in Apache Thrift.
• [service call]: Is the wrapper structure that is sent with the call to and response from a service method call. This is what is called a message in Apache Thrift.