Using the Enterprise API
At the highest level, the Enterprise API consists of core services that allow query and modification of Force.com data, plus a set of types reflecting the standard and custom objects defined in your Force.com organization. Using these core services and types is a fairly straightforward exercise after your code has established a session with Force.com.
This section divides the Enterprise API into four functional groups, described here:
1. Retrieving records—Retrieve records using SOQL or SOSL queries, by unique identifier, or based on their modification or deletion time stamp.
2. Writing records—Learn how to create and update records using the Enterprise API.
3. Deleting and undeleting records—By deleting records, you send them to the recycling bin, where they can later be undeleted if necessary.
4. Modifications in bulk—Modifications can be performed on up to 200 records at a time to conserve API calls and improve performance.
Retrieving Records
The most common way to retrieve records is via SOQL. This is accomplished with the query service. A SOQL statement is passed as input, and a QueryResult object is returned. This object contains an array of records returned by the query.
The number of records returned by the query service is a function of the batch size. The default batch size in Java using WSC is 2,000 records, 500 for Axis and other Web service clients. If a query result contains more records than the batch size, use the queryMore service to retrieve additional batches of records.
The code in Listing 10.17 demonstrates the query and queryMore services in Java to build a list of Project records.
Listing 10.17 Java Fragment to Execute SOQL Query
List<Project__c> projects = new ArrayList<Project__c>();
QueryResult qr = connection.query("SELECT Id, Name FROM Project__c");
boolean done = false;
if (qr.getSize() > 0) {
while (!done) {
SObject[] records = qr.getRecords();
if (records != null) {
for (SObject record : records) {
projects.add((Project__c)record);
}
if (qr.isDone()) {
done = true;
} else {
qr = connection.queryMore(qr.getQueryLocator());
}
}
}
}
You can set a custom batch size (up to 2,000 records) by providing a QueryOptions header. This is demonstrated in Java in Listing 10.18.
Listing 10.18 Java Fragment for Setting Query Batch Size
connection.setQueryOptions(2000);
There’s no guarantee Force.com will return the requested number of records in a batch. For example, if a SOQL statement selects two or more custom fields of type long text, the batch size will never be more than 200 records. Queries on binary data always return a single record at a time.
Other Ways to Retrieve Records
A few other approaches are available for retrieving records, described next:
Using SOSL—The search service executes a SOSL statement and returns a Search Result object, which contains an array of SearchRecord objects. Each SearchRecord contains an SObject instance representing a matching record. Because SOSL can return many object types, each SearchRecord object can contain a different type of SObject.
By unique identifier—If you know the unique identifier of an object, you can retrieve it by using the retrieve service. Its inputs are a string containing a comma-separated list of field names to retrieve, the type of object as a string, and an array of up to 2,000 record unique identifiers. It returns an array of SObject instances.
By time stamp—The getUpdated and getDeleted services return the unique identifiers of records updated or deleted between a range of dates.
Writing Records
The basic services for writing records closely resemble their counterparts in Apex code. Services exist for creating, updating, upserting, deleting, and undeleting records. These services can accept one record at a time or up to 200 records in a single invocation.
Creating Records
To create one or more records, invoke the create service, passing in an array of SObjects. Each SObject must contain at a minimum the values for the required fields defined on the object. The service returns an array of SaveResult objects. Each SaveResult indicates success or failure of an individual record. In the case of failure, the SaveResult also contains an array of Error objects indicating the error reason.
The code in Listing 10.19 demonstrates the create service in Java. It creates a Contact record from the values of firstName and lastName.
Listing 10.19 Java Fragment to Create Record
Contact contact = new Contact();
contact.setFirstName(firstName);
contact.setLastName(lastName);
SaveResult[] result = connection.create(
new SObject[] { contact });
if (result != null && result.length == 1) {
if (result[0].isSuccess()) {
System.out.println("Created contact with Id: "
+ result[0].getId());
} else {
System.out.println("Failed to create contact: " +
result[0].getErrors()[0].getMessage());
}
}
Updating Records
To modify existing records, use the update service. Its arguments and return value are identical to those of the create method. The major difference is that the SObjects must contain a value for the Id field. This value is the unique identifier of the record to be updated.
Use the upsert service when you want to create records that don’t exist and update them if they do exist. To determine whether a record exists, the upsert service examines a field containing unique identifiers. This field can be the internal Id field or a custom field designated as an external identifier. The first argument to the upsert service is the name of the unique identifier field, and the second is an array of SObjects. The service returns an array of UpsertResult objects. Like the SaveResult object, it contains a success or failure indicator and an array of errors upon failure.
Note
You must perform an additional step to set fields to null during an update or upsert. Each object instance has a special array field called fieldsToNull. To set a field to null, add the name of the field to this list.
Deleting and Undeleting Records
To delete records, call the delete service and pass in an array of record unique identifiers to delete. Unlike the other DML operations, delete accepts different types of objects in a single call. The service returns an array of DeleteResult objects indicating the success or failure of each deletion, as well as any error messages.
The undelete service restores deleted records from the Recycle Bin. Its input is a list of record unique identifiers, and it returns an array of UndeleteResult objects for use in tracking the outcome of each undeletion.
Modifications in Bulk
Bulk modifications involve more than one record. You can create, update, upsert, delete, or undelete a maximum of 200 records in a single call. By default, Force.com allows partial failure, meaning some records can fail while others succeed. To override this behavior, add the AllOrNoneHeader to the call and set it to true. This causes Force.com to roll back all modifications made by the call unless all records are successfully processed.
The ability to process multiple object types in a single call is a powerful feature of bulk modifications. This is supported on create, update, delete, and undelete operations, but not upsert. For example, you can create a Resource and Skill in one round-trip to Force.com. This requires that the Skill record references its parent Resource using an external identifier rather than an Id because an Id for the record doesn’t exist yet.
There are several important limitations of bulk create and update calls that involve multiple object types:
Up to ten unique object types are allowed per call.
You can’t reference a new record of the same type in a single call. For example, if two Contact records were related to each other, you would need to create the parent first and then create the child and relate it to the parent in a separate call.
If there are related records in the call, parent records must be located ahead of child records in the request.
You cannot modify records of multiple object types if they participate in the Salesforce Setup menu. This limitation includes custom settings objects, GroupMember, Group, and User.