Using the Database.com Java SDK

If you’re a Java developer reading this blog (i.e. you have some interest in the Force.com platform), you’ve probably heard of Java on Heroku – one the biggest announcements at this year’s Dreamforce. You can now “slip the surly bonds” of your local J2EE app server by deploying your Java apps to Heroku and taking advantage of all the benefits that a polygot PAAS platform like Heroku provides. Java on Heroku has deservedly gotten a lot of attention and press and if you’re interested in learning more, check out this great Dreamforce session recording by the very esteemed James Ward. There was however another exciting Java related announcement around the time of Dreamforce that you may have missed – the Beta release of the Database.com Java SDK. I’d like to spend some time talking about the SDK and so lets break it down.

1) So, it’s an SDK for Database.com? – Yes and no. Even though the official name for the SDK is the ‘Database.com Java SDK’, you can use it to connect to both Database.com and Force.com/Salesforce.

2), Got it. So what is it? At the highest level, the SDK provides a JPA 2.0 interface to Database.com/Force.com. If allows any Java application to use Database.com or Force.com as their persistence/data layer and use the standard JPA interface provided by the SDK to query and update data from our platform. And the SDK is completely runtime agnostic in that you can deploy your application to a cloud environment that supports Java (e.g. Heroku), or to a local J2EE container – the SDK works in all cases. In addition to a JPA interface, the SDK also has a couple of other very important components/value adds.

3) But I can already connect my Java app to Database.com/Force.com. Why do I need the SDK? – Its true that Java applications (or any other language/platform for that matter) have always been able to integrate with Force.com using one of our APIs – for e.g. the Web Services (SOAP) API or the REST API. What’s different with the SDK is that you can now use a J2EE standard – JPA – to do the same. No WSDL/XML/JSON  to parse or consume – simply use the standard ORM functionality provided by JPA and simplify and standardize your Java code. Other than the JPA provider, the SDK also has other components that provide additional value-adds to Java developers.

4) How is the SDK related to Java on Heroku? – As mentioned before, the SDK has absolutely no direct dependency on Java on Heroku. You can use the SDK no matter what you runtime environment. The only real intersection of the two is if you wanted to deploy a Java application to Heroku that used Database.com/Force.com as its persistence layer.

5) What are the various components of the SDK?

5.1) JPA Provider: The most important component of the SDK is obviously the JPA 2.0 provider. Here is quick snippet from a Java application that uses a simple ‘Album’ Entity with a Many-to-One relationship to the ‘Artist’ Entity.

@Entity
public class Album {

    @Id
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    private String id;

    private String name;

    @DateTimeFormat(iso=ISO.DATE)
    @Column(nullable = false)
    private Date releaseDate;

    @ManyToOne
    @CustomField(type= FieldType.MasterDetail)
    private Artist artist;
    ....
    //Public accessor and mutator methods for the above variables
}

Anyone familiar with JPA will instantly recognize this code. JPA uses a POJO based persistence model and relies heavily on annotations – both of which you can see in the above snippet. The SDK supports most of the standard JPA annotations and adds a couple of custom ones (e.g. the ‘@CustomField(type= FieldType.MasterDetail)’ used above). Here is another small snippet of how you can query and update data from the Album entity using the SDK.

public static EntityManagerFactory emf = 
                  Persistence.createEntityManagerFactory("forceDatabase");

public void saveArtistRecord(Artist artist) {
    EntityManager em = emf.createEntityManager();
    EntityTransaction tx = em.getTransaction();
    tx.begin();

    if(artist.getId()==null) {
		em.persist(artist);
	} else {
		artist = em.find(Artist.class, artist.getId());
		artist =  em.merge(artist);
	}

	tx.commit();
}

public static List<Album> getAlbumsByName(String albumName) {
	if(albumName==null) {
		throw new IllegalArgumentException("Album name cannot be null");
	}

	EntityManager em = emf.createEntityManager();

	String jpqlQuery = "SELECT a FROM Album a WHERE a.Name LIKE '%s'";
	jpqlQuery =	String.format(jpqlQuery,albumName);

	List<Album> albums = em.createQuery(jpqlQuery).getResultList();
	return albums;
}

Its all standard JPA code, including the use of JPQL (which the SDK supports) to query Database.com/Force.com data. Under the covers, the Album and Artist Entities will be mapped by the SDK to corresponding Custom Objects in the respective Database.com/Force.com Org. The SDK can even keep your data model in sync automatically. If you add a new Entity class (or a new field to an existing Entity class) and restart your application, the SDK will automatically detect these schema changes and create the custom object/field automatically in Database.com/Force.com.

5.2) OAuth and Spring Security: The SDK also has an OAuth component that lets you delegate the authentication and authorization for your Java web app to Salesforce. You only have to configure a couple of OAuth parameters (not a single line of code required) and every time a user tries to access your Java app they will be redirected to Salesforce to login and then redirected back to your Java app. The SDK also includes a Spring Security plugin that “wraps” this OAuth component and lets you delegate security for Spring MVC apps to Salesforce.

5.3) Maven Code generation plugin: Though not technically part of the SDK, I still see this as another component of the SDK. If you have your data model already defined in Database.com/Force.com using some Standard and/or Custom Objects, you can run a simple Maven command and generate the corresponding JPA Entity classes. This cuts down on your development time significantly.

6) This all sounds great! How do I get started? Check out the SDK’s home page for additional details and to get started. You can also watch a recording of the Dreamforce session where I previewed the SDK.

Published
October 3, 2011

Leave your comments...

Using the Database.com Java SDK