Overview

Catatumbo is an Open Source Object Mapping and Persistence framework for Google's Cloud Datastore and Cloud Firestore¹. Catatumbo allows to effortlessly save model objects to the Cloud Datastore as well as retrieve and map the data from the Cloud Datastore to model objects. Catatumbo is similar to JPA (Java Persistence API), but is specifically designed to work with Google Cloud Datastore instead of Relational Databases.

Catatumbo framework is built on top of Google Cloud Java Client for Datastore API (formerly known as gcloud-java-datastore API). The framework provides a handful of annotations to make your model classes manageable by the framework.

Features

• Automatic mapping of model classes to Cloud Datastore Entities and vice versa. Model classes may follow the below design patterns:
  • Classic Java Beans Pattern (a.k.a. POJO) - with a default constructor, accessor (getter) methods and mutator (setter) methods.
  • Builder Pattern - for immutable persistence objects and/or to ensure a persistence object state is always valid/consistent.
• Automatic generation of Identifiers (for both Numeric and String types)
• Support for strongly typed Identifiers (e.g. custom class UserId that wraps a numeric or string Id)
• Ignore specific fields of your model object from persistence operations
• Support for a variety of Data Types -
  • boolean, Boolean
  • char, Character
  • short, Short
  • int, Integer
  • long, Long
  • float, Float
  • double, Double
  • BigDecimal
  • String
  • Byte Array
  • Char Array
  • java.util.Date
  • java.util.Calendar
  • java.time.LocalDate
  • java.time.LocalTime
  • java.time.LocalDateTime
  • java.time.OffsetDateTime
  • java.time.ZonedDateTime
  • Enum
  • Geo Location (a.k.a Geo Point)
  • Keys, Parent Keys and Key References
  • java.util.List
  • java.util.Set
  • java.util.Map
  • Map of Maps
• Ability to annotate which fields are indexed/not indexed
• Ability to skip persistence of fields if their value is null
• Support for secondary indexes to index a property for case-insensitive querying/sorting.
• Support for embedded objects (e.g. Address object inside Customer model). Embedded objects can be stored in exploded (each field of embedded object is a separate property) form or imploded (the embedded object is stored in a single field)form.
• Support for persisting inherited fields
• Support for entity listeners which allow your application to react to certain persistence events.
• Support for Optimistic Locking using automatic entity versioning scheme
• Automatic timestamping of entities using @CreatedTimestamp and @UpdatedTimestamp annotations.
• Support for multi-tenancy - allows working with multiple Namespaces in the Cloud Datastore.
• Ability to override default mappers for a given data type
• Ability to define a custom mapper on a per-field basis
• Create, Retrieve, Update, Delete, Upsert (update or insert)
• Execute GQL Queries
  • Entity Queries
  • Projection Queries
  • Key-only Queries
• Support for Batch Writes
• Transaction Support
• Metadata API for retrieving the Datastore metadata
• Programmatic access to Datastore Statistics
• Ability to work with Local Datastore (a.k.a. Datastore Emulator)