Release Notes
2.7.0
(March 9, 2019)
- Enhanced the
QueryResponse
to provide access to metadata of the response (QueryResponseMetadata
). This metadata can be used to determine the status of query execution/whether or not there are more results after the last cursor/limit.
- Upgraded the underlying client library to the latest version, 1.64.0.
2.6.0
(September 30, 2018)
- Updated the Optimistic Locking/Entity Versioning to use the parent transaction, if one exists.
- Upgraded the underlying client library to the latest version, 1.46.0.
2.5.0
(February 19, 2018)
- 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.
2.4.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.
2.3.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
update operation
- 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.
2.2.0
(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.
2.1.0
(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).
2.0.0
(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:
- OffsetDateTime
- ZonedDateTime
- Enhanced the Query Parameter bindings (positional and named) to support all new types from the java.time
package.
- Upgraded the underlying google-cloud-datastore API to the latest version, 1.0.0-rc2.
1.4.0
(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
EntityManagerException
.
- Upgraded the underlying google-cloud-datastore API to the latest version, 0.9.4-beta.
1.3.1
(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
this.
- Added support for retrieving the Datastore Metadata. The new Metadata API (
DatastoreMetadata
)
allows -
- 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:
DatastoreBatch.Response#getGneratedKeys()
DatastoreTransaction.Response#getGneratedKeys()
- Updated Catatumbo to use the latest version, 0.9.3, of Google Cloud Java Client for Datastore API.
1.2.1
(February 5, 2017)
-
DefaultDatastoreKey
was modified to implement java.io.Serializable
interface to
allow serialization.
1.2.0
(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 accordingly.
- Updated Catatumbo to use the latest version, 0.8.3, of Google Cloud Java Client for Datastore API.
1.1.3
(December 13, 2016)
1.1.2
(December 11, 2016)
- Updated the below Exceptions to extend EntityManagerException:
- MappingException
- NoSuitableMapperException
- IndexingException
- NoSuitableIndexerException
- Updated Catatumbo to use the latest version, 0.8.0, of Google Cloud Java Client for
Datastore API.
1.1.1
(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
feature:
-
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
Datastore API.
1.0.2
(November 10, 2016)
- Fixed an issue where in some cases a MappingException was thrown when mapping
float/Float types.
- Deprecated the incorrectly spelled method name (
getGneratedKeys
) in DatastoreBatch.Response
and DatastoreTransaction.Response
interfaces. Created new method, getGeneratedKeys
with the correct spelling.
1.0.1
(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.
1.0.0
(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
terminology).
- 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
Collections)
- 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
Datastore
- 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
interface.
- 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
Datastore API.
- 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.
0.6.1
(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:
- EntityListeners
- EntityListener
- ExcludeDefaultListeners
- ExcludeSuperclassListeners
- PreInsert
- PostInsert
- PreUpdate
- PostUpdate
- PreUpsert
- PostUpsert
- PreDelete
- PostDelete
- 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
constant.
- 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:
- Boolean
- String
- Long
- Double
- DatastoreKey
- 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:
- Boolean
- String
- Long
- Double
- DatastoreKey
- 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
fixed LRUCache.
- Updated Catatumbo to use the latest version, 0.4.0, of Google Cloud Java Client for
Datastore API.
0.5.1
(September 21, 2016)
- Implemented support for Batch Writes
- Enhanced the EntityManager to allow callbacks to run a set of code inside a
transaction
- Enhanced DatastoreTransaction interface to support insert and upsert (Update or Insert)
with deferred ID allocation
0.4.0
(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
objects
- 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
update.
- 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).
0.3.0
(August 23, 2016)
- Added support for mapping and persistence of embedded objects. Two new annotations,
Embeddable
and Embedded
, were introduced to support this
feature.
- Added two new annotations,
PropertyOverrides
and
PropertyOverride
to override the properties defined in the Embeddable where
needed.
- 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.
0.2.0
(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
field.
- Fixed an issue where String Identifiers are auto generated during update operations.
0.1.0
(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:
- boolean, Boolean
- char, Character
- short, Short
- int, Integer
- long, Long
- float, Float
- double, Double
- String
- Byte Arrays
- Char Arrays
- Date
- Calendar
- Keys, Parent Keys and Key References
- List Values
- Null
- 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
- Transaction Support
- Support for Namespaces (for multi-tenant databases)
- Lightweight, easy to use and fully documented API