Building SOAP API Client Applications with Apache Axis

To use the Apache Axis framework with SuiteProjects Pro SOAP web services:

1. Install Java JDK 8.

   Download and install Java JDK 8. Ensure that the executables are available through the system path. This is required because all inbound and outbound secure communication must use TLS 1.2 or TLS 1.3.

2. Download and install Apache Axis from http://ws.apache.org/axis/. The following steps are provided for Axis version 1.4 installed in C:\axis-1_4.

3. Set up Apache Axis to consume SuiteProjects Pro SOAP web services.

   1. Go to the directory where you want to generate the Java source code files and folders.

   2. Run the following command to:

      • Ensure that your CLASSPATH includes the required elements from the Axis binary distribution.

      • Use the WSDL2Java utility to generate the proxy classes from the SuiteProjects Pro WSDL definition.

                          java -cp c:\axis-1_4\lib\axis.jar;
      c:\axis-1_4\lib\axis-ant.jar;
      c:\axis-1_4\lib\commons-logging-1.0.4.jar;
      c:\axis-1_4\lib\commons-discovery-0.2.jar;
      c:\axis-1_4\lib\jaxrpc.jar;
      c:\axis-1_4\lib\log4j-1.2.8.jar;
      c:\axis-1_4\lib\wsdl4j-1.5.1.jar;
      org.apache.axis.wsdl.WSDL2Java -a <wsdl-file-url> 
      
                        

      Where <wsdl-file-url> is the URL for the SuiteProjects Pro WSDL. For more information about accessing or generating the WSDL for your account, see XML Schema and WSDL Definition Documents.

      Note:

      Use the WSDL2Java utility -a option to generate code for all elements, even unreferenced ones. By default, WSDL2Java only generates code for those elements in the WSDL file that are referenced.

      (Optional) Use the -p option to specify a package namespace instead of the default com.soaplite.namespaces.perl namespace.

      For more information about the WSDL2Java utility, see WSDL2Java: Building stubs, skeletons, and data types from WSDL (External link to Apache Axis website) and WSDL2Java Reference (External link to Apache Axis website).

   3. Compile the generated source code.

   Note:

   You can use Apache Ant or wizard-based tools instead of the command line to build the stub objects and proxy classes in most Java development environments.

4. Implement workaround to handle SAXExceptions caused by WSDL updates.

   Important:

   New objects and object properties may be added to the SuiteProjects Pro WSDL definition from time to time. These changes may not be automatically reflected in stubs generated using the WSDL2Java utility and may cause exceptions in your client application code.

   1. Create a subclass of org.apache.axis.encoding.ser.BeanDeserializer and override the onStartChild method to handle any SAXExceptions that may occur.

                          public class MyDeserializer extends BeanDeserializer {
         public MyDeserializer(java.lang.Class javaType, javax.xml.namespace.QNamexmlType,org.apache.axis.description.TypeDesc typeDesc)
            {
               super(javaType, xmlType, typeDesc);
            }
         public SOAPHandler onStartChild(String arg0, String arg1, String arg2, Attributes arg3, DeserializationContext arg4) throws SAXException
            {
               // TODO Auto-generated method stub
               try
                  { 
                     __return super.onStartChild(arg0, arg1, arg2,arg3, arg4);
                  }catch (SAXException e){
                     __return null;
                  }
            }
         } 
      
                        

   2. For each generated client class (oaEnvelope, oaTimesheet, etc.), change the getDeserializer method to use the new subclass of BeanDeserializer instead of the default implementation.

                          /**
        * Get Custom Deserializer 
      **/
      public static org.apache.axis.encoding.Deserializer getDeserializer( 
         java.lang.String mechType,
         java.lang.Class _javaType,
         javax.xml.namespace.QName _xmlType)
         {
            return new MyDeserializer( _javaType, _xmlTpe, typeDesc);
         } 
      
                        

5. Implement your application by writing your business logic using the generated Axis proxy classes.

   1. Locate the SuiteProjects Pro service.

                          OAirServiceHandlerServiceLocator locator = new OAirServiceHandlerServiceLocator(); 
      
                        

   2. Get an instance of the SuiteProjects Pro service.

                          m_svc = (OAirServiceSoapBindingStub)locator.getOAirService(); 
      
                        

   3. Authenticate by populating the LoginParams object and then invoking the login() operation.

                          LoginParams lp = new LoginParams();
      lp.setApi_namespace("<Your_API_Namespace>");
      lp.setApi_key("<Your_API_Key>");
      lp.setCompany("<Your_Company_ID>");
      lp.setUser("<Your_User_ID>");
      lp.setPassword("<Your_Password>");
      LoginResult loginResult = m_svc.login(lp); 
      
                        

      Replace <Your_API_Namespace>, <Your_API_Key>, <Your_Company_ID>, <Your_User_ID>, and <Your_Password> with your API namespace, API key, and SuiteProjects Pro company ID, user ID and password.

      The login() command creates a session and returns a session ID which you can use in the SOAP header to provide authentication for API calls implementing your business logic.

   4. Set up the SOAP header to include the session ID.

                          SOAPHeaderElement header = new SOAPHeaderElement("https://company-id.app.netsuitesuiteprojectspro.com/OAirService","SessionHeader");           
      SOAPElement node = header.addChildElement("sessionId");
      node.addTextNode(loginResult.getSessionId());
      m_svc.setHeader(header); 
      
                        

   5. Implement your business logic. For example, create a new customer in SuiteProjects Pro.

                          oaCustomer customer = new oaCustomer();
      customer.setName("XYZ Inc");
      try
         {
            // Add the customer and output any errors encountered
            UpdateResult result = m_svc.add(customer);
            if (result.getErrors() != null)
               {
                  for (oaBase base : result.getErrors())
                     {
                        oaError err = (oaError)base;
                        System.out.println("Error: " + err.getCode() + "\t" + err.getComment() + "\t" + err.getText());
                     }
               }
            if (result.getStatus() == "A") System.out.println("Customer added");
         } 
      
                        

   6. Sign out to invalidate the current session.

                          m_svc.logout();