Database.com Java SDK

Database.com Data Types

Database.com has its own built-in list of data types optimized for building business applications. To see how these data types map to standard Java data types, see Mapping Database.com to Java Data Types.

Note: Field names in Java classes must start with a lowercase letter to match bean-naming conventions. For example, use String id instead of String Id.

For information on primary key fields, see Primary Keys.

The rest of this section highlights useful information about a subset of Database.com data types. For a list of all the data types, see Mapping Database.com to Java Data Types.

Text Fields

The Database.com Text data type is used for string and character fields.

The length of Text fields is controlled by the length attribute of the @Column annotation. For example:

@Column(length=1)
String flag;

This code defines a Text field called flag of length 1. The default length is 255.

Number Fields

The Database.com Number data type is used for numbers of various sizes. The precision and scale is set by the @Column annotation. For example:

@Column(precision=1, scale=0)
int digit;

This code defines an integer that can range from 0 to 9. The default precision and scale are 18 and 0 for integers and 16 and 2 for floats and doubles. For more information, see Mapping Database.com to Java Data Types.

Auto Number Fields

To create a Database.com auto number field, use @CustomField(type=FieldType.AutoNumber) with an int or Integer Java type. For example:

@CustomField(type=FieldType.AutoNumber)
int referenceNum;

The default start value for the number is 0. Use the optional startValue attribute for a different start value. Auto number fields are read only.

Currency Fields

To create a Database.com currency field, use a BigDecimal Java type. You can also use another number type in Java, but you must add a @CustomField(type=FieldType.Currency) annotation. For example:

@CustomField(type=FieldType.Currency)
double revenue;

Date Fields

Database.com has two date types: Date and Date/Time. Date doesn't include hours, minutes, and seconds. By default, the Database.com JPA provider maps java.util.Calendar to Date/Time and java.util.Date to Date. You can customize this behavior using the JPA @Temporal annotation. For example, the following two Java fields are both mapped to a Date/Time field in Database.com.

java.util.Calendar lastUpdated;

@Temporal(TemporalType.TIMESTAMP)
java.util.Date dateCreated;

Similarly, you can use the @Temporal annotation to map a java.util.Calendar to a Date field. This example maps both Java fields to Date fields.

java.util.Date birthDate;

@Temporal(TemporalType.DATE)
java.util.Calendar transactionDate;

The java.util.GregorianCalendar class can be used instead of java.util.Calendar.

Enumeration (Picklist) Fields

Database.com supports enumerations as a data type. Enumerations are referred to as picklists and multi-select picklists in Database.com terminology. Define picklist values by using a Java enumeration. For example:

public enum Varietal { Cabernet_Sauvignon, Syrah, Pinot_Noir, Zinfandel }

@Enumerated
private Varietal varietal;

By default, Database.com stores ordinal values for the selected value. For example, if you set the varietal variable to Syrah, the value 1 is stored in the database. To store the value strings instead of ordinals, use @Enumerated(EnumType.STRING).

public enum Varietal { Cabernet_Sauvignon, Syrah, Pinot_Noir, Zinfandel }

@Enumerated(EnumType.STRING)
private Varietal varietal;

Database.com also supports multi-value selections. To pick multiple varietals for a single wine, use an array type instead.

public enum Varietal { Cabernet_Sauvignon, Syrah, Pinot_Noir, Zinfandel }

@Enumerated(EnumType.STRING)
private Varietal[] varietal;

Restricted versus Non-Restricted Picklists

Database.com supports two types of picklists: restricted and non-restricted. A restricted picklist only allows valid enumeration values. The field type should match the type of the enum representing the picklist values for picklists or an array of the enum type for multi-select picklists. For example:

public enum Varietal { Cabernet_Sauvignon, Syrah, Pinot_Noir, Zinfandel }

@Enumerated(EnumType.STRING)
private Varietal varietal;

// If this was multi-select, type would be Varietal[] instead
//private Varietal[] varietal;

A non-restricted picklist allows any string value and is not restricted to the enumeration values. Instead of using the enum type, the field type is a String or String[] for picklists and multi-select picklists respectively. To define which enum values available by default, use the custom @PicklistValue annotation. For example:

public enum Varietal { Cabernet_Sauvignon, Syrah, Pinot_Noir, Zinfandel }

@CustomField(type=FieldType.Picklist)
// You could use @Enumerated instead of the @CustomField declaration
//@Enumerated(EnumType.STRING)
@PicklistValue(Varietal.class)
// note the field type is String
private String varietal;

// If this was multi-select, type would be String[] instead
//private String[] varietal;

Since non-restricted picklists are not limited to enum values, they don't support @Enumerated(EnumType.ORDINAL). We recommend that you use @Enumeration for restricted picklists and @CustomField(type=FieldType.Picklist) for non-restricted picklists.

Email Fields

To create a Database.com email field, use @CustomField(type=FieldType.Email) with a String Java type. For example:

@CustomField(type=FieldType.Email)
String orderEmail;

Phone Fields

To create a Database.com phone field, use @CustomField(type=FieldType.Phone) with a String Java type. For example:

@CustomField(type=FieldType.Email)
String orderEmail;

URL Fields

To create a Database.com URL field, use the @Basic annotation with a URL Java type. You need the @Basic annotation to enable persistence for the field because URL is not one of the Java types that is persisted by default. For example:

@Basic
URL companyUrl;

Percent Fields

To create a Database.com percent field, use @CustomField(type=FieldType.Percent) with any Java type that maps to a Database.com Number field, such as int or double. For example:

@CustomField(type=FieldType.Percent)
int mainVarietalPercent;

Formula Fields

A formula is a field whose value is derived from other fields, expressions, or values. For more information about formula fields, see Building Formulas.

To create a Database.com formula field, use a @CustomField annotation with a String Java type. For example:

@CustomField(type=FieldType.Text, formula="formulaValue")
String snazzyFormula;

Formula fields are read only. A formula can return a Currency, Date, DateTime, Number, Percent, or Text FieldType. To see how these types map to Java data types, see Mapping Database.com to Java Data Types.

Use the optional treatBlankAs attribute to control how blank values are interpreted. The default value is TreatBlanksAs.BlankAsBlank.

Relationship Fields

Database.com supports two types of relationships between entities: Lookup and Master-Detail. You can perform join queries on entities connected by a relationship field.

Master-Detail

A master-detail relationship links entities so that the master record controls certain behaviors of any detail records. For example, when a master record is deleted, the related detail records are also deleted. The ownership and security settings of a detail record are determined by the master record and can't be changed for a detail record.

Lookup

A lookup relationship is a foreign key to another entity, but it has no effect on deletion, record ownership, or security settings.

For more details on working with Lookup and Master-Detail fields, see Overview of Relationships.

Define Lookup or Master-Detail relationship fields in Java classes by using a @ManyToOne annotation on the field in the class on the many side of a relationship and a @OneToMany annotation on the field in the class on the one side of the relationship. The following sections include code examples for Lookup and Master-Detail fields.

@ManyToOne Annotation

Use the @ManyToOne annotation on a field to model the many side of a relationship. By default, the Database.com JPA provider maps this annotation to a Lookup relationship field. Use an @CustomField(type = FieldType.MasterDetail) annotation to define it as a Master-Detail relationship field instead.

For example, if a Wine Java entity has a many-to-one relationship to a Producer entity, the relationship is defined in the Wine entity as a producer Lookup field with a @ManyToOne annotation.

@ManyToOne
private Producer producer;

To set the Lookup field name in Database.com to be something other than producer, use the @Column annotation.

@Column(name = "wine_producer")
@ManyToOne
private Producer producer;

Change the Lookup field to a Master-Detail field by including an @CustomField(type = FieldType.MasterDetail) annotation.

@ManyToOne
@CustomField(type = FieldType.MasterDetail)
private Producer producer;

@OneToMany Annotation

Use the @OneToMany annotation to model the one side of a relationship. Every @OneToMany annotation must have a field with a @ManyToOne annotation on the many side of the relationship. The Database.com JPA provider requires that an @OneToMany annotation must include a mappedBy attribute with a value matching the foreign key field name in the related JPA entity.

For example, a Producer entity with a one-to-many relationship to the Wine entity could point to a collection of wines. The mappedBy attribute value is producer to match the field name of the Lookup field in the Wine entity.

@OneToMany(mappedBy="producer")
private Collection<Wine> wines;

To automatically persist all new child records in a collection when you persist a new parent record, see the CascadeType.PERSIST attribute for the parent @OneToMany field. You must explicitly set the parent field for each child record in the collection. In this example, you must set the producer field for each Wine in the collection.

The Database.com JPA provider supports List, Set, and Map collections for an @OneToMany field on the one-side of the relationship.The Database.com JPA provider dynamically builds these collections and doesn't explicitly store them in Database.com.

The default key for a Map is the id field. The value of the id field for a new object is null until the object is persisted to Database.com so you can only insert one new entry into a map using the default key. The alternative is to use the @MapKey standard annotation to set a different field as the key. Entries must have a unique key value. To continue the earlier example, the Producer entity could use a map to track the related wines. The key of the map is the wine name.

@OneToMany(mappedBy="producer")
@MapKey(name="wineName")
private Map<String, Wine> wines;

Note: You can't mark an @OneToMany field with a FetchType.EAGER attribute. For more information, see Eager Versus Lazy Fetch Types.

Unsupported JPA Annotations

The Database.com JPA provider doesn't support:

  • One-to-one relationships using the @OneToOne annotation-Merge the entities into one entity instead.
  • Many-to-many relationships using the @ManyToMany annotation-Use a custom junction entity with two @ManyToOne relationship fields connecting the two entities instead.

Cascading Persistence and Deletion

JPA defines attributes that control cascading behavior for relationship fields. For example, if record A references record B, a cascading deletion of record A would also delete record B. The Database.com JPA provider supports a subset of the JPA cascading attributes for @OneToMany fields and ignores any cascading attributes for @ManyToOne fields. The supported attributes for @OneToMany fields are:

CascadeType.PERSIST

When this attribute is enabled, persisting a new parent record also persists all new child records in its collection if you explicitly set the parent field for each child record in the collection. Otherwise, it is up to you to persist child records individually as well as the parent in the same transaction.

CascadeType.REMOVE

When this attribute is enabled for Lookup fields, removing a parent entity also removes all child entities in its collection. Otherwise, it is up to you to remove child entities individually. This attribute is always enabled for Master-Detail fields. Removing a parent Master-Detail always removes its children.

CascadeType.MERGE

When this attribute is enabled, merging (updating) an existing parent entity merges the child entities in its collection. CascadeType.MERGE or CascadeType.ALL doesn't persist new child entities in its collection, even when they have their parent field set. Persist any new child entities separately.

CascadeType.ALL

Shorthand for enabling all supported cascade types.

The following JPA attributes are not configurable for @OneToMany fields. This list explains the behavior related to these attributes for the Database.com JPA provider.

CascadeType.REFRESH

Refreshing a parent entity always refreshes the child entities in its collection.

CascadeType.DETACH

Detaching a parent always detaches the child entities in its collection.

For more information on cascading attributes, see the DataNucleus documentation.

Binary (Base64) Fields

Database.com only supports binary values for Attachment, Document, or Scontrol standard objects. You can't use byte[] fields to represent binary (blob) data in custom Database.com entities.

In Java classes representing Attachment, Document, or Scontrol standard objects, use a byte[] field for the base64–encoded data in the Body or Binary field. The BodyLength field defines the length of the data in the Body or Binary field. In the Document object, you can specify a URL to the document instead of storing the binary data directly in the record.

A sample Java class representing a Document includes body and bodyLength fields:

public class Document {
    // base64-encoded binary data
    private byte[] body;
    // size of the binary data in bytes
    private int bodyLength;

    // more fields
}