SOAP Connect

From LongJump Support Wiki

SOAP Connect (Redirected from SOAP)
Jump to: navigation, search

SOAP (Simple Object Access Protocol) is an XML-based protocol to let applications exchange information over HTTP. SOAP provides a way to communicate between applications running on different operating systems, with different technologies and programming languages. You can connect to the platform as a Web service from clients through SOAP Connect.

WSDL (Web Service Description Language) is an XML-based language for describing Web services and how to access them. WSDL is often used with SOAP to provide Web services over the Internet. The platform provides WSDL that describes the SOAP Connect Web service.

Although you can write client code that builds, sends, receives, and reads SOAP message strings, you probably want to use a toolkit to speed your development. Apache Axis2 is such a framework, including tools to generate Java client classes from WSDL. The Axis 2 tools are command-line driven, but you can invoke them from a graphical user interface in the soapUI application.

SOAP Connect complies with these specifications:

Contents

Setup and Configuration

These steps show you how to set up and configure a client computer to use SOAP Connect.

You must have a Java Runtime Environment (version 1.6 or later) installed.

  1. Create A WSDL file for the Web service. Get the client WSDL from https://www.longjump.com/networking/Service?t=3570.
    View the page source, select all the text, copy it, and then paste it to a local file.
  2. Install soapUI.
    You can download soapUI from http://soapui.org.
  3. Install Axis2. You can download Axis2 from http://ws.apache.org/axis2/download/1_4_1/download.cgi
    We have tested SOAP Connect with the Axis2 download at this mirror: http://www.trieuvan.com/apache/ws/axis/1_4.
    You can learn more about Axis at http://ws.apache.org/axis.
  4. Configure environment variables:
    • Set AXIS2_HOME to the directory that contains the Axis bin subdirectory (such as C:\axis2-1.4-bin\axis2-1.4).
    • Set JAVA_HOME to where you installed the Java Runtime Environment.

Generate Classes

These steps show you how to use soapUI to generate the client stub class, platform object classes, and the test class.

  • You call methods in the stub class (LongJumpServiceStub) to invoke operations in SOAP Connect. These methods are described in the Operation Method Reference.
  • You create instances of the platform object classes and call their getter and setter methods to get and set the objects' fields.
  • The test class has methods that invoke all the operations in SOAP Connect; however the method implementations are empty and you must add code to them.
  1. Open soapUI and select Tools | Axis 2 Artifacts.
  2. Click the Basic tab.
    • Specify the path to the WSDL file.
    • Specify ADB as the databinding method.
    • Specify the output directory where the stub classes will be generated.
    • Check sync and test-case.
  3. Click the Advanced tab and check generate all and unpack classes.
  4. Click Tools and set Axis2 to the location where you installed Axis. Click the [Ok] button.
  5. Click the [Generate] button. soapUI generates the classes in the directory you specified.
  6. Add implementations to the test classes.

Using Platform Objects

Objects in the platform represent database tables that contain your application's data. In soapUI, when you checked unpack classes, a class was generated for each Object in your application. soapUI generates the object classes in the com.longjump.ws.soap.dao.* package. You must import this package into any SOAP Connect application that you write.

Considerations
  • Each object class has a getter and setter method (such as getName and setName) for each field in the object
  • When you add, update, or retrieve an object in a SOAP Connect application, you must create an instance of it and call its getter and setter methods as appropriate
  • For add and update operations, when you instantiate an object, specify the same name as in the Object Name field, but capitalize the first letter. For example, for the object named "contact": 
Contact updateContact = new Contact();
  • For search and delete operations, when you call setObjectType, specify the same name as in the Object Name field in the Properties tab. However, you do not capitalize the first letter of the object name. For example, again for the object named "contact": 
searchRecords2Delete.setObjectType("contact");


Identifying Objects and Records

Many of the API record handling calls require an <object> element identifier. To find the Object Identifier:


The object identifier is a unique identifier for an object type, and is used to reference object identifiers in APIs. The object identifier format differs, depending whether the object is an Object or a System-Generated Object.

Learn more:

Find the Object Identifier in Objects

To find the object identifier syntax for Objects:

  1. Click Setup | Customize | Objects | <object name>
  2. Click the Properties tab to see the object identifier
  • Object Name is typically used in APIs, because it is more "readable", although Object Id can be used as well
Object Name




Relating Objects

As you add, update, and delete objects, you need to maintain their associations. For example, when you create an order, you need to associate it to a customer. In the platform user interface, you relate one object to another using the Lookup field as described in Relating Objects Using Lookups. In SOAP Connect, you relate one object to another in code by searching for an object and then using a field value that identifies the object to set a field in a related object. For example, in code you can search for a customer and then use the customer number to set the customer field in an order.

To show how to relate objects in SOAP Connect, this example creates a task object and then searches for a user to which to associate the task. The first step is to create the task object: 

import com.longjump.ws.soap.dao.*;
// ...

LongJumpServiceStub stub = new LongJumpServiceStub();
SoapClient2Account t = new SoapClient2Account();

AddRecordsRequest addTaskRecordsRequest = (AddRecordsRequest) t.getTestObject(AddRecordsRequest.class);
Task acntTask = new Task();
acntTask.setAction_type("Fax");
// ... Set other task fields

Then the code sets up and performs a search for a user: 

SearchRecordsRequest searchUser4Assigned = (SearchRecordsRequest)
    t.getTestObject(SearchRecordsRequest.class);
searchUser4Assigned.setObjectType("user");
searchUser4Assigned.setFields("record_id");
searchUser4Assigned.setCriteria("name1='fred smith'");

SearchRecordsResponse searchUser4AssignedResponse = stub.searchRecords(searchUser4Assigned);

int searchUser4AssignedLength = (searchUser4AssignedResponse.getSearchRecordsResult()).length;
LjObject[] search4User = new LjObject[searchUser4AssignedLength]; 

// Code below assumes only 1 record is returned
search4User[0] = (searchUser4AssignedResponse.getSearchRecordsResult())[0];

Now take the Id field from the retrieved user record and use it to set the Assigned_Id field of the user record. This sets up the relationship between the task and user objects. 

acntTask.setAssigned_id(Integer.parseInt((((User)(search4User[0])).getId()).trim()));

Now you can add the task to the database: 

LjObject[] addLJTask = new LjObject[1];
addLJTask[0] = acntTask;
addTaskRecordsRequest.setLjObjects(addLJTask);
AddRecordsResponse addTaskResponse = null;
addTaskResponse = stub.addRecords(addTaskRecordsRequest);

Operation Method Reference

This section describes the operation methods in LongJumpServiceStub:

All parameters and returns are in this package:

  • com.longjump.ws.soap.operation.LongJumpServiceStub

For brevity, this package name is not shown in the signatures in this topic.

login

Logs a user into the platform.

Syntax 

LoginResponse login(LoginRequest loginRequest)

Parameter

LoginRequest has these methods:

  • java.lang.String getUsername()
  • void setUsername(java.lang.String param)
  • java.lang.String getPassword()
  • void setPassword(java.lang.String param)

Return

LoginResponse has these methods:

  • SOAPResponse getLoginResult()
  • void setLoginResult(SOAPResponse param)

Example

This example creates an instance of LongJumpServiceStub in stub and an instance of itself. It then calls its getTestObject method to create an instance of LoginRequest named loginRequest4Account as an ADBBean. (ADB (Axis2 Data Binding) is a framework that processes SOAP messages.) Then the code sets the username and password in loginRequest4Account, which it passes as a parameter to the login method of stub. 

import com.longjump.ws.soap.dao.*;    // platform object classes generated
                                      // by soapUI "unpack classes" option

public class SoapClient2Account
{  
    public static void main(String[] args) throws Exception
    {
        LongJumpServiceStub stub = new LongJumpServiceStub();
        
        SoapClient2Account t = new SoapClient2Account();

        LoginRequest loginRequest4Account = (LoginRequest) t.getTestObject(LoginRequest.class);
        
        loginRequest4Account.setUsername("mia@financio.com");
        loginRequest4Account.setPassword("longjump1");
        
        LoginResponse response = stub.login(loginRequest4Account);
        
        System.out.println("SOAPResponse : " + response.getLoginResult());
        
        String sessionId = response.getLoginResult().getMessage();
        
        stub._getServiceClient().addStringHeader(new javax.xml.namespace.QName(
            "urn:operation.soap.ws.longjump.com", "sessionId"), sessionId);
        ...

searchRecords

Searches for objects based on a criteria that you specify.

Syntax 

SearchRecordsResponse searchRecords(SearchRecordsRequest searchRecordsRequest)

Parameter

SearchRecordsRequest has these methods:

  • java.lang.String getObjectType()
  • void setObjectType(java.lang.String param)
  • void java.lang.String getFields()
  • void setFields(java.lang.String param)
  • java.lang.String getCriteria()
  • void setCriteria(java.lang.String param) (You specify the same type of string as in a Filter Expression

Return

SearchRecordsResponse has these methods:

  • LjObject[] getSearchRecordsResult()
  • setSearchRecordsResult(LjObject[] param)
  • void addSearchRecordsResult(LjObject param)

Example

This example calls the getTestObject method to create an instance of SearchRecordsRequest named searchAccountRecordsRequest as an ADBBean. Then the code sets parameters for the search in searchAccountRecordsRequest which it passes as a parameter to the searchRecords method of stub. 

SearchRecordsRequest searchAccountRecordsRequest = (SearchRecordsRequest)
    t.getTestObject(SearchRecordsRequest.class);

searchAccountRecordsRequest.setObjectType("account");

searchAccountRecordsRequest.setFields("record_id,name,number,agent_id,
    billing_account_id,city,country,county,description,do_not_call,
    do_not_fax,duns_number,employees,fax,industry,lead_source,
    ownership,parent_id,phone,primary_contact_id,rating,state,street,
    ticker,type,website,zip,date_created");
searchAccountRecordsRequest.setCriteria("name ends with 'Society'");
searchAccountRecordsRequest.setSort_column("name");
searchAccountRecordsRequest.setSort_order("DESC");

SearchRecordsResponse searchResponse = stub.searchRecords(searchAccountRecordsRequest);

int searchLength = (searchResponse.getSearchRecordsResult()).length;
LjObject[] searchLjObject = new LjObject[searchLength];

//Records retrieved
System.out.println("Number of Records Retrieved = " +
    (searchResponse.getSearchRecordsResult()).length);
//To show how the records from search response can be retrieved
for(int i=0; i<searchLength; i++) {
 searchLjObject[i] = (searchResponse.getSearchRecordsResult())[i];
 System.out.println("****************Result "+ i + "*************");
  System.out.println("   Record ID:" + ((Account)(searchLjObject[i])).getId());
  System.out.println("   Name:" + ((Account)(searchLjObject[i])).getName());
  System.out.println("   Number:" + ((Account)(searchLjObject[i])).getNumber());
  System.out.println("   Address:" + ((Account)(searchLjObject[i])).getStreet());
  System.out.println("   City:" + ((Account)(searchLjObject[i])).getCity());
  System.out.println("   State:" + ((Account)(searchLjObject[i])).getState());
  System.out.println("   Zip:" + ((Account)(searchLjObject[i])).getZip());
  System.out.println("   Country:" + ((Account)(searchLjObject[i])).getCountry());
  System.out.println("   Phone:" + ((Account)(searchLjObject[i])).getPhone());
  System.out.println("   Description:" + ((Account)(searchLjObject[i])).getDescription());
  System.out.println("   Agent ID:" + ((Account)(searchLjObject[i])).getAgent_id());
  System.out.println("   Billing Account ID:" + ((Account)(searchLjObject[i])).getBilling_account_id());
  System.out.println("   Date Created:" + ((Account)(searchLjObject[i])).getDate_created());
  System.out.println("   Industry:" + ((Account)(searchLjObject[i])).getIndustry());
  System.out.println("   Last Activity:" + ((Account)(searchLjObject[i])).getLast_activity());
  System.out.println("   Primary Contact ID:" + ((Account)(searchLjObject[i])).getPrimary_contact_id());
  System.out.println("   Do Not Call:" + ((Account)(searchLjObject[i])).getDo_not_call());
  System.out.println("   Website:" + ((Account)(searchLjObject[i])).getWebsite());
  System.out.println("   Do Not Call:" + ((Account)(searchLjObject[i])).getDo_not_call());
}

addRecords

Adds one or more objects.

Syntax 

AddRecordsResponse addRecords(AddRecordsRequest addRecordsRequest)

Parameter

AddRecordsRequest has these methods:

  • LjObject[] getLjObjects()
  • void setLjObjects(LjObject[] param)
  • void addLjObjects(LjObject param)

Return

AddRecordsResponse has these methods:

  • SOAPResponse[] getAddRecordsResult()
  • void setAddRecordsResult(SOAPResponse[] param)
  • void addAddRecordsResult(SOAPResponse param)

Example

This example calls the getTestObject method to create an instance of AddRecordsRequest named addAccountRecordsRequest as an ADBBean and an instance of Account named accountRecord. The code sets parameters for the add in accountRecord and creates an instance of LjObject named ljObjects to which it assigns accountRecord as an element. Then the code sets ljObjects into addAccountRecordsRequest. Finally, the code passes addAccountRecordsRequest as a parameter to the addRecords method of stub. 

AddRecordsRequest addAccountRecordsRequest = (AddRecordsRequest)
    t.getTestObject(AddRecordsRequest.class);

// Fill in the addRecordsRequest here
Account accountRecord = new Account();

accountRecord.setName("SOAP Account" + new Date());
accountRecord.setNumber("SOAP_ACNT_" + new Date());
accountRecord.setCountry("Brazil");

// Create the array of ljObjects and fill the custom objects

LjObject[] ljObjects = new LjObject[1];
ljObjects[0] = accountRecord;

//Set the ljobject[] in the request body

addAccountRecordsRequest.setLjObjects(ljObjects);

//Call for addrequest to the server

AddRecordsResponse addResponse = null;

addResponse = stub.addRecords(addAccountRecordsRequest);
//Read the response

System.out.println("\n\nService response for addRequest :");

for (SOAPResponse soapRes : addResponse.getAddRecordsResult()) {

    System.out.println(" Code = " + soapRes.getCode() + " :Message = " + soapRes.getMessage());
}

deleteRecords

Deletes one or more objects.

Syntax 

DeleteRecordsResponse deleteRecords(DeleteRecordsRequest deleteRecordsRequest)

Parameter

DeleteRecordsRequest has these methods:

  • java.lang.String getObjectType()
  • void setObjectType(java.lang.String param)
  • java.lang.String[] getObjectIds()
  • void setObjectIds(java.lang.String[] param)
  • void addObjectIds(java.lang.String param)

Return

DeleteRecordsResponse has these methods:

  • SOAPResponse[] getDeleteRecordsResult()
  • void setDeleteRecordsResult(SOAPResponse[] param)
  • void addDeleteRecordsResult(SOAPResponse param)

Example

This example calls the getTestObject method to create these ADBBeans:

  • An instance of DeleteRecordsRequest named delRequest
  • An instance of SearchRecordsRequest named searchRecords2Delete

The code sets parameters for the search in searchRecords2Delete which it passes as a parameter to the searchRecords method of stub.

The code then creates an instance of LjObject named search2DeleteLjObject. In a loop, each record in the result of the search is assigned to search2DeleteLjObject as an element and each element of a String array named accountRecords2Delete is assigned the record identifier.

The accountRecords2Delete array and the object type are assigned as delRequest members. Finally, the code calls stub.deleteRecords, specifying delRequest as a parameter. 

DeleteRecordsRequest delRequest = (DeleteRecordsRequest)
    t.getTestObject(DeleteRecordsRequest.class);

SearchRecordsRequest searchRecords2Delete = (SearchRecordsRequest)
    t.getTestObject(SearchRecordsRequest.class);

// Search for records to delete 
searchRecords2Delete.setObjectType("account");
searchRecords2Delete.setFields("record_id");
searchRecords2Delete.setCriteria("name contains 'Account'");

SearchRecordsResponse search2DeleteResponse = stub.searchRecords(searchRecords2Delete);
//Created the array of LjObject to delete if the search results are not null
if(search2DeleteResponse.localSearchRecordsResult != null) {
    int search2DeleteLength = (search2DeleteResponse.getSearchRecordsResult()).length;
    LjObject[] search2DeleteLjObject = new LjObject[search2DeleteLength];
    String[] accountRecords2Delete = new String[search2DeleteLength];
  
    System.out.println("Number of Records Retrieved = " +
        (search2DeleteResponse.getSearchRecordsResult()).length);
    for(int i=0; i<search2DeleteLength; i++) {
        search2DeleteLjObject[i] = (search2DeleteResponse.getSearchRecordsResult())[i];
        accountRecords2Delete[i] = ((Account)(search2DeleteLjObject[i])).getId();
    }
    //set the request parameters
    delRequest.setRecordIds(accountRecords2Delete);
    delRequest.setObjectType("account");

    //Actual call to the server
    //DeleteRecordsResponse deleteResponse = stub.deleteRecords(delRequest);

    System.out.println("\n\nDelete request response :");
    for(SOAPResponse delSoapResponse: deleteResponse.getDeleteRecordsResult()){
        System.out.println(" Code = "+delSoapResponse.getCode()+" :Message = " + 
            delSoapResponse.getMessage());
    }
}

updateRecords

Updates one or more objects.

Syntax 

UpdateRecordsResponse updateRecords(UpdateRecordsRequest updateRecordsRequest)

Parameter

UpdateRecordsRequest has these methods:

  • LjObject[] getLjObjects()
  • void setLjObjects(LjObject[] param)
  • void addLjObjects(LjObject param)

Return

UpdateRecordsResponse has these methods:

  • SOAPResponse[] getUpdateRecordsResult()
  • void setUpdateRecordsResult(SOAPResponse[] param)
  • void addUpdateRecordsResult(SOAPResponse param)

Example

This example calls the getTestObject method to create:

  • An instance of UpdateRecordsRequest named updateReq as an ADBBean
  • An instance of Account named updateAcnt.

The code sets the city member of updateAcnt and creates an instance of SearchRecordsRequest named searchAccountRecord4update as an ADBBean. The code sets parameters for the search in searchAccountRecord4update which it passes as a parameter to the searchRecords method of stub.

The code then creates instances of LjObject named updateAccountLjObjects and updateObjects. In a loop, each record in the results of the search are assigned to updateAccountLjObjects. The code extracts each record identifier from updateAccountLjObjects and uses it to set the identifier field in updateAcnt; other fields in updateAcnt are set directly. At the end of the loop, updateAcnt is assigned as an element of updateObjects.

Next, updateObjects is assigned to updateReq. Finally, the code calls stub.updateRecords, specifying updateReq as a parameter. 

UpdateRecordsRequest updateReq = (UpdateRecordsRequest) t.getTestObject(UpdateRecordsRequest.class);

Account updateAcnt = new Account();

updateAcnt.setCity("Santa Clara");

//search the Account's object for a record to update 
SearchRecordsRequest searchAccountRecord4update = (SearchRecordsRequest)
    t.getTestObject(SearchRecordsRequest.class);

searchAccountRecord4update.setObjectType("account");
searchAccountRecord4update.setFields("record_id");
searchAccountRecord4update.setCriteria("name starts with 'SOAP'");

SearchRecordsResponse search4Account2UpdateResponse = stub.searchRecords(searchAccountRecord4update);

int search4Account2UpdateResponseLength = (search4Account2UpdateResponse.getSearchRecordsResult()).length;
LjObject[] updateAccountLjObjects = new LjObject[search4Account2UpdateResponseLength];

System.out.println("Number of Records Retrieved = " + search4Account2UpdateResponseLength);
//Create an array of ljObjects to the size of search result
//retrieve the records from the search result and update each one and save it to the 
//LjObjects array to be passed to the updateRequest call to save on the server.
//Create two arrays to test mass update of records retrieved from a search response

LjObject[] updateObjects = new LjObject[search4Account2UpdateResponseLength];
for(int i=0; i<search4Account2UpdateResponseLength; i++) {
    updateAccountLjObjects[i] = (search4Account2UpdateResponse.getSearchRecordsResult())[i];
    updateAcnt.setId((((Account)(updateAccountLjObjects[i])).getId()));
    updateAcnt.setZip("12345");
    updateAcnt.setCountry("United States");
    updateAcnt.setDescription("updated  using SOAP");
    updateAcnt.setCounty("Santa Clara");
    updateAcnt.setDo_not_call(true);
    updateAcnt.setFax("408-888-8888");
    updateAcnt.setIndustry("Agriculture");
    updateAcnt.setPhone("18009119111");
    updateAcnt.setType("Agency");
    updateAcnt.setState("CA");
    updateAcnt.setStreet("123 Main St");
    updateAcnt.setLead_source("Cold Call");
 
    //Set the customObjects in the ljObject array
    updateObjects[i] = updateAcnt;
}
//Set the update objects in the request
updateReq.setLjObjects(updateObjects);

/send the request to the server
UpdateRecordsResponse updateRes = stub.updateRecords(updateReq);

//Read the response from the server

System.out.println("\n\nUpdate request response: ----->");

for(SOAPResponse updateSoapResp: updateRes.getUpdateRecordsResult()){
    System.out.println(" Code = "+ updateSoapResp.getCode()+" :Message = "+
        updateSoapResp.getMessage());
}
Retrieved from "http://lj.platformatyourservice.com/~platfor1/wiki/index.php?title=SOAP_Connect"
Personal tools
Categories
[−] Help
[+] Overview
[+] Catalog
[+] Setup
[+] Building Applications
[+] Tips and Tricks