• Page
|
• Edit

Force.com for Google App Engine for Java is a set of libraries that developers can use to connect the Force.com and Google clouds. These java libraries run on Google App Engine and expose the Force.com Web Services API. This page will describe how to get started developing with these libraries.

Downloading the Libraries

You can download the Force.com for Google App Engine libraries from the Code Share project. You will need wsc-[version].jar and optionally partner-library.jar. See below for a description of when you'll want partner-library.jar.

Description of the Libraries

There are two libraries you will need to get started developing with Force.com within Google App Engine. First is the Force.com Web Services Connector referred to as "WSC". This is a code-generation tool and runtime library for accessing Force.com web services (as even other web services). This tool can take a Force.com Web Services Description Language (WSDL) file and generate an optimzed java library that provides access to that web service. There are two types of WSDL available from Force.com: Enterprise WSDL and Partner WSDL. Read this section of the Force.com online docs to learn more about the differences between the two WSDLs. Because the Partner WSDL is the same for every customer, we've pre-generated that java library using WSC for you. It's called partner-library.jar and it's available from the Code Share project. If you want to use the Enterprise WSDL, you will need to generate your own java library with your organization's specific Enterprise WSDL. The following sections describe how to do this.

Generating an Enterprise WSDL Java Library

The first step is to obtain your organization's Enterprise WSDL which can be done by logging into salesforce.com and from the Setup screen clicking Develop, then API. On this page there will be a link to download your Enterprise WSDL. Note: this will be different for each organization.

To generate the java library for this WSDL file, you run the WSDL compiler (wsdlc) from WSC. The basic syntax for wsdlc is:

java -classpath wsc.jar;JAVA_HOME/lib/tools.jar com.sforce.ws.tools.wsdlc [WsdlFile] [output-jar-file]

This command will generate a set of folders and java source code files in a temporary directory, compile the source files and produce a jar file. This jar file can be included in your Java classpath for use in creating client applications. Note: Whether you use the Partner or Enterprise WSDL, you will need to include wsc.jar in your java build path because it is a runtime dependency of the generated library.

Developing with Eclipse: Create a Hello World App

• Install Eclipse and the Google Eclipse Plugin by following the instructions on Google's site
• Create a new Web Application Project and name it helloworld
• For Mac Users: If you don't already have the Java 1.6 virtual machine, install it via the Apple Developer Site. Then set your project to use the 1.6 JVM by right clicking on your project and selecting Properties, then select Java Build Path. From here click on Java System Library and click Edit and change it to JVM 1.6
• Add the Force.com Java libraries (wsc.jar + partner-library.jar or your-enterprise-library.jar) to the application's WEB-INF/lib folder
• Add the following example servlet class:

package com.force;
import java.io.IOException;
import java.io.PrintWriter;

import javax.servlet.http.*;
import java.util.logging.*;

import com.sforce.ws.*;
import com.sforce.soap.partner.*;
import com.sforce.soap.partner.sobject.SObject;


@SuppressWarnings("serial")
public class HelloWorldServlet extends HttpServlet {
 	private static final Logger log = Logger.getLogger(helloworldServlet.class.getName());

	private String username = "your username";
	private String password = "your password";
	private PartnerConnection connection;
	
	public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
		resp.setContentType("text/html");
		resp.getWriter().println("Hello, world. this is a test2");
		
		PrintWriter t = resp.getWriter();
		getConnection( t, req);
		if ( connection == null ) { return; }

		QueryResult result = null;
		
		try {
		
			result = connection.query(  "select id, name, phone from Account order by LastModifiedDate desc limit 10 ");
		
		} catch (ConnectionException e) {
			// TODO Auto-generated catch block
			e.printStackTrace();
		}
		for (SObject account : result.getRecords()) {
		     t.println("<li>"+ (String)account.getField("Name") + "</li>");
		}
	}
	
	void getConnection(PrintWriter out, HttpServletRequest req)  { 
		
		try { 
			// build up a ConnectorConfig from a sid
			String sessionid = req.getParameter("sid");
			String serverurl = req.getParameter("srv");
			
			if ( connection == null ) { 
				
			   out.println("<p>new connection needed</p>");
			   // login to the Force.com Platform
			   ConnectorConfig config = new ConnectorConfig();
			   if ( sessionid != null && serverurl != null) {
				   config.setServiceEndpoint(serverurl);
				   config.setSessionId(sessionid);
				   config.setManualLogin(false);
				   out.println("using session from query string");
			   }   else { 
				   config.setUsername(username);
				   config.setPassword(password);
			   }
			   connection = Connector.newConnection(config);
			   out.println( connection.getConfig().getSessionId() );
			   out.println( connection.getConfig().getServiceEndpoint() );
		   } else { 
			   out.println("<p> reuse existing connection"); 
			   out.println( connection.getConfig().getSessionId() );
		   }
		   log.warning("Connection SID " +connection.getConfig().getSessionId());

		} catch ( ConnectionException ce) {
			log.warning("ConnectionException " +ce.getMessage());
			
			out.println( ce.getMessage() + " s " + ce.getClass() );

		}
			
	}
}

• Modify your web.xml to setup a mapping for the HelloWorldServlet class
• Run the localserver and you when hitting the servlet you should see something like this:

Enterprise Library Sample Code

The following sample code shows how you can use the generated Enterprise library (.jar file) to login to Force.com and create a new Account record.

import com.sforce.ws.ConnectionException;
import com.sforce.soap.enterprise.sobject.Account;
import com.sforce.soap.enterprise.sobject.SObject;
import com.sforce.soap.enterprise.EnterpriseConnection;
import com.sforce.soap.enterprise.Connector;

public class EnterpriseClient {
    private String username = //your user name
    private String password = //your password
    private EnterpriseConnection connection;

    public EnterpriseClient() throws ConnectionException {
        connection = Connector.newConnection(username, password);
        createAccount();
    }

    private void createAccount() throws ConnectionException {
        Account account = new Account();
        account.setName("My Account");
        account.setPhone("123 244 3455");
        connection.create(new SObject[]{account});
    }

    public static void main(String[] args) throws ConnectionException {
        new EnterpriseClient();
    }
}

Partner Library Sample Code

The following sample code shows how you can use the supplied Partner library (partner-library.jar file) to login to Force.com and create a new Account record.

import com.sforce.ws.*;
import com.sforce.soap.partner.*;
import com.sforce.soap.partner.sobject.*;

public class PartnerClient {

    private String username = //your user name
    private String password = //your password
    private PartnerConnection connection;

    public PartnerClient() throws ConnectionException {
        ConnectorConfig config = new ConnectorConfig();
        config.setUsername(username);
        config.setPassword(password);
        connection = Connector.newConnection(config);
        createAccount();
    }

    private void createAccount() throws ConnectionException {
        SObject account = new SObject();
        account.setType("Account");
        account.setField("Name", "My Account");
        account.setField("Phone", "123 244 3455");
        connection.create(new SObject[]{account});
    }

    public static void main(String[] args) throws ConnectionException {
        new PartnerClient();
    }
}

WSC Configuration

You can set configuration using ConnectorConfig as shown below:

       Connector connector = Connector.newConnector();
       ConnectionConfig config = new ConnectionConfig();
       config.setTraceMessage(true);
       ...
       connector.setConfiguration(config);

The following configuration options are supported by WSC.

API Documentation

• Javadocs for WSC
• Javadocs for Partner Library

Obtaining a Force.com Developer Edition Account

If you are not already a member of the Force.com developer community, you should sign up for a free Developer Edition account. Even if you already have an Enterprise Edition or Unlimited Edition account, it is strongly recommended that you use Developer Edition for developing, staging, and testing your solutions against sample data to avoid impacting your organization's live data. This is especially true for applications that will be inserting, updating, or deleting data (as opposed to simply reading data).