Quick Start for sforce 3.0 and Eclipse

Adam Gross

salesforce.com

Sforce 3.0 and the new Enterprise Web services API represents a significant advancement in the state of the art of Web services generally, and the application development and integration capabilities of salesforce.com specifically.

Fortunately, open source development environments and tools, and specifically Eclipse and Apache Axis, are available that can quickly get you up to speed using the new Web services API, and demonstrating the power and simplicity of this new interface. This document, the first of two, will show you how to get your environment set up to start developing with sforce.

Note: You need to understand Java programming to use the new API with Eclipse. If you don’t know Java, this is a good time to learn; the better you understand sforce, the better equipped you’ll be to sell and close large deals quickly. There are many good resources online to get you started, including this one: http://java.sun.com/docs/books/tutorial/index.html.

Step 1: Understanding of the Parts

To set up your environment, you need the following:

• JDK (Java Development Kit) 1.4: The JDK includes the Java VM (Virtual Machine) that runs Java programs, the core class libraries (the sets of Java APIs that represent different functionality from using graphics to accessing the Internet) and Javac (a compiler for creating Java code.) Note you’ll need the JDK, not the JRE (Java Runtime) as the latter does not include the compiler.

• Eclipse 2.1: Eclipse is a popular and full featured IDE (Integrated Development Environment). In addition to being great, its free. (Eclipse is an open source project based on IBM’s VisualAge development tools.)

• Apache Axis: Axis an open source, free SOAP stack largely developed by IBM, and maintained by the Apache organization (the good folks who bring you most of the Web and app servers used in the world, as well.) A SOAP stack is analogous to a Web browser; it contains the libraries necessary to communicate with Web services, and convert the resulting XML into structures easily used within the language of your choice. Axis is the most popular and widely used SOAP stack for Java, and is used in many commercial products, including salesforce.com.

• WSDL2Java Eclipse Plug-in: This plug-in is used to convert the sforce-provided WSDL file into Java objects that you will write your programs against. (This step of converting WSDL into local proxy objects, is part of using Web services, regardless of language or platform.)

Step 2: Downloading and Installing the Bits

The first step is to download and install all the component parts necessary to use the sforce Web service. We’ll be setting up the environment at c:\sforce, so make sure you create that directory and have ~ 100 megs of free space.

1. Download and install the JDK: http://java.sun.com/j2se/1.4.2/download.html. Make sure you select just the JDK (the second option), not the JDK + NetBeans. Also be sure to download the JDK, not the JRE, as discussed above. Download and install as directed.

2. Download and install Eclipse: http://download2.eclipse.org/downloads/drops/R-2.1.2-200311030802/download.php?dropFile=eclipse-SDK-2.1.2-win32.zip. Download the zip file, and extract the contents into your c:\sforce directory.

3. Download and install Apache Axis: http://mirrors.xtria.com/apache/ws/axis/1_1/axis-1_1.zip. Download the zip file, and extract the contents into your c:\sforce directory.

4. Download and install the WSDL2Java Eclipse Plug-in: http:// http://prdownloads.sourceforge.net/sforce/com.myspotter.wsdl2java_1.2.0.zip?download . This one is a bit tricky, as you need to make sure the files (within the core com.myspotter.wsld2java directory) are installed into the plugins directory within your c:\sforce\eclipse path. Extracting the zip to c:\sforce should do that, but check the directories after your install to be sure, and move the com.myspotter.wsld2java folder to the c:\sforce\eclipse\plugins directory if necessary.

Step 3: Creating your first Eclipse project & running the sample

The last step is to create an configure an eclipse project to use in developing your sforce applications.

1. Start up Eclipse by double clicking the Eclipse icon in the c:\sforce\eclipse directory.
2. Select File | New | Project and complete the wizard to create an empty Java Project.
3. Right-click on the project in the Navigator window and select properties. In the Properties window, select Java Build Path, and then the Libraries Tab. Click “Add External JARs”, and in the dialog, navigate to and select all the contents of c:\sforce\axis\lib. As you might guess, this step adds Axis to your project.
4. Download the WSDL from your salesforce.com account (available via the Setup area.) If you don’t see the WSDL option under “sforce Application Server”, you don’t have the appropriate permissions.
5. Right click on the project, select “Import..” and then “File System..”; follow the steps to add the WSDL to your project.
6. Right click on the WSDL and select WSDL2Java | Generate...; and follow the steps to generate your Java objects.

From here, you can follow the steps in the “Getting Started” section of the sforce Web services API 2.5 Documentation (available as sforce.com) to copy and run the sample.

Step 4: Install Tomcat

In order to create Web applications using JSPs and servlets, you’ll need a Java application server. Tomcat (also from Apache), is the leading open source Java app server, and is remarkably full featured. (Note that it does not include EJB functionality, but it is highly unlikely that you’ll ever need that.)

To install Tomcat:

1. Download the zip file at http://apache.cs.utah.edu/jakarta/tomcat-5/v5.0.24/bin/jakarta-tomcat-5.0.24.zip , and extract the contents to c:\sforce
2. To start Tomcat, you’ll need to first set the JAVA_HOME environement variable to the location of your JDK install, which should be something like c:\j2sdk1.4.1_03, depending on where you install Java and what version you are using.
3. In the c:\tomcat\bin directory, run startup.bat to start Tomcat.

There is a great IDE plugin, called myeclipseIDE, for building JSPs and deploying to Tomcat (or any other app server); it provides full JSP editing capabilities, including code completion for your Java JSP includes. This plugin, however, is cheap ($25!), but not free – you can registered for and download a trial at http://myeclipseide.com/. Consult the documentation for setting up your JSP projects using this plugin.

Tip: A simple way to make sure your programs, including Tomcat and JSP applications, always have access to the Axis libraries is to copy them into your C:\j2sdk1.4.1_03\jre\lib\ext directory (the exact location depends on where you installed Java and what version you are using.) This should simplify most of your classpath issues, which are the most common problems in building Web applications with sforce.