Enterprise Java

How to use Salesforce REST API with your JavaServer Pages

Photo of Seetha Annamraju Seetha AnnamrajuJune 30th, 2014Last Updated: July 7th, 2014
0 251 9 minutes read

Abstract: This tutorial gives an example of a JSP and how to integrate it with the Salesforce REST API. We will walk through the step­by­step process of creating an external client to manage your data with Force.com,while using HTTP(S) and JSON.

In this example, I am using Mac OS X 10.9.2 with Apache Tomcat 7 server and Java 1.7. Eclipse Java EE edition is the IDE used for development and testing. The instructions given in this tutorial should work with minor modifications for other platforms as well.

If you want to access the entire sample code from this tutorial, you can access it here: github.com/seethaa/force_rest_example

All code is updated to work with the httpclient 4.3 libraries.

What Is REST?

REST stands for Representational State Transfer, and is a stateless client­server communications protocol over HTTP.

Why and When To Use A REST API in Java for Your JSP

A REST API is well suited for browser applications which require a lot of interaction, and uses synchronous communication to transfer data. The Salesforce REST API provides a programming interface for simple web services to interact with Force.com, and supports both XML and JSON formats. The Salesforce REST API works well for mobile applications or dynamic websites to retrieve or update records quickly on your web server. While bulk record retrieval should be reserved for the BulkAPI, this lightweight REST API can be used for common server pages which involve quick updates and frequent user interactions, for example updating a single user record.

Setting Up Your Development Account and Prerequisites

You will need the following:

  1. Go to https://developer.salesforce.com/signup and register for your Free DE account. For the purposes of this example, I recommend sign up for a Developer Edition even if you already have an account. This ensures you get a clean environment with the latest features enabled.
  2. Java application Server. I created mine using Apache Tomcat 7 on Mac OS X and Eclipse as the IDE. There is also a free Eclipse plugin at http://developer.salesforce.com/page/Force.com_IDE but the original Eclipse setup was used in this tutorial.
  3. Configure SSL on your Tomcat server using http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html. If you are developing in Eclipse, make sure to add the Connector piece in server.xml file in your Eclipse environment, e.g.:
    <Connector SSLEnabled="true" clientAuth="false" keystoreFile="/Users/seetha/.keystore" keystorePass="password" maxThreads="200" port="8443" protocol="HTTP/1.1" scheme="https" secure="true" sslProtocol="TLS"/>
  4. Add the required jar files to WebContent/WEB­INF/lib. You will need commons-­codec-­1.6.jar, httpclient­4.3.3.jar, httpcore-­4.3.2.jar, commons-­logging­-1.1.3.jar, and java-­json.jar. For Eclipse, I also had to make sure that all jars were added to the build path (Right click Project → Build Path → Configure build path →  Select Libraries tab → Click Add Jars → Select the Jar files from the WEB­INF/lib folder.

Create a Connected App

  1. Back in your Force.com DE, create a new Connected App through the console. Click on Setup → Build → Create → Apps. Scroll down to the Connected Apps section and click on the New button.
    • Ensure that the callback URL is http://localhost:8080/<your_app_context_path>/oauth/_callback

      (You can find the app context path by going back to Eclipse: Right clicking on Project → Properties → Web Project Settings → Context root)

    • Check “Enable OAuth Settings” checkbox
    • The required OAuth scopes for this tutorial (see Figure 1) are “Access and manage your data (api)” and “Provide access to your data via the Web (web)”, but these scopes should be changed as per your requirement.
    • Save

      Figure 1: Creating new Connected App
      Figure 1: Creating new Connected App
  2. Copy the ClientID and Client Secret (see Figure 2), because both of these will be used in the next step.
     
    Figure 2: Connected App Example with Consumer Key and Secret
    Figure 2: Connected App Example with Consumer Key and Secret

    Authentication

    There are three files that need to be imported into your JSP project, given below:

    index.html

    <!DOCTYPE html PUBLIC "­//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http­equiv="Content­Type" content="text/html; charset=UTF­8">
<title>REST/OAuth Example</title>
</head>
<body>
	<script type="text/javascript"  language="javascript">
	if (location.protocol != "https:") {
		document.write("OAuth  will not work correctly from plain http. "+ "Please use an https URL.");
	} else {
		document.write("<a href=\"oauth\">Run Connected App demo via REST/OAuth.</a>");
	}
	</script>
</body>
</html>

    OAuthConnectedApp.java

    import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.ArrayList;
import java.util.List;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebInitParam;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.http.Consts; 
import org.apache.http.HttpEntity;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.message.BasicNameValuePair;

import org.json.JSONException;
import org.json.JSONObject;
import org.json.JSONTokener;

@WebServlet(name  = "oauth", urlPatterns = { "/oauth/*", "/oauth" }, initParams = {
// clientId is 'Consumer Key' in the Remote Access UI
//**Update with your own Client ID
@WebInitParam(name  = "clientId", value = "3MVG9JZ_r.QzrS7jzujCYrebr8kajDEcjXQLXnV9nGU6PaxOjuOi_n8EcUf0Ix9qqk1lYCa4_Jaq7mpqxi2YT"),
// clientSecret is 'Consumer Secret' in the Remote Access UI
//**Update with your own Client Secret
@WebInitParam(name  = "clientSecret", value = "2307033558641049067"),
// This must be identical to 'Callback URL' in the Remote Access UI
//**Update with your own URI
@WebInitParam(name  = "redirectUri", value = "http://localhost:8080/force_rest_example/oauth/_callback"),
@WebInitParam(name  = "environment", value = "https://login.salesforce.com"), })

/**
* Servlet parameters
* @author  seetha
*
*/
public class OAuthConnectedApp  extends HttpServlet {

	private static final long serialVersionUID = 1L;

	private static final String ACCESS_TOKEN = "ACCESS_TOKEN";
	private static final String INSTANCE_URL = "INSTANCE_URL";

	private String clientId = null;
	private String clientSecret = null;
	private String redirectUri = null;
	private String environment = null;
	private String authUrl = null;
	private String tokenUrl = null;
	
	public void init() throws ServletException {
		
		clientId = this.getInitParameter("clientId");
		clientSecret = this.getInitParameter("clientSecret");
		redirectUri = this.getInitParameter("redirectUri");
		environment = this.getInitParameter("environment");

		try {

			authUrl = environment
			+ "/services/oauth2/authorize?response_type=code&client_id="
			+ clientId + "&redirect_uri="
			+ URLEncoder.encode(redirectUri, "UTF­8");
		}
		catch (UnsupportedEncodingException e) {
			throw new ServletException(e);
		}

		tokenUrl = environment + "/services/oauth2/token";
	}

	protected void doGet(HttpServletRequest request, HttpServletResponse  response) throws ServletException, IOException {
	
		String accessToken = (String) request.getSession().getAttribute(ACCESS_TOKEN);

		//System.out.println("calling doget");
		if (accessToken == null) {
			String instanceUrl = null;

			if (request.getRequestURI().endsWith("oauth")) {
				// we need to send the user to authorize
				response.sendRedirect(authUrl);
				return;
			}
			else {
				System.out.println("Auth successful ­ got callback");
				String code = request.getParameter("code");

				// Create an instance of HttpClient.
				CloseableHttpClient  httpclient = HttpClients.createDefault();

				try{
					// Create an instance of HttpPost.
					HttpPost httpost = new HttpPost(tokenUrl);

					// Adding all form parameters in a List of type NameValuePair
					List<NameValuePair>  nvps = new ArrayList<NameValuePair>();
					nvps.add(new BasicNameValuePair("code", code));
					nvps.add(new BasicNameValuePair("grant_type","authorization_code"));
					nvps.add(new BasicNameValuePair("client_id", clientId));
					nvps.add(new BasicNameValuePair("client_secret", clientSecret));
					nvps.add(new BasicNameValuePair("redirect_uri", redirectUri));

					httpost.setEntity(new  UrlEncodedFormEntity(nvps, Consts.UTF_8));
					
					// Execute the request.
					CloseableHttpResponse closeableresponse=httpclient.execute(httpost);
					System.out.println("Response Statusline:"+closeableresponse.getStatusLine());

					try {
						// Do the needful with entity.
						HttpEntity entity = closeableresponse.getEntity();
						InputStream rstream = entity.getContent();
						JSONObject authResponse = new JSONObject(new JSONTokener(rstream));

						accessToken = authResponse.getString("access_token");
						instanceUrl = authResponse.getString("instance_url");

					} catch (JSONException e) {
						// TODO Auto­generated catch block e.printStackTrace();
						e.printStackTrace();
					} finally {
						// Closing the response
						closeableresponse.close();
					}
				} finally {
					httpclient.close();
				}

			}

			// Set a session attribute so that other servlets can get the access token
			request.getSession().setAttribute(ACCESS_TOKEN, accessToken);

			// We also get the instance URL from the OAuth response, so set it in the session too
			request.getSession().setAttribute(INSTANCE_URL, instanceUrl);
		}

		response.sendRedirect(request.getContextPath() + "/ConnectedAppREST");
	}
	
}

    ConnectedAppREST.java

    import java.io.IOException;
import java.io.InputStream;
import java.io.PrintWriter;
import java.net.URISyntaxException;
import java.util.Iterator;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.http.HttpEntity;
import org.apache.http.HttpStatus;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpDelete;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
import org.json.JSONTokener;

@WebServlet(urlPatterns = { "/ConnectedAppREST"  })
/**
* Demo for Connect App/REST API
* @author  seetha
*
*/
public class ConnectedAppREST  extends HttpServlet {

	private static final long serialVersionUID = 1L;
	private static final String ACCESS_TOKEN = "ACCESS_TOKEN";
	private static final String INSTANCE_URL = "INSTANCE_URL";
	
	private void showAccounts(String  instanceUrl, String accessToken,
		PrintWriter writer) throws ServletException, IOException {
		
		CloseableHttpClient  httpclient = HttpClients.createDefault();

		HttpGet httpGet = new HttpGet();

		//add key and value
		httpGet.addHeader("Authorization", "OAuth " + accessToken);

		try {
		
			URIBuilder builder = new URIBuilder(instanceUrl+ "/services/data/v30.0/query");
			builder.setParameter("q", "SELECT Name, Id from Account LIMIT 100");

			httpGet.setURI(builder.build());

			CloseableHttpResponse  closeableresponse = httpclient.execute(httpGet);
			System.out.println("Response Status line :" + closeableresponse.getStatusLine());
			
			if (closeableresponse.getStatusLine().getStatusCode() == HttpStatus.SC_OK) {
				// Now lets use the standard java json classes to work with the results
				try {
					// Do the needful with entity.
					HttpEntity entity = closeableresponse.getEntity();
					InputStream rstream = entity.getContent();
					JSONObject authResponse = new JSONObject(new JSONTokener(rstream));

					System.out.println("Query response: " + authResponse.toString(2));

					writer.write(authResponse.getInt("totalSize") + " record(s) returned\n\n");

					JSONArray results = authResponse.getJSONArray("records");
					
					for (int i = 0; i < results.length(); i++) {
					writer.write(results.getJSONObject(i).getString("Id")
						+ ", "
						+ results.getJSONObject(i).getString("Name")
						+ "\n");
					}
					
					writer.write("\n");
				}
				catch (JSONException e) {
					e.printStackTrace();
					throw new ServletException(e);
				}
			}
			
		} catch (URISyntaxException  e1) {
			// TODO Auto­generated catch block
			e1.printStackTrace();
		} finally {
			httpclient.close();
		}
	}
	
	private String createAccount(String  name, String instanceUrl,
		String accessToken, PrintWriter writer) throws ServletException, IOException {
		
		String accountId = null;
		CloseableHttpClient  httpclient = HttpClients.createDefault();
		JSONObject account = new JSONObject();
		
		try {
			account.put("Name",  name);
		}
		catch (JSONException e) {
			e.printStackTrace();
			throw new ServletException(e);
		}
		
		HttpPost httpost = new HttpPost(instanceUrl+  "/services/data/v30.0/sobjects/Account/");

		httpost.addHeader("Authorization", "OAuth " + accessToken);

		StringEntity messageEntity = new StringEntity( account.toString(), ContentType.create("application/json"));

		httpost.setEntity(messageEntity);

		// Execute the request.
		CloseableHttpResponse  closeableresponse = httpclient.execute(httpost);
		System.out.println("Response Status line :" + closeableresponse.getStatusLine());
		
		try {
		
			writer.write("HTTP status " + closeableresponse.getStatusLine().getStatusCode() + " creating account\n\n");

			if (closeableresponse.getStatusLine().getStatusCode()  == HttpStatus.SC_CREATED) {
			
				try {
				
					// Do the needful with entity.
					HttpEntity entity = closeableresponse.getEntity();
					InputStream rstream = entity.getContent();
					JSONObject authResponse = new JSONObject(new JSONTokener(rstream));
					
					System.out.println("Create response: " + authResponse.toString(2));

					if (authResponse.getBoolean("success")) {
						accountId = authResponse.getString("id");
						writer.write("New record id " + accountId + "\n\n");
					}
					
				} catch (JSONException e) {
					e.printStackTrace();
					// throw new ServletException(e);
				}
			}
		}
		finally {
			httpclient.close();
		}

		return accountId;
	}
	
	private void showAccount(String  accountId, String instanceUrl,
		String accessToken, PrintWriter writer) throws ServletException, IOException {

		CloseableHttpClient  httpclient = HttpClients.createDefault();
		HttpGet httpGet = new HttpGet();
	
		//add key and value
		httpGet.addHeader("Authorization", "OAuth " + accessToken);
		
		try {
		
			URIBuilder builder = new URIBuilder(instanceUrl + "/services/data/v30.0/sobjects/Account/" + accountId);

			httpGet.setURI(builder.build());

			//httpclient.execute(httpGet);

			CloseableHttpResponse  closeableresponse = httpclient.execute(httpGet);
			System.out.println("Response Status line :" + closeableresponse.getStatusLine());
			
			if (closeableresponse.getStatusLine().getStatusCode()  == HttpStatus.SC_OK) {

				try {
				
					// Do the needful with entity.
					HttpEntity entity = closeableresponse.getEntity();
					InputStream rstream = entity.getContent();
					JSONObject authResponse = new JSONObject(new JSONTokener(rstream));
					
					System.out.println("Query response: " + authResponse.toString(2));
					writer.write("Account  content\n\n");
					
					Iterator iterator = authResponse.keys();

					while (iterator.hasNext()) {
						String key = (String) iterator.next();

						Object obj = authResponse.get(key);
						String value = null;
				
						if (obj instanceof String) {
							value = (String) obj;
						}

						writer.write(key + ":" + (value != null ? value : "") + "\n");
					}

					writer.write("\n");
					
				} catch (JSONException e) {
					e.printStackTrace();
					throw new ServletException(e);
				}
			}
			
		}
		catch (URISyntaxException  e1) {
			// TODO Auto­generated catch block
			e1.printStackTrace();
		} finally {
			httpclient.close();
		}
	}
	
	private void updateAccount(String  accountId, String newName, String city, String instanceUrl, String accessToken, PrintWriter writer) throws ServletException, IOException {
		
		CloseableHttpClient  httpclient = HttpClients.createDefault();

		JSONObject update = new JSONObject();
		
		try {
			update.put("Name", newName);
			update.put("BillingCity", city);
		}
		catch (JSONException e) {
			e.printStackTrace();
			throw new ServletException(e);
		}
		
		HttpPost httpost = new HttpPost(instanceUrl + "/services/data/v30.0/sobjects/Account/" +accountId+"?_HttpMethod=PATCH");
		httpost.addHeader("Authorization", "OAuth " + accessToken);
		StringEntity messageEntity = new StringEntity( update.toString(), ContentType.create("application/json"));

		httpost.setEntity(messageEntity);
		
		// Execute the request.
		CloseableHttpResponse  closeableresponse = httpclient.execute(httpost); System.out.println("Response Status line :" + closeableresponse.getStatusLine());
		
		try {
			writer.write("HTTP status " + closeableresponse.getStatusLine().getStatusCode() + " updating account " + accountId + "\n\n");
		} finally {
			httpclient.close();
		}
	}
	
	private void deleteAccount(String  accountId, String instanceUrl, String accessToken, PrintWriter writer) throws IOException {

		CloseableHttpClient  httpclient = HttpClients.createDefault();

		HttpDelete delete = new HttpDelete(instanceUrl + "/services/data/v30.0/sobjects/Account/" + accountId);

		delete.setHeader("Authorization", "OAuth " + accessToken);

		// Execute the request.
		CloseableHttpResponse  closeableresponse = httpclient.execute(delete);
		System.out.println("Response Status line :" + closeableresponse.getStatusLine());
		
		try {
			writer.write("HTTP status " + closeableresponse.getStatusLine().getStatusCode() + " deleting account " + accountId + "\n\n");
		} finally {
			delete.releaseConnection();
		}
	}
	
	/**
	* @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse
	*      response)
	*/
	@Override
	protected void doGet(HttpServletRequest request, HttpServletResponse  response) throws ServletException, IOException {
	
		PrintWriter writer = response.getWriter();

		String accessToken = (String) request.getSession().getAttribute( ACCESS_TOKEN);

		String instanceUrl = (String) request.getSession().getAttribute( INSTANCE_URL);

		if (accessToken == null) {
			writer.write("Error ­ no access token");
			return;
		}
		
		writer.write("We have an access token: " + accessToken + "\n" + "Using instance " + instanceUrl + "\n\n");

		showAccounts(instanceUrl, accessToken, writer);

		String accountId = createAccount("My New Org", instanceUrl, accessToken, writer);

		if (accountId == null) {
			System.out.println("Account ID null");
		}

		showAccount(accountId,  instanceUrl, accessToken, writer);
		showAccounts(instanceUrl, accessToken, writer);
		
		updateAccount(accountId, "My New Org, Inc", "San Francisco", instanceUrl, accessToken, writer);

		showAccount(accountId,  instanceUrl, accessToken, writer);

		deleteAccount(accountId, instanceUrl, accessToken, writer);

		showAccounts(instanceUrl, accessToken, writer);
		
	}
	
}
  3. Change OAuthConnectedApp.java to replace Client ID, Client Secret, and Callback URI fields based on the Connected App configuration.
  4. Start Tomcat server in Eclipse (see Figure 3) or externally, and navigate to https://localhost:8443/<your_app_context_path>/

    Figure 3: Running Tomcat Server in Eclipse
    Figure 3: Running Tomcat Server in Eclipse

     
    Figure 4: Retrieve Objects Screen
    Figure 4: Retrieve Objects Screen
  5. Clicking on the link above (see Figure 4) will not work unless it is through HTTPS, and SSL must be configured as endpoint for Tomcat.

    If all configurations were done properly, you should see a salesforce.com login screen (see Figure 5). Go ahead and login with your salesforce.com credentials to authorize your web application to access resources.

    Figure 5: Salesforce.com Login Screen for OAuth
    Figure 5: Salesforce.com Login Screen for OAuth
  6. Logging in will allow the ConnectedAppREST demo to execute methods to create, show, update, and delete records (see Figure 6).

    Figure 6: Output from Connected App REST Demo
    Figure 6: Output from Connected App REST Demo

*Tips & Warnings

  1. Make sure you have a Developer Edition (DE) account, because there are slight differences between Professional, Enterprise, Developer, etc. The Developer edition is free and does not expire (unless unused after a year).
  2. The callback URL in the OAuthConnectedApp.java must be same as the URL added to the connected app.
  3. If you get HTTP 403 error, it means the resource you are requesting is “Forbidden” from being accessed. Check that the username/account you are accessing with has the appropriate permissions.
  4. Make sure index.html is directly under the WebContent directory.

Resources

For a comprehensive set or resources, check out: http://developer.salesforce.com/en/mobile/resources

References

  1. Force.com REST API Developer’s Guide (PDF)
  2. Using the Force.com REST API
Tags
Photo of Seetha Annamraju Seetha AnnamrajuJune 30th, 2014Last Updated: July 7th, 2014
0 251 9 minutes read
Photo of Seetha Annamraju

Seetha Annamraju

Seetha Annamraju is a mobile engineer working at Amazon Lab126. She holds a master's degree in Information Technology - Mobility from Carnegie Mellon University. Her interests include developing software for mobile and wearable technologies with a focus on usability.
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Back to top button