Quick Start

This section walks through a sample Java client application that uses the Apache Axis SOAP client. The purpose of this sample application is to show the required steps for logging into the login server and to demonstrate the invocation and subsequent handling of several API calls. This sample application performs the following main tasks:

Note the error handling code that follows each API call.

//The sample client application begins by importing the necessary packages and objects.
package com.doc.samples;

import java.io.*;
import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;

import com.sforce.soap.enterprise.*;
import com.sforce.soap.enterprise.fault.ExceptionCode;
import com.sforce.soap.enterprise.fault.LoginFault;
import com.sforce.soap.enterprise.sobject.Contact;

/**
 * Title: Login Sample
 * 
 * Description: Console application illustrating login, session management,
 * and server redirection.
 * 
 * Copyright: Copyright (c) 2005- 2008
 * Company: salesforce.com
 *
 * @version 14.0
 */
public class Samples {
    private SoapBindingStub binding;
    static BufferedReader rdr = new BufferedReader(new InputStreamReader(System.in));

    public Samples() {
    }

    public static void main(String[] args) throws ServiceException {
        Samples samples1 = new Samples();
        samples1.run();
    }

    //The sample client application retrieves the user's login credentials.
    // Helper function for retrieving user input from the console
    String getUserInput(String prompt) {
        System.out.print(prompt);
        try {
            return rdr.readLine();
        }
        catch (IOException ex) {
            return null;
        }
    }

    /**
     * The login call is used to obtain a token from Salesforce.
     * This token must be passed to all other calls to provide
     * authentication.
     */
    private boolean login() throws ServiceException {
        String userName = getUserInput("Enter username: ");
        String password = getUserInput("Enter password: ");
        /** Next, the sample client application initializes the binding stub.
         * This is our main interface to the API through which all 
         * calls are made. The getSoap method takes an optional parameter,
         * (a java.net.URL) which is the endpoint.
         * For the login call, the parameter always starts with 
         * http(s)://www.salesforce.com. After logging in, the sample 
         * client application changes the endpoint to the one specified 
         * in the returned loginResult object.
         */
        binding = (SoapBindingStub) new SforceServiceLocator().getSoap();
        
        // Time out after a minute
        binding.setTimeout(60000);
        // Test operation
        LoginResult loginResult;
        try {
            System.out.println("LOGGING IN NOW....");
            loginResult = binding.login(userName, password);
        }
        catch (LoginFault ex) {
            // The LoginFault derives from AxisFault
            ExceptionCode exCode = ex.getExceptionCode();
            if (exCode == ExceptionCode.FUNCTIONALITY_NOT_ENABLED ||
                exCode == ExceptionCode.INVALID_CLIENT ||
                exCode == ExceptionCode.INVALID_LOGIN ||
                exCode == ExceptionCode.LOGIN_DURING_RESTRICTED_DOMAIN ||
                exCode == ExceptionCode.LOGIN_DURING_RESTRICTED_TIME ||
                exCode == ExceptionCode.ORG_LOCKED ||
                exCode == ExceptionCode.PASSWORD_LOCKOUT ||
                exCode == ExceptionCode.SERVER_UNAVAILABLE ||
                exCode == ExceptionCode.TRIAL_EXPIRED ||
                exCode == ExceptionCode.UNSUPPORTED_CLIENT) {
                System.out.println("Please be sure that you have a valid username
                     and password.");
            } else {
                // Write the fault code to the console
                System.out.println(ex.getExceptionCode());
                // Write the fault message to the console
                System.out.println("An unexpected error has occurred." + ex.getMessage());
            }
            return false;
        } catch (Exception ex) {
            System.out.println("An unexpected error has occurred: " + ex.getMessage());
            ex.printStackTrace();
            return false;
        }
        // Check if the password has expired
        if (loginResult.isPasswordExpired()) {
            System.out.println("An error has occurred. Your password has expired.");
            return false;
        }
        /** Once the client application has logged in successfully, it will use 
         *  the results of the login call to reset the endpoint of the service  
         *  to the virtual server instance that is servicing your organization.  
         *  To do this, the client application sets the ENDPOINT_ADDRESS_PROPERTY 
         *  of the binding object using the URL returned from the LoginResult.
         */
        binding._setProperty(SoapBindingStub.ENDPOINT_ADDRESS_PROPERTY, 
            loginResult.getServerUrl());
        /** The sample client application now has an instance of the SoapBindingStub 
         *  that is pointing to the correct endpoint. Next, the sample client application 
         *  sets a persistent SOAP header (to be included on all subsequent calls that 
         *  are made with the SoapBindingStub) that contains the valid sessionId
         *  for our login credentials. To do this, the sample client application 
         *  creates a new SessionHeader object and set its sessionId property to the 
         *  sessionId property from the LoginResult object.
         */
        // Create a new session header object and add the session id
        // from the login return object
        SessionHeader sh = new SessionHeader();
        sh.setSessionId(loginResult.getSessionId());
        /** Next, the sample client application calls the setHeader method of the 
         *  SoapBindingStub to add the header to all subsequent method calls. This  
         *  header will persist until the SoapBindingStub is destroyed until the header 
         *  is explicitly removed. The "SessionHeader" parameter is the name of the 
         *  header to be added.
         */
        // set the session header for subsequent call authentication
        binding.setHeader(new SforceServiceLocator().getServiceName().getNamespaceURI(),
                          "SessionHeader", sh);
        // return true to indicate that we are logged in, pointed
        // at the right url and have our security token in place.
        return true;
    }

    /**
     * To determine the objects that are available to the logged-in user, the sample 
     * client application executes a describeGlobal call, which returns all of the 
     * objects that are visible to the logged-in user. This call should not be made  
     * more than once per session, as the data returned from the call likely does not  
     * change frequently. The DescribeGlobalResult is simply echoed to the console.
     */
    private void describeGlobalSample() {
        try {
            DescribeGlobalResult describeGlobalResult;
            describeGlobalResult = binding.describeGlobal();
            String[] types = describeGlobalResult.getTypes();
            for (String type : types) System.out.println(type);
            getUserInput("\nDescribe global was successful.\n\nHit the enter key 
                 to continue....");
        }
        catch (Exception ex) {
            System.out.println("\nFailed to return types, error message was: \n" 
                 + ex.getMessage());
            getUserInput("\nHit return to continue...");
        }
    }

    /**
     * The following code segment illustrates the type of metadata information that 
     * can be obtained for each object available to the user. The sample client 
     * application executes a describeSObject call on a given object and then echoes  
     * the returned metadata information to the console. Object metadata information
     * includes permissions, field types and length and available values for picklist 
     * fields and types for referenceTo fields.
     */
    private void describeSample() {
        String objectToDescribe = getUserInput("\nType the name of the object to 
             describe (try Account): ");
        try {
            DescribeSObjectResult descSObjectRslt;
            descSObjectRslt = binding.describeSObject(objectToDescribe);
            if (descSObjectRslt != null) {
                // Report object level information
                Field[] fields = descSObjectRslt.getFields();
                String objectName = descSObjectRslt.getName();
                System.out.println("Metadata for " + objectToDescribe + " object:\n");
                System.out.println("Object name = " + objectName);
                System.out.println("Number of fields = " + fields.length);
                System.out.println("Object can be activated = " + 
                     descSObjectRslt.isActivateable());
                System.out.println("Can create rows of data = " + 
                     descSObjectRslt.isCreateable());
                System.out.println("Object is custom object = " + 
                     descSObjectRslt.isCustom());
                System.out.println("Can delete rows of data = " + 
                     descSObjectRslt.isDeletable());
                System.out.println("Can query for rows of data = " + 
                     descSObjectRslt.isQueryable());
                System.out.println("Object used in replication = " + 
                     descSObjectRslt.isReplicateable());
                System.out.println("Can retrieve object = " + 
                     descSObjectRslt.isRetrieveable());
                System.out.println("Can search object = " + 
                     descSObjectRslt.isSearchable());
                System.out.println("Can un-delete = " + 
                     descSObjectRslt.isUndeletable());
                System.out.println("Can update = " + 
                     descSObjectRslt.isUpdateable());
                System.out.println("\nField metadata for " + objectToDescribe + 
                     " object:\n");
                // Report information about each field
                if (fields != null) {
                    for (Field field : fields) {
                        PicklistEntry[] picklistValues = field.getPicklistValues();
                        String[] referenceTos = field.getReferenceTo();
                        System.out.println("************* New Field ***************");
                        System.out.println("Name = " + field.getName());
                        System.out.println("Label = " + field.getLabel());
                        System.out.println("Length = " + field.getLength());
                        System.out.println("Bytelength = " + field.getByteLength());
                        System.out.println("Digits = " + field.getDigits());
                        System.out.println("Precision = " + field.getPrecision());
                        System.out.println("Scale = " + field.getScale());
                        System.out.println("Field type = " + field.getType());
                        // field properties
                        System.out.println("Custom field = " + field.isCustom());
                        System.out.println("Name field = " + field.isNameField());
                        System.out.println("Can set field value on Create = " + 
                             field.isCreateable());
                        System.out.println("Can set field value on Update = " + 
                             field.isUpdateable());
                        System.out.println("Can be used to filter results = " + 
                             field.isFilterable());
                        System.out.println("Field value can be empty = " + 
                             field.isNillable());
                        System.out.println("Field value is defaulted on Create = " + 
                             field.isDefaultedOnCreate());
                        System.out.println("Field value is calculated = " + 
                             field.isCalculated());
                        System.out.println("Field value is a restricted picklist = " + 
                             field.isRestrictedPicklist());
                        if (picklistValues != null) {
                            System.out.println("Picklist values = ");
                            for (PicklistEntry picklistValue : picklistValues) {
                                if (picklistValue.getLabel() != null)
                                    System.out.print(" item: " + picklistValue.getLabel());
                                else
                                    System.out.print(" item: " + picklistValue.getValue());
                                System.out.print(", value = " + picklistValue.getValue());
                                System.out.println(", is default = " + 
                                     picklistValue.isDefaultValue());
                            }
                        }
                        if (referenceTos != null) {
                            System.out.println("Field references the following objects:");
                            for (String referenceTo : referenceTos) System.out.println(" " 
                                + referenceTo);
                        }
                        System.out.println("");
                    }
                    getUserInput("\nDescribe " + objectToDescribe +
                         " was successful.\n\nHit the enter key to continue....");
                }
            }
        } catch (Exception ex) {
            System.out.println("\nFailed to get " + objectToDescribe +
                 " description, error message was: \n " + ex.getMessage());
            getUserInput("\nHit return to continue...");
        }
    }

    /**
     * The sample client application executes a query by invoking the query call, 
     * passing a simple query string ("select FirstName, LastName from Contact") 
     * and iterating through the returned QueryResult.
     */
    private void querySample() {
        QueryOptions qo = new QueryOptions();
        qo.setBatchSize(200);
        binding.setHeader(new SforceServiceLocator().getServiceName().getNamespaceURI(), 
             "QueryOptions", qo);
        try {
            QueryResult qr = binding.query("select FirstName, LastName from Contact");
            
            if (qr.getSize() > 0) {
                      System.out.println("Logged in user can see "
                          + qr.getRecords().length + " contact records. ");
                      do {
                          // output contact records
                          for (int i = 0; i < qr.getRecords().length; i++) {
                              Contact con = (Contact) qr.getRecords(i);
                              String fName = con.getFirstName();
                              String lName = con.getLastName();
                              if (fName == null) {
                                  System.out.println("Contact " + (i + 1) + ": "
                                   + lName);
                              } else {
                                      System.out.println("Contact " + (i + 1) + ": "
                                       + fName + " " + lName);
                              }
                          }

                       if (!qr.isDone()) {
                               qr = binding.queryMore(qr.getQueryLocator());
                       } else {
                               break;
                       }
                   } while (qr.getSize() > 0);
           } else {
                    System.out.println("No records found.");
           }            

          getUserInput("Query succesfully executed. \nHit return to continue...");
     } catch (ApiFault ex) {
         System.out.println("\nFailed to execute query succesfully, error message was: 
                            \n" + ex.getMessage());
         getUserInput("\nHit return to continue...");
     }
    }

    private void run() throws ServiceException {
        if (login()) {
            getUserInput("SUCESSFUL LOGIN! Hit the enter key to continue.");
            describeGlobalSample();
            describeSample();
            querySample();
        }
    }
}

This section walks through a sample C# client application. The purpose of this sample application is to show the required steps for logging in and to demonstrate the invocation and subsequent handling of several API calls.

This sample application performs the following main tasks:

In the following sample code, API calls and other significant code is identified in a bold font. In addition, note the error handling code that follows each API call.

The following code begins the sample C# client application.

using System;

namespace Walkthrough
{
    class WalkthroughSample
    {
        private sforce.SforceService binding;
        static private WalkthroughSample walkthroughSample;
        [STAThread]
        static void Main(string[] args)
        {
            walkthroughSample = new WalkthroughSample();
            walkthroughSample.run();
        }

        public void run() 
        {
            //Call the login call
            if ( login() ) 
            {
                //Do a describe global
                describeGlobal();

                //describe an account object
                describeSObject("account");

                //retrieve some data using query
                querySample();
            }
        }

The login() method retrieves the user’s login credentials, instantiates a binding stub (which is the main interface to the API through which all calls are made), and invokes the login() call.

For the login() call, the initial endpoint is always http(s)//www.salesforce.com. Once the client application has logged in successfully, however, a client application uses the results of the login() call to reset the endpoint of the service to the virtual server instance that is servicing your organization. After logging in successfully, the sample client application:

        private void login() 
        { 
          // Create service object  
          SforceService sfdc = new SforceService(); 
          // Invoke the login call and save results in LoginResult 
          LoginResult lr = sfdc.login("username","password"); 
          if (!lr.passwordExpired) {
             // Reset the SOAP endpoint to the returned server URL 
             sfdc.Url = lr.serverUrl; 
             // Create a new session header object 
             // Add the session ID returned from the login 
             sfdc.SessionHeaderValue = new SessionHeader(); 
             sfdc.SessionHeaderValue.sessionId = lr.sessionId; 
             GetUserInfoResult userInfo = lr.userInfo; 
         } else {
           Console.Writeine("You password is expired.");
         }
       } 

Note

The describeGlobal method determines the objects that are available to the logged in user. It invokes a describeGlobal() call, which returns all of the objects that are visible to the logged-in user (see Factors that Affect Data Access). This call should not be made more than once per session, since the data returned from the call is not likely to change frequently. The DescribeGlobalResult is simply echoed to the console.

private void describeGlobal() 
        {
            //The describe global will return an array of object names that
            //are available to the logged-in user
            sforce.DescribeGlobalResult dgr = binding.describeGlobal();Console.WriteLine("\nDescribe Global Results:\n");

            //Loop through the array echoing the object names to the console
            for (int i=0;i<dgr.types.Length;i++)
            {
                  Console.WriteLine(dgr.types[i]);
            }
            Console.WriteLine("\n\nHit enter to continue...");
            Console.ReadLine();
         }

Note

The describeSObject method illustrates the type of metadata information that can be obtained for each object available to the user. The sample client application executes a describeSObject() call on a given object and then echoes the returned metadata information to the console. Object metadata information includes permissions, field types and lengths, and available values for picklist fields and types for referenceTo fields.

private void describeSObject(string objectType) 
        {
            //Call the describeSObject passing in the object type name
            sforce.DescribeSObjectResult dsr =
                  binding.describeSObject(objectType);

            //The first properites we will echo are on the object itself
            //First we will output some Descriptive info on the object
            Console.WriteLine("\n\nObject Name: " + dsr.name);
            if (dsr.custom) Console.WriteLine("Custom Object");
            if (dsr.label != null) Console.WriteLine("Label: " + dsr.label);
            
            //now the permissions on the object
            if (dsr.activateable) Console.WriteLine("Activateable");
            if (dsr.createable) Console.WriteLine("Createable");
            if (dsr.deletable) Console.WriteLine("Deleteable");
            if (dsr.queryable) Console.WriteLine("Queryable");
            if (dsr.replicateable) Console.WriteLine("Replicateable");
            if (dsr.retrieveable) Console.WriteLine("Retrieveable");
            if (dsr.searchable) Console.WriteLine("Searchable");
            if (dsr.undeletable) Console.WriteLine("Undeleteable");
            if (dsr.updateable) Console.WriteLine("Updateable");

            //Now we will retrieve meta-data about each of the fields
            for (int i=0;i<dsr.fields.Length;i++)
            {
                //Create field object for readability
                sforce.Field field = dsr.fields[i];
                
                //Echo some useful information
                Console.WriteLine("Field name: " + field.name);
                Console.WriteLine("\tField Label: " + field.label);
                //This next property indicates that this 
                //field is searched when using
                //the name search group in SOSL
                if (field.nameField) 
                    Console.WriteLine("\tThis is a name field.");
                if (field.restrictedPicklist) 
                    Console.WriteLine("This is a RESTRICTED picklist field.");
               Console.WriteLine("\tType is: " + field.type.ToString());
                if (field.length > 0) 
                    Console.WriteLine("\tLength: " + field.length);
                if (field.scale > 0) 
                    Console.WriteLine("\tScale: " + field.scale);
                if (field.precision > 0) 
                    Console.WriteLine("\tPrecision: " + field.precision);
                if (field.digits > 0) 
                    Console.WriteLine("\tDigits: " + field.digits);
                if (field.custom) 
                    Console.WriteLine("\tThis is a custom field.");
                //Output the permission on this field.
                if (field.nillable) Console.WriteLine("\tCan be nulled.");
                if (field.createable) Console.WriteLine("\tCreateable");
                if (field.filterable) Console.WriteLine("\tFilterable");
                if (field.updateable) Console.WriteLine("\tUpdateable");

                //If this is a picklist field, we will show the values
                if (field.type.Equals(sforce.fieldType.picklist)) 
                {
                   Console.WriteLine("\tPicklist Values");
                      for (int j=0;j<field.picklistValues.Length;j++)
                      Console.WriteLine("\t\t" + field.picklistValues[j].value);
                }

                //If this is a foreign key field (reference), 
                //we will show the values
                if (field.type.Equals(sforce.fieldType.reference)) 
                {
                    Console.WriteLine("\tCan reference these objects:");
                    for (int j=0;j<field.referenceTo.Length;j++)
                       Console.WriteLine("\t\t" + field.referenceTo[j]);
                }
                Console.WriteLine("");

            }
        
            Console.WriteLine("\n\nHit enter to continue...");
            Console.ReadLine();
        }  

Note

The querySample() method executes a query by invoking the query() call, passing a simple query string ("select FirstName, LastName from Contact"), and iterating through the returned QueryResult.

        private void querySample() 
        {
            //The results will be placed in qr
            sforce.QueryResult qr = null;

            //We are going to increase our return batch size to 250 items
            //Setting is a recommendation only, different batch sizes may
            //be returned depending on data, to keep performance optimized.
            binding.QueryOptionsValue = new sforce.QueryOptions();
            binding.QueryOptionsValue.batchSize = 250;
            binding.QueryOptionsValue.batchSizeSpecified = true;

            try 
            {
               qr = binding.query("select FirstName, LastName from Contact");
               bool done = false;
               if (qr.size > 0)
               {
                  Console.WriteLine("Logged-in user can see " 
                        + qr.records.Length + " contact records.");
                  while (!done) 
                  {
                   Console.WriteLine("");
                   for (int i=0;i<qr.records.Length;i++)
                   {
                      sforce.Contact con = (sforce.Contact)qr.records[i];
                      string fName = con.FirstName;
                      string lName = con.LastName;
                      if (fName == null)
                      Console.WriteLine("Contact " + (i + 1) + ": " + lName);
                      else
                      Console.WriteLine("Contact " + (i + 1) + ": " + fName 
                             + " " + lName);
                     }
                  if (qr.done) 
                  {
                     done = true;
                  } 
                  else 
                  {
                     qr = binding.queryMore(qr.queryLocator);
                  }
                  }
               }
               else 
               {
                  Console.WriteLine("No records found.");
               }
            }
            catch (Exception ex) 
            {
                Console.WriteLine("\nFailed to execute query succesfully, 
                     error message was: \n" + ex.Message);
            }
            Console.WriteLine("\n\nHit enter to exit...");
            Console.ReadLine();
        }
    }
}