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)

• 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)

• Fixed an issue with the way Catatumbo was determining the accessor method names for the fields of an entity. In some rare cases, the expected method names were not matching with the method names produced by popular IDEs. For example, if you have a field named aUser, Catatumbo was expecting setAUser and getAuser methods, while the IDEs generate setaUser and getaUser. This fix makes Catatumbo to be compliant with IDEs and JavaBeans standards. See Issue #96 for more details.
  
  
  Though it is unlikely, this release may not be 100% backward compatible, if your entities have field names like the one mentioned above. You may need to update the accessor method names.

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):
  • Keys
  • Double
  • Boolean
• 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