Hibernate Language Binding Guide For The Connection Cloud Using Java Persistence API (JAP)

Hibernate Language Binding Guide For The Connection Cloud Using Java Persistence API (JAP)

Table Of Contents Overview... 3 Intended Audience... 3 Prerequisites... 3 Term Definitions... 3 Introduction... 4 What s Required... 5 Language Binding... 5 Creating a Connection... 6 Building Entity Classes... 6 Executing Queries... 7 Error Handling... 8 Appendix... 9 B: Full Sample Code... 9 Page 2 of 11

Overview As the number of cloud applications increases, so does the amount of data stored in the cloud. More and more application developers are looking for ways to integrate the vast amounts of cloud data into their applications but, of course, this has been a challenge until now. The Connection Cloud is a platform that allows seamless integration of data from any data source by providing language bindings for application developers. Please note this document focuses on the use of Hibernate, an implementation of Java Persistence API (JAP), in conjunction with the Connection Cloud JDBC driver. Intended Audience This document is for Java developers who need to integrate cloud data, or data mash- ups into their applications. The Connection Cloud makes this possible without requiring custom query syntax, custom authentication code, or specialized drivers. This applies to cloud application developers and website designers using Java- enabled development environments in conjunction with Hibernate. Basic understanding of Hibernate and database query operations is required. You will need access to the items listed in the Prerequisites section before following the instructions in this document. Prerequisites Before attempting to use the Connection Cloud capabilities in an application, please be sure the following software and credentials are available: IDE/Compiler An Integrated Development Environment such as Eclipse or NetBeans to support Java development, or a simple command- line compiler. Connection Cloud Hibernate Resource Package Free WSQL dialect JAR as well as the JDBC driver for the Connection Cloud. You can download the Hibernate Package here: www.connectioncloud.com Java Runtime Environment The Connection Cloud JDBC driver requires any of the following at a minimum: Java 5 JRE, Java 6 JRE, JDK 1.5, or JDK 1.6. Connection Cloud Login Credentials The credentials to access your Connection Cloud account. Register for a free account at www.connectioncloud.com. Target Data Source Credentials The credentials to access the cloud data your application needs to integrate. For example, you may need your Salesforce.com username, password, and security token. Term Definitions This document uses the following terms: Cloud Data Source Data stored in a cloud application s underlying database such as Salesforce or Facebook data. Page 3 of 11

JDBC Java Database Connectivity is a Java- based data access technology that allows developers to query relational databases using the provided access methods. Please refer to the following URL for more information: http://en.wikipedia.org/wiki/jdbc Database Query An operation to manipulate data in a database management system. This may include fetching, updating, and/or deleting data. Query Language Syntax used to create database queries. Different databases and cloud applications may have vastly diverse query language syntax. SQL Structured Query Language is the most widely used query language to manipulate and fetch data in database management systems. Also referred to as ANSI SQL due to being a standard recognized by the American National Standards Institute. WSQL Web Services Query Language is the native query language of the Connection Cloud. It is a superset of ANSI SQL and includes the ability to call web service operations. For more information on syntax and features please visit the WSQL help page: https://connectioncloud.atlassian.net/wiki/display/wsql/home Introduction The complexity of data and data integration for application developers increases with the exponential growth of cloud applications. Each cloud data source can expose and require an authentication method, an API style such as SOAP or REST, a native query language with varying levels of functionality (SOQL, FQL, YQL, etc.), and may even release API updates with no backward compatibility. This has led to many silos of data since getting access to the underlying data varies from application to application. Furthermore, not having an ANSI SQL interface to these cloud databases increases the challenges involved with integrating multiple data sources into a single application. Most developers have had to first solve the data integration challenge before focusing on core application development tasks. This has stifled the rapid application development path most software professionals are accustomed to. The Connection Cloud hooks up any development language, application, or JDBC/ODBC compatible tool to cloud data sources just as easily as if the data were in a local, standard SQL database. In essence, the Connection Cloud allows programmatic access to any data source on the Web. Java developers looking to easily integrate cloud data into their applications using the Hibernate dialect implementation of Java Persistence API (JAP) should use this document. Page 4 of 11

What s Required To retrieve data via the Connection Cloud inside a Hibernate application you need a Connection Cloud account. Register for free at www.connectioncloud.com and use the username and password selected here when connecting to the Connection Cloud Web services. The Connection Cloud platform does not grant anonymous access. After you log into the Connection Cloud workbench, navigate to the Channels page and activate the desired cloud data sources. You can choose from sources like Salesforce.com, Facebook, or NetSuite. To set up credentials for each data source please refer to the Connection Cloud help pages/faq. Note: some cloud data sources require a certain subscription level to provide full API access. For instance, Salesforce.com only provides API access to the underlying data when subscribed to the Enterprise or Unlimited editions of the platform. Please be mindful of such restrictions when looking for access to cloud data. Language Binding To use the Connection Cloud inside your Hibernate application, include the following two libraries in your project: Connection Cloud JDBC Driver (CC_JDBC_x.jar, where x denotes the version number) WSQL Dialect Library (WSQLDialect.jar) You need to include these libraries in addition to the required libraries for Hibernate and Hibernate JPA. Please refer to the following link for information and help on creating Hibernate projects: http://docs.oracle.com/javaee/5/tutorial/doc/bnbpy.html Once you have included the required libraries, create a connection to the Connection Cloud per the instructions in the next section. You may then use standard Hibernate constructs such as Entity classes to define the tables the application needs access to. Please note, queries stored in the Connection Cloud Repository look like database tables to Hibernate. Page 5 of 11

Creating a Connection In order to execute queries through the Connection Cloud an application needs to first create a connection using Connection Cloud credentials. Most Connection Cloud account credentials will not include a tenant name ; therefore the only required credentials are the username and password. To configure the Hibernate connection to the Connection Cloud, configure the persistence.xml file by defining the following: Connection URL: jdbc:demandreports://workbench.demandreports.com Connection Username: Connection Cloud account username Connection Password: Connection Cloud account password Connection Driver: com.demandreports.jdbc.driver Connection Dialect: com.demandreports.hibernate.dialect.wsqldialect The following is a sample persistence.xml file: <?xml version="1.0" encoding="utf-8"?> <persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"> <persistence-unit name="hibernateexample" transaction-type="resource_local"> <provider>org.hibernate.ejb.hibernatepersistence</provider> <properties> <property name="hibernate.connection.username" value="myusername"/> <property name="hibernate.connection.password" value="mypassword"/> <property name="hibernate.connection.url" value="jdbc:demandreports://workbench.demandreports.com"/> <property name="hibernate.connection.driver_class" value="com.demandreports.jdbc.driver"/> <property name="hibernate.dialect" value="com.demandreports.hibernate.dialect.wsqldialect"/> </properties> </persistence-unit> </persistence> Building Entity Classes To execute queries on the Connection Cloud via Hibernate you need to create an Entity class per query or table. You may specify the name of the table as a reference to the stored query inside the Connection Cloud Repository using the following format: FolderName.QueryName Page 6 of 11

The following sample class describes a Customer Entity class that executes a query stored inside the Connection Cloud Repository as /MyQueries/CustomersQuery. @Entity @Table( name = "MyQueries.CustomersQuery" ) public class Customer { private Long id; private String emailaddress; private List<Order> orders; public Customer() { // Default constructor @Id @Column(name = "customerid") public Long getid() { return id; private void setid(long id) { this.id = id; ` @Column(name = "emailaddress") public String getemailaddress() { return emailaddress; public void setemailaddress(string emailaddress) { this.emailaddress = emailaddress; @OneToMany @JoinColumn(name="customerid", referencedcolumnname="customerid") public List<Order> getorders() { return orders; public void setorders(list<order> orders) { this.orders = orders; This class outlines the various columns the application will require from the Customers table. Executing Queries In order to execute queries use standard Hibernate method calls such as createentitymanagerfactory, gettransaction().begin(), and createquery. Page 7 of 11

The following code snippet demonstrates the necessary steps required in order to execute queries via the Connection Cloud. import java.util.list; import java.util.date; import javax.persistence.entitymanager; import javax.persistence.entitymanagerfactory; import javax.persistence.persistence; public class HibernateExample { /** * @param args the command line arguments */ public static void main(string[] args) { EntityManagerFactory entitymanagerfactory = Persistence.createEntityManagerFactory( "HibernateExample" ); EntityManager entitymanager = entitymanagerfactory.createentitymanager(); entitymanager.gettransaction().begin(); List<Customer> customers = entitymanager.createquery( "from Customer where locate(substring(trim(emailaddress), 1),'@XYZCompany.com')!= 0").getResultList(); System.out.println( "customer count: " + customers.size() ); for ( Customer customer : customers ) { System.out.println( "Customer (" + customer.getid() + ") : " + customer.getemailaddress() ); List<Order> orders = customer.getorders(); for ( Order order : orders ) { System.out.println( "Order (" + order.getid() + ") : " + order.getorderdate() ); entitymanager.gettransaction().commit(); entitymanager.close(); Error Handling You should always use appropriate Exception handling when calling the Connection Cloud via Hibernate. Implement all calls to the Connection Cloud within a try-catch block. Page 8 of 11

Appendix B: Full Sample Code CustomersEntity.java import java.util.date; import java.util.list; import javax.persistence.column; import javax.persistence.entity; import javax.persistence.id; import javax.persistence.joincolumn; import javax.persistence.onetomany; import javax.persistence.table; import javax.persistence.temporal; import javax.persistence.temporaltype; import org.hibernate.annotations.genericgenerator; @Entity @Table( name = "MyQueries.CustomersQuery" ) public class Customer { private Long id; private String emailaddress; private List<Order> orders; public Customer() { // Default constructor @Id @Column(name = "customerid") public Long getid() { return id; private void setid(long id) { this.id = id; @Column(name = "emailaddress") public String getemailaddress() { return emailaddress; public void setemailaddress(string emailaddress) { this.emailaddress = emailaddress; @OneToMany @JoinColumn(name="customerid", referencedcolumnname="customerid") public List<Order> getorders() { return orders; public void setorders(list<order> orders) { this.orders = orders; Page 9 of 11

OrdersEntity.java import java.util.date; import javax.persistence.column; import javax.persistence.entity; import javax.persistence.generatedvalue; import javax.persistence.id; import javax.persistence.joincolumn; import javax.persistence.manytoone; import javax.persistence.table; import javax.persistence.temporal; import javax.persistence.temporaltype; import org.hibernate.annotations.genericgenerator; @Entity @Table( name = "MyQueries.OrdersQuery" ) public class Order { private Long id; private Date orderdate; private Customer customer; public Order() { // this form used by Hibernate @Id @Column(name = "orderid") public Long getid() { return id; private void setid(long id) { this.id = id; @Temporal(TemporalType.TIMESTAMP) @Column(name = "orderdate") public Date getorderdate() { return orderdate; public void setorderdate(date orderdate) { this.orderdate = orderdate; Page 10 of 11

Main.java import java.util.list; import java.util.date; import javax.persistence.entitymanager; import javax.persistence.entitymanagerfactory; import javax.persistence.persistence; public class HibernateExample { /** * @param args the command line arguments */ public static void main(string[] args) { EntityManagerFactory entitymanagerfactory = Persistence.createEntityManagerFactory( "HibernateExample" ); EntityManager entitymanager = entitymanagerfactory.createentitymanager(); entitymanager.gettransaction().begin(); List<Customer> customers = entitymanager.createquery( "from Customer where locate(substring(trim(emailaddress), 1),'@XYZCompany.com')!= 0").getResultList(); System.out.println( "customer count: " + customers.size() ); for ( Customer customer : customers ) { System.out.println( "Customer (" + customer.getid() + ") : " + customer.getemailaddress() ); List<Order> orders = customer.getorders(); for ( Order order : orders ) { System.out.println( "Order (" + order.getid() + ") : " + order.getorderdate() ); entitymanager.gettransaction().commit(); entitymanager.close(); Page 11 of 11