Building a Java integration with WSC

Using WSC in a Java integration is a four-piece workflow: download the WSDL and generate stubs, set up the Maven or Gradle build with the WSC runtime and the generated jar, write the authentication and API call code, and operationalize for production with retry and monitoring. Each piece is mostly mechanical, but the order matters and some pieces have non-obvious traps. This guide covers the standard pattern that most Java teams follow when standing up a new WSC-based Salesforce integration.

1. 1
   Download the WSDL and generate stubs

   In Salesforce Setup, search API. Pick the right WSDL for the integration (Partner for generic, Enterprise for type-safe, Metadata for deployment, Tooling for IDE work). Click Generate, save the WSDL to your project resources folder. Download the latest WSC jar from the salesforce/wsc GitHub releases. Run java with classpath wsc-VERSION.jar com.sforce.ws.tools.wsdlc your-wsdl.wsdl output-stub.jar. The result is a stub jar containing the typed Java classes. Commit both the WSDL and the stub jar to source control (or regenerate on every build, depending on the team preference). Document the WSDL version and the WSC version in the project README.

2. 2
   Set up the Java project build

   In Maven, add the WSC runtime as a dependency: groupId com.force.api, artifactId force-wsc, version matching the WSC release you used to generate stubs. Add the generated stub jar as either a separate Maven artifact (if it lives in an internal repository) or as a system-scope dependency (if local). For Gradle, the equivalent is a compile dependency on force-wsc and either an artifact dependency or a flat-dir dependency on the stub jar. Keep the WSC runtime version aligned with the version used for stub generation; mismatched versions cause cryptic runtime exceptions when the stub calls into the runtime.

3. 3
   Write authentication and API call code

   Create a ConnectorConfig with the org username, password (plus security token if applicable), and login URL (login.salesforce.com for production, test.salesforce.com for sandbox). Call Connector.newConnection(config) to authenticate and get a PartnerConnection. From the connection, call API methods: connection.create(sObjects), connection.query(soql), connection.update(records), connection.delete(ids). Wrap each call in try-catch for ConnectionException and ApiFault. Log every call timing and result. For OAuth, set the session id directly via ConnectorConfig.setSessionId(token) after obtaining the token through your OAuth flow. Document the authentication choice in the integration runbook.

4. 4
   Operationalize for production with retry and monitoring

   Wrap every WSC call in retry-with-exponential-backoff logic to handle transient failures (UNABLE_TO_LOCK_ROW, REQUEST_RUNNING_TOO_LONG, ConnectionTimeoutException). Configure retry counts and backoff intervals based on the operation idempotency: idempotent operations (queries, updates by ID) can retry aggressively; non-idempotent operations (creates without an external ID) need careful retry logic to avoid duplicates. Log every retry to a structured log so operators can diagnose chronic failures. Monitor the org daily API request limit; WSC calls count toward it. Set ConnectorConfig.setReadTimeout() and setConnectionTimeout() to values that match the org typical response times plus a safety margin.