spec

Spec

Operation names

An operation on an entity is represented as a method call:

api.<operation><entity>[plural]([appname],[requestobject | flattened arguments]);

with angular brackets meaning required, square brackets meaning optional. For example:

Type mapping

Any operation that returns an SObject entity should support "late mapping", so the user can choose dynamic typing or binding to a proper Java class.

Example use

List API versions

List<ApiVersion> l = ForceApi.listVersions();

This is a static method. No authentication is required.

Create new API instance

ForceApi api = new ForceApi(apiSession);

This creates a new api instance. API session instance contains session key and api version. An instance of ForceApi is always pegged to one API version.

List resources

List<String> res = api.listResources();

lists the resources available for this session and API version

Get SObject info

OrgSObjectInfo res = api.getOrgSObjectInfo();

res.getMaxBatchSize(); // => 200
res.getEncoding(); // => "UTF-8" 

res.getSObjectMetadata()[0].getName(); // => "Account"

Get Metadata details for an SObject type

SObjectInfo res = api.getSObjectInfo("Account");

res.getMetadata().getName(); // "Account"

res.getRecentItems().asListOf(Account.class)[0].getAnnualRevenue();

Get full metadata

SObjectMetadata res - api.getFullSObjectMetadata("Account");

res.getFields().get("name").getLength(); // => 18

Get SObject

Account res = api.getSObject("Account", "001D000000INjVe").as(Account.class);

Get blob field of SObject

byte[] blob = api.getSObjectBlobField("Account","001D000000INjVe","blobField").asBytes();

InputStream blob = api.getSObjectBlobField("Account","001D000000INjVe","blobField").asStream();

Query

Instead of just a List<?> we need a dedicated QueryResult class so we also capture metadata like totalSize.

QueryResult<Account> result = api.query("SELECT id FROM Account",Account.class);
System.out.println(result.getTotalSize());
System.out.println(result.getRecords().get(0).getName());

Search

Untyped:

List<SObject> res = api.search("FIND test");

Typed:

Map types = new HashMap<String,Class>();
types.put("account", Account.class);
List<? extends SObject> res = api.search("FIND test", types);

Create a new SObject record

try {
    String id = api.createSObject("account", new Account().setName("Salesforce.com"));
} catch(OperationFailedException e) {
    // extends RuntimeException
    System.out.println(e.getErrors()[0].getFields()[0]+" "+e.getApiErrorCode());
}

Update an SObject record

try {
    api.updateSObject("account", new Account().setId("001D000000INjVe").setName("Salesforce.com, Inc."));
} catch(OperationFailedException e) {
    // extends RuntimeException
    System.out.println(e.getErrors()[0].getFields()[0]+" "+e.getApiErrorCode());
}

Create or update an SObject record

(create if not exists or update if exists, aka upsert)

try {
    String id = api.createOrUpdateSObject("account", new Account().setName("Salesforce.com"));
} catch(CreateOrUpdateException e) {
    // extends OperationFailedException
    System.out.println(e.getErrors()[0].getFields()[0]+" "+e.getApiErrorCode());
    if(e.getResponseCode()==300) {
        // multiple matches
        for(Account a: e.getMatchingRecords().asListOf(Account.class)) {
            
        }
    }
}

Delete an SObject record

api.deleteSObject("account", "001D000000INjVe");

Blob content

Unclear if this only works for document objects or any sobject.

(requires special flag, not generally available yet)

api.createDocument(new Document()
        .setDescription("Marketing brochure for Q1 2011")
        .setKeywords("marketing,sales,update")
        .setFolderId("005D0000001GiU7")
        .setName("Marketing Brochure Q1")
        .setType("pdf")
        .setContentAsStream(inputStream));

or

api.createDocument(new Document()
        .setDescription("Marketing brochure for Q1 2011")
        .setKeywords("marketing,sales,update")
        .setFolderId("005D0000001GiU7")
        .setName("Marketing Brochure Q1")
        .setType("pdf")
        .setContentAsBytes(byteArray));

Update an existing document blob