Java SDK

Custom Annotations

As well as supporting standard JPA annotations, has defined custom annotations for behavior specific to

Use @CustomObject to enable feed tracking in Chatter for a new custom object ( entity) or mark it as read only.
Read More
Use @CustomField to set some of the attributes of a custom field when you create a field in a Java class that maps to a new custom field in
Read More
Use @PicklistValue to define which enum values are available by default in a non-restricted multi-select picklist.
Read More
Use @JoinFilter to include a WHERE clause to filter the returned child collection or map in an implicit JPQL query join.
Read More


Use @CustomObject to enable feed tracking in Chatter for a custom object ( entity) or mark it as read only.

Enabling Feed Tracking

Enable objects for feed tracking so people can follow records of that object type and see Chatter feed updates when records of that object type are created. For example, if you enable feed tracking for a Student custom object, users can follow Student records and see feed updates when they create students.

To create a new custom object and enable feed tracking for it:

  • Add an @Entity annotation to the class. The custom object is not created if you don't include this annotation, as well as the @CustomObject annotation.
  • Set the enableFeeds attribute of @CustomObject to true. The default value for this attribute is false.

For example:

@CustomObject(enableFeeds = true)
public class Student
    // class details here

The custom object is created when your application starts and the Java class loads. When the custom object is created, custom fields corresponding to all of the fields in the class are also created.

Note: If you add a @CustomObject annotation to a Java class that already exists as a custom object in, the @CustomObject annotation is ignored. For example, if a Student custom object already exists in your organization and feed tracking in Chatter is not enabled for it, adding @CustomObject(enableFeeds = true) to the Student Java class does not enable feed tracking. Use the user interface in Salesforce to enable feed tracking for an existing custom object.

Marking Object (Entity) Read-Only

Use the readOnlySchema attribute to mark an entity as read only. If you set readOnlySchema = true, it ensures that the schema will not be deleted when the force.purgeOnDelete property is set in your application's persistence.xml file.


Use @CustomField to set some of the attributes of a custom field when you create a field in a Java class that maps to a new custom field in For example, you can set the name, description, and length of the new custom field. If the custom field already exists, the @CustomField annotation has no effect.

The custom field attributes that you can set are:

Custom Field Attribute Field Type Description Default Value
childRelationshipName String The child relationship name for lookup or master-detail fields. If a value is not specified for this field, it is automatically set to ParentObjectName_ChildObjectNames__r, where ParentObjectName is the parent object for a lookup field or the master object for a master-detail field. If this name is more than 40 characters, it is truncated.

For more information about relationship names, see the Web Services API Developer's Guide.

See the Description column.
description String Description of the field.
enableFeeds boolean Indicates whether the field is enabled for feed tracking (true) or not (false). To set this field to true, the enableFeeds attribute on the object containing this field must also be true. false
externalId boolean Indicates whether the field is an external ID field (true) or not (false). false
label String Label for the field.
length int Length of the field.
name String The name of the field used for API access.
precision int The precision for number values. Precision is the number of digits in a number. For example, the number 256.99 has a precision of 5.
scale int The scale for the field. Scale is the number of digits to the right of the decimal point in a number. For example, the number 256.99 has a scale of 2.
type String The field type for the field. The valid values are:
  • FieldType.AutoNumber
  • FieldType.Lookup
  • FieldType.MasterDetail
  • FieldType.Checkbox
  • FieldType.Currency
  • FieldType.Date
  • FieldType.DateTime
  • FieldType.Email
  • FieldType.EncryptedText
  • FieldType.Number
  • FieldType.Percent
  • FieldType.Phone
  • FieldType.Picklist
  • FieldType.MultiselectPicklist
  • FieldType.Summary
  • FieldType.Text
  • FieldType.TextArea
  • FieldType.Summary
  • FieldType.Url
  • FieldType.Hierarchy
  • FieldType.File
  • FieldType.CustomDataType
  • FieldType.Html

For more information about field types, see Custom Field Types.


Sample Class Using Custom Annotations

The following sample Java class uses custom JPA annotations.

import java.util.Date;
import javax.persistence.*;

@CustomObject(enableFeeds = true)
public class Student
    String id;

    @CustomField(type = "Text", label="First Name", length=100)
    private String firstName;

    @CustomField(type = "Text", label="Last Name", length=100)
    private String lastName;

    @CustomField(type = "Text", label="Email", length=255)
    private String email;

    @CustomField(type = "Date", label="Date of Birth")
    private Date dateOfBirth;

    // Getters and setters not used by JPA.
    // They are used by your code when you are persisting records.

    public String getId() {
        return id;

    public String getFirstName() {
        return firstName;
    public void setFirstName(String firstName) {
        this.firstName = firstName;

    public String getLastName() {
        return lastName;
    public void setLastName(String lastName) {
        this.lastName = lastName;

    public String getEmail() {
        return email;
    public void setEmail(String email) { = email;

    public Date getDateOfBirth() {
        return dateOfBirth;
    public void setDateOfBirth(Date dateOfBirth) {
        this.dateOfBirth = dateOfBirth;


Mixing Standard and Custom Annotations

You can mix standard JPA and custom annotations in the same Java class. However, custom annotations take precedence if there is an overlap in functionality. In the following example, the @CustomField annotation takes precedence over the standard JPA @Column annotation. The counter field gets a precision of 11 and a scale of 0.

@CustomField(precision=11, scale=0)
@Column(precision=17, scale=0)
private int counter;