Added support for creating read-only or read-write transactions. Prior to this version, Transactions were always read-write.
Created a new enum named TransactionMode
EntityManager#newTransaction method is overloaded to accept the desired transaction mode.
EntityManager#executeInTransaction method is overloaded to accept the desired transaction mode.
Marked the TransactionalTask interface as a Functional Interface.
Upgraded the underlying client library to the latest version, 1.16.0.
(December 10, 2017)
Fixed an issue with persisting of unindexed List/Set values defined in an Embeddable.
Upgraded the underlying client library for Google Cloud Datastore to the latest version, 1.12.0.
(September 16, 2017)
Model classes (@Entity, @Embeddable and @MappedSuperClass) can now
use Builder pattern, in addition to the previously supported Classic Java Beans pattern (a.k.a
POJO). Builder pattern helps the cases where persistence objects need to be immutable or to ensure that the
objects state is always valid/consistent.
Updated the EntityManager, DatastoreTransaction, DatastoreBatch to
throw two specialized exceptions in certain cases:
EntityAlreadyExistsException - when attempting to insert a duplicate key
EntityNotFoundException - if the entity with the given key is not found, during an
Fixed a couple of typos in the exception messages generated by the Marshaller
Upgraded the underlying client library for Google Cloud Datastore to the latest version, 1.5.1.
(July 22, 2017)
Added the ability to skip persistence of fields if their value is null. The Property and Embedded
annotations now support defining a field as optional. When optional is set to true, and if the field is
null, the corresponding property will be completely omitted when saving to the Datastore. PropertyOverride
can be used to override the optionality of fields defined in an Embeddable or MappedSuperClass.
Added support for persisting/loading Map of Maps to/from Embedded Entity
Enhanced the Metadata API to return all Kinds excluding any System Kinds. Kind names that begin with double
underscores will be omitted from the returned list.
Added support for deletion of all Entities of a given Kind, given the Kind name. This can be used in
conjunction with the above feature to clean up an entire namespace (e.g. for cleaning up test data).
Upgraded the underlying google-cloud-datastore API to the latest version, 1.2.3.
(June 20, 2017)
Provides programmatic access to Datastore Statistics (information available on GCD Dashboard). Various
statistics are available through the DatastoreStats interface.
Added support for strongly typed identifiers. This allows custom classes to be used as Entity Identifiers.
For example, entity User may declare its Identifier as of type UserId.
Added two new methods to the EntityManager and DatastoreTransaction interfaces to
retrieve entities by their Key (DatastoreKey).
Enhanced the EntityManager interface to support ID/Key allocation.
Marked the DatastoreKey interface as Serializable.
Upgraded the underlying google-cloud-datastore API to the latest version, 1.2.0.
Fixed potential NullPointerException and ClassCastException in the DatastoreProperty
Entity (part of the Metadata API).
(April 25, 2017)
This version requires Java 8 or later. Catatumbo 1.4.0 is the last version that supports Java 7.
Migrated to Java 8.
Replaced the classic Reflection based Method invocations with MethodHandlers for better performance.
Added support for the following types from java.time package:
LocalDate - maps to String in the Cloud Datastore
LocalTime - maps to String in the Cloud Datastore
LocalDateTime - Maps to String in the Cloud Datastore
OffsetDateTime - Maps to DateTime in the Cloud Datastore
ZonedDateTime - Maps to DateTime in the Cloud Datastore
Entity fields that are annotated with CreatedTimestamp or UpdatedTimestamp annotations now support the below
new types from the java.time package:
Enhanced the Query Parameter bindings (positional and named) to support all new types from the java.time
Upgraded the underlying google-cloud-datastore API to the latest version, 1.0.0-rc2.
(March 13, 2017)
Enhanced the EntityManagerFactory to allow creation of EntityManager using
advanced options such as connection timeout and read timeout. A new class, ConnectionParameters
was created for this purpose. The ConnectionParameters class provides a standardized and
consistent way to create EntityManager either for Datastore on GCP or Datastore Emulator.
Added a new annotation named ProjectedEntity to support mapping the results of a projection
query. Query Results (Entity Query or Projection Query) can either be mapped to an Entity or
ProjectedEntity. Using ProjectedEntity enforces additional checks (e.g.
persistence of Projection Entities is disallowed).
Fixed the DefaultDatastoreMetadata to catch any underlying exceptions and re-throw them as
Upgraded the underlying google-cloud-datastore API to the latest version, 0.9.4-beta.
(February 27, 2017)
Enhanced support for multi-tenancy. The new class, Tenant, lets each thread to maintain a
different namespace. This allows a single instance of EntityManager to read from/write to
multiple namespaces in the Cloud Datastore.
Added support for automatically setting the creation and modification timestamp of entities. Two new
annotations, @CreatedTimestamp and @UpdatedTimestamp were introduced to facilitate
Added support for retrieving the Datastore Metadata. The new Metadata API (DatastoreMetadata)
Retrieval of Namespaces in the Cloud Datastore
Retrieve all Kinds in a Namespace
Retrieve all indexed Properties and their data types in a given Kind.
Extended the support for optimistic locking technique to DatastoreAccess.update(List) methods.
Implementations of QueryRequest now support binding multiple positional parameters using the
newly added var-arg method, addPositionalBindings.
Removed the following misspelled and deprecated methods that were first deprecated in version 1.0.2:
Updated Catatumbo to use the latest version, 0.9.3, of Google Cloud Java Client for Datastore API.
(February 5, 2017)
DefaultDatastoreKey was modified to implement java.io.Serializable interface to
(February 5, 2017)
Fixed an issue where persisting Array properties (List/Set) with indexing turned off was throwing an
Exception. Google Cloud Datastore mandates that the indexing be ON for Array properties, but the items in
the Array property may be excluded from indexing. The effected Mappers, ListMapper and SetMapper were
Updated Catatumbo to use the latest version, 0.8.3, of Google Cloud Java Client for Datastore API.
(December 13, 2016)
Fixed an issue with the way Catatumbo was determining the accessor method names for the
an entity. In some rare cases, the expected method names were not matching with the
produced by popular IDEs. For example, if you have a field named aUser,
expecting setAUser and getAuser methods, while the IDEs
setaUser and getaUser. This fix makes Catatumbo to be
IDEs and JavaBeans standards.
See Issue #96
for more details.
Though it is unlikely, this release may not be 100% backward compatible, if your
field names like the one mentioned above. You may need to update the accessor method
(December 11, 2016)
Updated the below Exceptions to extend EntityManagerException:
Updated Catatumbo to use the latest version, 0.8.0, of Google Cloud Java Client for
(December 4, 2016)
Enhanced the support for List/Set/Map types to allow mapping of embedded objects. For
example, a list of Address objects can now be mapped to/from the Cloud Datastore.
Added support for creation of Secondary Indexes on the fields of an Entity. Secondary
Indexes are useful, for example, to index a field in all lower case or upper case, to
allow for case-insensitive querying and sorting. The Catatumbo framework handles this
transparently by creating an additional property in the Cloud Datastore, without
polluting the model classes. Added the below two new annotations to support this
SecondaryIndex - specifies if a secondary index should be created
for an entity's field.
PropertyIndexer - This optional annotation allows specifying which
indexer implementation is to be used for creating the secondary index.
Updated Catatumbo to use the latest version, 0.7.0, of Google Cloud Java Client for
(November 10, 2016)
Fixed an issue where in some cases a MappingException was thrown when mapping
Deprecated the incorrectly spelled method name (getGneratedKeys) in DatastoreBatch.Response
and DatastoreTransaction.Response interfaces. Created new method, getGeneratedKeys
with the correct spelling.
(November 4, 2016)
Removed the restriction on which data types can exist in a model class (Entity,
Embeddable, MappedSuperClass). Model classes can now have fields of any type (e.g.
java.time.LocalDate from Java 8), as long as there is a registered mapper
to handle the data type.
Fixed an issue where the return value from DatastoreAccess#update methods
may not reflect the changes that the property mappers might have made.
(November 2, 2016)
Added support for mapping embedded objects of an entity to a single property in the
Cloud Datastore (referred to as Embedded Entities in Google Cloud Datastore's
Enhanced the Embedded annotation to optionally specify a property name and
whether or not to index the embedded property.
Introduced two new annotations, @Exploded and
@Imploded, to specify the storage strategy for embedded objects.
These annotations can be applied to an embedded object of an Entity. With
Exploded strategy, which is the default, all primitive fields of the embedded
object are stored as individual properties in the Cloud Datastore. On the
contrary, with the Imploded strategy, the embedded object is stored as a single
property in the Cloud Datastore.
Enhanced the support for mapping Lists, Sets and Maps (together referred to as
The framework now supports all basic types to be part of a collection, provided
the collection is parameterized (Generics).
Raw collections and wildcard collections continue to support the previously
supported data types, Boolean, Long, String, Double and DatastoreKey.
Added support for mapping SortedSets and SortedMaps.
Added Support for persisting BigDecimal types.
Default strategy maps BigDecimal types to Floating Point properties in the Cloud
Added an option to store BigDecimals as "true" Decimals in the Cloud Datastore
without any loss of precision. This option is useful to store currency and any
other decimal types. A new annotation, @Decimal, was introduced to
support this feature. Using this annotation, the precision and scale are
pre-defined on the entity fields. Catatumbo maps these BigDecimal types to
Integer properties while transparently managing the data conversion.
Added support for defining custom Mappers to map fields of the model to/from Cloud
Datastore. A new annotation, @PropertyMapper, was introduced. Using this
annotation, developers can specify the name of the class that implements the Mapper
Added the ability to override the default mappers based on the field type. MapperFactory
exposes a method to set/override the default mappers.
Added the ability to connect and work with a Local Datastore (a.k.a Datastore Emulator).
Added new methods to the EntityManagerFactory to create
EntityManager for Local Datastore.
Enhanced the Mappers for Short, Float, Integer, etc, to raise a MappingException, if the
value read from the Datastore is not within the bounds of the corresponding type.
Updated Catatumbo to use the latest version, 0.5.0, of Google Cloud Java Client for
Removed the deprecated method, DatastoreAccess#executeQuery(). This method was first
deprecated after 0.1.0 version.
Fixed an issue where the Unmarshaller was not calling the Setter method of the model
class when the value read from the Datastore is null.
(October 9, 2016)
Implemented support for Entity Listeners. Entity Listeners help your application to
react to certain events that occur in the persistence mechanism. For example, you could
define a Callback method to trap the PreUpdate event and update certain fields of the
entity, such as Last Modified Timestamp. The following annotations were introduced to
support this feature:
Added support for mapping and persisting of Enum types. Entities,
MappedSuperClasses and Embeddables can now define properties with an Enum
type and Catatumbo takes care of mapping and persistence. Enum types are stored into the
Datastore as String that is same as the name of the Enum
Added support for mapping of java.util.Map and its implementations. Maps
are stored as Embedded Entity in the Google Cloud Datastore. Keys in the Maps are
expected to be of type String. Values in the Map can be of the following types:
Added support for mapping and persisting java.util.Set and its
implementations. Sets are stored as Array properties in the Google Cloud Datastore. Sets
may contain the following types of items:
Enhanced the support for persisting java.util.List. The framework now
supports List and any of its implementations.
Updated the Caching mechanism for EntityMetadata to use an unbounded cache instead of a
Updated Catatumbo to use the latest version, 0.4.0, of Google Cloud Java Client for
(September 21, 2016)
Implemented support for Batch Writes
Enhanced the EntityManager to allow callbacks to run a set of code inside a
Enhanced DatastoreTransaction interface to support insert and upsert (Update or Insert)
with deferred ID allocation
(September 1, 2016)
Added support for persisting inherited fields.
Added a new annotation MappedSuperClass
Entities can extend a class that is tagged as MappedSuperClass.
A MappedSuperClass can extend another MappedSuperClass.
MappedSuperClass can have fields of primitive type and/or Embedded
Ability to override property definitions from the super class using PropertyOverrides
and PropertyOverride annotations.
Added support for Optimistic Locking
Added a new annotation named Version
Version annotation can be applied on any field of type long (primitive)
When updating an entity, the EntityManager ensures that the version
of the entity being updated matches with the version of the entity in the Cloud
Datastore. The update will succeed if the versions match, otherwise an exception
will be thrown. Version property is automatically incremented during each
Updated the Unmarshaller to not always create a new instance of Embeddable, instead if
the Embedded object is already initialized (e.g. during Entity instantiation), use it.
Upgraded to the latest version (0.3.0) of Google Cloud Java Client for Datastore API
(formerly known as gcloud-java-datastore).
(August 23, 2016)
Added support for mapping and persistence of embedded objects. Two new annotations,
Embeddable and Embedded, were introduced to support this
Added two new annotations, PropertyOverrides and
PropertyOverride to override the properties defined in the Embeddable where
Enhanced QueryRequest interfaces/classes to support literals in the query.
Enhanced the support for Array properties. Array properties now support the following
data types, in addition to the previously supported (Long and String):
Updated the version of gcloud-java-datastore API to 0.2.7.
(July 24, 2016)
Added support for Projection queries.
Added support for Key-only queries.
Optimized the deleteAll method by deleting entities in chunks of 100.
Added support for retrieving a list of entities given a list of identifiers or keys.
Added support for UPSERT (Update or Insert) entities.
Added support for GeoLocation data type.
Fixed an issue where the Ignore annotation had no effect and still persisting the
Fixed an issue where String Identifiers are auto generated during update operations.
(July 3, 2016)
Automatic mapping of model classes (POJOs) to Cloud Datastore Entities and vice versa
Ability to map an Object to a an Entity of specified Kind
Ability to map POJO fields to a property
Ability to specify whether or not a field (or property) should be indexed
Ability to ignore certain fields from mapping and persistence
Automatic generation of Identifiers (for both Numeric and String types)
Support for a variety of Data Types:
Keys, Parent Keys and Key References
Create, Retrieve, Update, Delete, Upsert (update or insert)
Support for executing GQL Queries (Entity Queries Only)
Pagination of query results through the use of Cursors
Support for positional and named bindings in the queries
Support for Namespaces (for multi-tenant databases)