Utilities and Add-ons for Objectify
Java XML
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
.gitignore
.travis.yml
README.md
pom.xml

README.md

Objectify-Utils (Objectify Utilities for Google Appengine)

Build Status Coverage Status

Objectify-Utils contain various utility and extension classes to augment Objectify 5 including Objectify Translators for enhanced handling of large numbers, Joda-Money, and Joda-Time types.

Note that objectify-utils no longer includes a sharded-counter implementation. Instead, we recommend using this one: https://github.com/oodlemud/appengine-counter

Additionally, versioning of Objectify-Utils has been realigned to coordinate with release versions of Objectify-Appengine. Thus, the most recent version of this library is 5.1.x.

Features

To read more about this in the Objectify-Appengine discussion groups, see here.

  • Enhanced Objectify Translators for Guava Optional Types
    Utilize Optional<String> properties in your Objectify @Entity classes.

  • Enhanced Annotations and Translators for Joda "Money" Types
    Store entities with Joda-Money properties in interesting ways, fully controllable via field annotations.

    • Fully Indexable BigDecimal and Money Fields
      Whether your property is of type BigDecimal, Money, or BigMoney, the Translators in objectify-utils store all number values in an encoded String-format that is lexigraphically equivalent to numeric values when it comes to comparison. This encoding format supports negative values, meaning currency values can be fully indexed, sorted, and queried natively via the Datastore.

    • Arbitrary Precision
      Objectify-utils translators allows for arbitrary number-precision across and inside entities. For example, one "Car" entity with a "value" property of "$25,000.00" could be stored while another "Car" could have a more precise value of "$25,000.253".

    • Anotation Support for Joda Money and BigMoney
      Joda-Money and Joda-BigMoney both implement a common interface (BigMoneyProvider), making it possible to utilize the same translator for both object types.

    • Full Currency Code Support
      JodaMoneyTranslatorFactory can store a currency-code for any Money/BigMoney object in a different embedded field that is related to the currency value amount.

    • Full Index Control and Field Name Customization
      Using the @BigDecimal and @Money annotations, you can control how your Number and Currency information is stored, what is indexed, and what each embedded field is called.

    • Objectify-Appengine Discussion Threads

    • Further Reading

Note: The current release of this library is not compatible with Objectify versions prior to version 5.1.x. See the changelog for previous version support.

Getting Started

Download the latest objectify-utils and include it your application's classpath.

Maven users should utilize the following dependency instead:

<dependency>
  <groupId>com.sappenin.objectify</groupId>
      <artifactId>objectify-utils</artifactId>
      <version>5.1.3</version>
</dependency>

Next, be sure to register any annotations that you plan to use, as follows:

ObjectifyService.factory().getTranslators().add(new BigDecimalEmbeddedEntityTranslatorFactory());
ObjectifyService.factory().getTranslators().add(new JodaMoneyEmbeddedEntityTranslatorFactory());
ObjectifyService.factory().getTranslators().add(new UTCReadableInstantDateTranslatorFactory());
ObjectifyService.factory().getTranslators().add(new OptionalStringTranslatorFactory());

BigDecimal Entity Fields

To persist properties of type java.math.BigDecimal, annotate your field with the @com.sappenin.objectify.annotations.BigDecimal. Be sure to not confuse this with the default BigDecimal support provided by Objectify which doesn't handle indexing properly (see here for more details).

Example configuration:

@Entity
public class OfyEntity
{

    ... //Rest of Objectify4 Entity definition

    @com.sappenin.objectify.annotations.BigDecimal
    BigDecimal bigDecimal;
}

Note that the @Index field is optional since Indexing is controlled via the @BigDecimal annotation.

Joda-Money Entity Fields

To persist properties of type com.joda.money.Money or com.joda.money.BigMoney, annotate your field with the @com.sappenin.objectify.annotations.Money annotation.

Example configuration:

@Entity
public class OfyEntity
{

    ... //Rest of Objectify Entity definition

    @com.sappenin.objectify.annotations.Money
    org.joda.money.BigMoney bigMoneyAmount;

    @com.sappenin.objectify.annotations.Money
    org.joda.money.Money moneyAmount;

}

Note that the @Index field is optional since Indexing is controlled via the @BigDecimal annotation.

Change Log

Version 5.1.3 Version 5.1.2 Version 5.1.1

  • No changes; Sonatype Deploy Fixes in pom.

Version 5.1.0

  • Update to Objectify 5.1.x.
  • Update App Engine, Joda, Lombok, and Guava versions to latest.
  • Update README.md with updated documentation.

Version 5.0.2

  • Now aligning objectify-utils versioning with objectify major and minor releases (i.e., 5.x.y)
  • Update Translators for Objectify 5.0.x.
  • Update README.md with updated documentation.
  • Update App Engine, Joda, Lombok, and Guava versions to latest.

Version 2.3.7

  • Fix Sonatype failure

Version 2.3.6

  • Added translator for Guava Optional Strings that allows entities to contain an Optional field and serialize/deserialize properly to/from a DataStore entity.

Version 2.3.5

  • Fix Sonatype failure

Version 2.3.4

  • Updated dependencies
  • Official Release to Sonatype

Version 2.3.0

Version 2.2.1

  • Added missing #build to ShardedCounterServiceConfiguration.Builder
  • Updated to Appengine: 1.8.1 (provided)

Version 2.2.0

  • Updated to Appengine: 1.8.0 (provided)
  • Updated to Objectify: 4.0rc1 (provided)
  • Now compiled with Java 7

Version 2.1.0

  • Updated to Appengine: 1.7.6 (provided)
  • Updated to Objectify: 4.0b2 (provided)
  • Updated to Joda Time: 2.2
  • Updated to Joda Money: 0.8
  • Updated to Guava: 14.0.1

Version 2.0.0

  • Updated to Objectify 4.0

Authors

David Fuelling

Copyright and License

Copyright 2013 Sappenin Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.