July 11, 2010

“Tolerado” - Salesforce Web Service client wrappers !

I am starting a new open source project called “Tolerado”. Tolerado will be a wrapper API over Salesforce Java Web service client (Apache Axis, WSC integration planned too). This project is started with motivation to make client java code more fault tolerant, recoverable and stable at production, so its named “Tolerado”. Tolerado will give wrapper API over Metadata, Partner and Apex WSDL APIs.

Core Motive

Motive is to create an API that wraps existing Salesforce web service client APIs and

  • Giving a RECOVERABLE framework for each web service method call. This recoverable framework will transparently RETRY all the recoverable web service/remote errors/exceptions rather failing fast.   Why recovering is important is explained here.
  • Giving an transparent caching mechanism for salesforce session id/urls, so that we save a login web service call.
  • Giving utility and wrapper API's for easing and making development effort less error prone with existing WS client stubs. For ex.
    • Easing the creation of new Sobjects via wrappers rather using “com.sforce.soap.partner.sobject.SObject” and notorious MessageElement.
    • Giving easy stubs, so that developers are not into hassle of setting right session headers, server urls etc for using either Metadata, Apex or Partner WSDL APIs.
  • Keeping the migration effort to minimal. So classes are designed to fit well with existing Axis generated classes for ex. QueryResult, RunTestsResult etc.

Tolerado Design/Components

Tolerado is having 3 main components, these match almost exactly to the motives mentioned above. Here is the list

  1. ToleradoStub(s) : These stubs are set of huge wrapper classes over all the web service calls exposed by partner, metadata and apex web service calls. (100 % Complete, code checked in with few samples) . It gives
    • Management of session headers and all other housekeeping required to keep the state correct in various partner, metadata and apex stubs.
    • Fault tolerant behavior to each web service method.
    • Transparent Salesforce SessionID + Server URL caching. So future web service calls can reuse the tokens. Those tokens are automatically renewed on expiry.
  2. ToleradoQuery : Its a partner query helper class. When querying with partner binding you can directly fetch only 500 records. To fetch more then 500 one needs to use queryMore() API, this API requires setting some headers and maintaining a cursor on client. This class simplifies and exposes and easy to use interface to queryMore() API, so it does all the ground work for making the call correctly. (100 % Complete, code checked in with few samples)
  3. ToleradoSObject : Wraps the com.sforce.soap.partner.sobject.SObject class, so that creating, updating and working with attributes can be pretty correct and easy. (I am in middle of development 30 % Complete, will check-in the code soon)

Source @ Google Code

Complete source code including the sample I am creating are available here. I am code complete. One can do an anonymous checkout from SVN, instructions available here.

References

For more info on “Tolerado”, please follow these pointers

TODOs ?

Guys, biggest TODO and help would be to test and start playing with the API, and report bugs. So here is the list

  • Add more documentation, add pages like FAQ and Videos for quickly productive with Tolerado
  • More more testing