SOAP

1. SOAP Uses XML to perform RPC (remote procedure call) and has functionality like RMI

2. Soap & Xerces directories • You’ll need to download apache soap and the apache xerces parser.

3. Information on getting soap installed on tomcat is at • C:\soap\soap\docs\body.html • Mail.jar needs to be in tomcat\common\lib

4. Getting started Guide for SOAP installation • http://www.xmethods.net/gettingstarted/apache.html • You’ll need to copy the soap.war file into the tomcat webapps directory and fix classpath settings as mentioned elsewhere. (soap.jar, activation.jar, mail.jar are all needed)

5. Classpath- xerces, soap, mail must be in the classpath • My classpath is set to: C:\xerces-j-bin.2.7.0\xerces-2_7_0\xercesimpl.jar;C:\xerces-j-bin.2.7.0\xerces-2_7_0\resolver.jar;C:\jakarta-tomcat-5.5.10\common\lib\activation.jar;C:\jakarta-tomcat-5.5.10\common\lib\mail.jar;c:\program files\java\jdk1.5.0_03\bin;c:\program files\java\jdk1.5.0_03\lib;C:\Program Files\Java\jdk1.5.0_03\bin\javax;c:\soap\soap\lib\soap.jar

6. Deploying Apache-SOAP on Tomcat • There are two different ways to actually deploy Apache SOAP on Tomcat: • Method 1: Deploying the web archive. • The Apache SOAP distribution includes a web archive at /soap-2_3/webapps/soap.war. Simply drop this web archive into Tomcat's webapps directory (i.e. %tomcat_home%/webapps). If you deploy Apache SOAP into Tomcat in this manner, you will not need to have anything from the /soap-2_3 directory on your server's classpath (the relevant items are included in the web archive). Note: If you copy the web archive into the webapps directory while Tomcat is running, Tomcat will need to be restarted before the Apache SOAP web application can be accessed. • Keep in mind that if you want to replace the deployed Apache SOAP web application with a later version that you will probably have to shut the server down, remove the expanded %tomcat_home%/webapps/soap directory, and replace the %tomcat_home%/webapps/soap.war file with the newer one.

7. Guide for install • A Quick-Start Guide for Installing Apache SOAP (version 2.1) • Step 1. Install Java Virtual Machine • Install Java virtual machine (version 1.1 or later), either as part of the Java SDK installation or the Java Runtime Environment installation. You can download either installation from Sun's Java 2 Homepage • Step 2. Install Apache SOAP and Apache Xerces-J (XML Parser) • Important Note: It is essential that you run version 1.1.2 or later of Xerces-J. To download the complete packages and learn more about Apache SOAP and Xerces-J, visit the Apache SOAP Homepage and the Apache Xerces-J Homepage. Alternatively, you can download the following quickstart package: • quickstart.tar.gz (660K)quickstart.zip (657K) • The quickstart package contains: • soap.jar version 2.1 - contains Apache's SOAP client classes • xerces.jar version 1.2 - contains Apache's Xerces-J classes • mail.jar and activation.jar - required by Apache SOAP 2.1 • Apache license agreement

8. Quickstart I used the mail.jar and activation.jar from Quickstart, but am using Xercesimpl.jar from a download of current xerces parser Xerces-j-bin-2.7.0 Which you can find on the Apache site.

9. Checking soap installation • You’ll know it is working if you can go to your tomcat path/soap (http://localhost:8080/soap/) and get the “what do you want to do” message.

10. Soap message

11. Admin client displays: C:\soap\soap\docs\guide\index.html info about deploying services to Tomcat

12. Soap rpc router servlet displays: SOAP RPC Router Sorry, I don't speak via HTTP GET- you have to use HTTP POST to talk to me.

13. Deployment continued • Copy the class file for your server side service into the jakarta-tomcat/common/classes directory and or the jar file into the lib directory. • I did not use jar files (The jar file does not seem to be needed.) • You can create a jar for your server class with: jar cf jfname.jar classname.class

14. Client side and Server side classes with NO RETURNS • GetInt passes an int parameter which ReceiveInt receives. Call returns properly and messages are printed on both blackscreen sessions

15. Client side • GetInt – does NOT get an int, just passes one

16. Server and client side passing string • Serverside: import org.apache.soap.*; import org.apache.soap.rpc.*; import org.w3c.dom.*; public class ReturnString { public String returnString(String s) throws Exception { //String message=(String)m.getValue(); String text = "Welcome to SOAP!\nHere is your message: "+s; return (String)text; }}

17. Server and client side passing string C:\PROGRA~1\JAVA\JDK15~1.0_0\BIN>java GetAString Welcome to SOAP! Here is your message: whatever client side returned C:\PROGRA~1\JAVA\JDK15~1.0_0\BIN>

18. SOAP client as a Java applet • to write a SOAP client as a Java applet. Are there any 'tiny' SOAP client libraries I could use?Consider using SoapRMI for your client. It is 183KB (including full XML parser) and is available here: http://www.extreme.indiana.edu/soap/rmi/download/. For more details about its design, see: http://www.extreme.indiana.edu/soap/.

19. SOAP Client writing • http://www.xmethods.net/gettingstarted/apache.html#writingapacheclients

20. Tomcat & Soap I moved the soap.war file to tomcat/webapps and the jar files to: C:\jakarta\jakarta-tomcat-5.0.28\common\lib

21. An example • params.addElement (new Parameter ("StudentID", String.class, studentID, null)); Here we add a parameter that should be encoded with a different serializer (in this case, the XML serializer) than the default encoding set at the Call object level. • params.addElement(new Parameter ("StudentProfile", Element.class, profile, Constants.NS_URI_LITERAL_XML)); So it's clear now that we are sending two parameters to the method being invoked - a string, and an XML document. Note that the XML document could have also been sent as a string, in the default SOAP encoding. Now, we add the parameter to the call object: • call.setParams (params); and then invoke the method.

22. URL url = new URL ("http://www.mySoapRouter.com/soap/servlet/rpcrouter"); Response resp = call.invoke (url, ""); The URL object represents the SOAP endpoint that will be receiving the request. Typically (at least in Apache SOAP server implementations) , a single SOAP endpoint is capable of handling calls to multiple object interfaces and methods. Note that the invocation may throw a SoapException if something goes wrong, so you will need to make provisions to catch the exception. • Next, you will want to check the response to see if a exception was generated at the SOAP protocol level (such an exception would not throw a SoapException fault, which can be thought of as a "lower level" fault).

23. if (resp.generatedFault()) { Fault fault=resp.getFault(); System.out.println(" Fault code: " + fault.getFaultCode()); System.out.println(" Fault string: "+fault.getFaultString()); } else { Otherwise, the call was successful and a return value can be retrieved. Parameter stores values of class Object, so you will need to downcast the object to expected type for further handling. • Parameter result=resp.getReturnValue(); Object o = result.getValue(); } At this point, the method invocation is complete.

24. Writing RPC Clients Writing clients to access SOAP RPC-based services is fairly straightforward. Apache SOAP provides a client-side API to assist in the construction of the SOAP request, and then to assist in interpreting the response. Conceptually, RPC-based service are relatively easy to understand, because the concepts involved are those which may be found in any procedural based language. To invoke a procedure, you need the name of the procedure and the parameters to pass to it. When the invocation completes, you need to extract any response information from the return value and/or output parameters.

25. RPC Clients The basic steps for creating a client which interacts with a SOAP RPC-based service are as follows: Obtain the interface description of the SOAP service, so that you know what the signatures of the methods that you wish to invoke are.You can either look at a WSDL file (or at some other interface definition format) for the service, or directly at its implementation. Make sure that there are serializers registered for all parameters which you will be sending, and deserializers for all information which you will be receiving back.Parameters must be serialized into/deserialized from XML before they can be transmitted/received, and so Apache SOAP provides a number of pre-defined serializers/deserializers which are available. If you need to transmit or receive a type which has not been registered, then you will need to write and register your own serializer/deserializer. Create the org.apache.soap.rpc.RPCMessage.Call object.The Apache SOAP Call object is the main interface to the underlying SOAP RPC code Set the target URI into the Call object using the setTargetObjectURI(...) method.Pass in the URN that the service used to identify itself in its deployment descriptor.Set the method name that you wish to invoke into the Call object using the setMethodName(...) method.This must be one of the methods exposed by the service which is identified by the URN given in the previous step.

26. RPC clients Create any Parameter objects necessary for the RPC call and set them into the Call object using the setParams(...) method.Make sure that you have the same number of parameters with the same types as the service is expecting. Also make sure that there are registered serializers/deserializers for the objects which you will be transmitting/receiving. (See step 2.) Execute the Call object's invoke(...) method and capture the Response object which is returned from invoke(...).The invoke(...) method takes in two parameters, the first is a URL which identifies the endpoint at which the service resides (i.e. http://localhost/soap/servlet/rpcrouter) and the second is the value to be placed into the SOAPAction header. Remember that the RPC call is synchronous, and so may take a while to complete. Check the Response object to see if a fault was generated using the generatedFault() method. If a fault was returned, retrieve it using the getFault(...) method, otherwise extract any result or returned parameters using the getReturnValue() and getParams() methods respectively.While most of the providers will only return a result, if you have created your own provider (or obtained one from somewhere else,) it may also return output parameters. Because SOAP is a supposed to be a standard, you should be able to use the clients that you create with the Apache SOAP API to access services running on a different implementations, and vice versa.

27. Writing Message Clients • Writing clients to access SOAP message-oriented services requires that you interact with a lower-level set of Apache SOAP APIs than you would otherwise have to if you were writing a SOAP RPC-based client. However, message-oriented services provide you with a finer grain of control over what is actually being transmitted over SOAP. (In fact, the RPC mechanism is built on top of this message-oriented layer.) • The basic steps for creating a client which interacts with a SOAP message-oriented service are as follows: • Obtain the interface description of the SOAP service, so that you know what the format of the SOAP message should be (i.e. what headers it should have, what the body should look like, etc.) as well as the type of message exchange which will take place.You can either look at a WSDL file (or at some other interface definition format) for the service, or directly at its implementation. Unlike SOAP RPC, there is no predefined message exchange pattern defined, so a message-oriented service may return a SOAP envelope, may return another type of data, or may return nothing at all.

28. Construct an org.apache.soap.Envelope which contains the information that the SOAP service requires.At the very least, you will need to add an org.apache.soap.Body object to the envelope. You can optionally add headers as well.Note: When the message is received on the server, it will be routed to the proper service by looking at the XML Namespace associated with the first child element in the body, and then to the correct method/function within that service via the name of the element itself. • Create an org.apache.soap.messaging.Message object.If you need to add MIME attachments to your message, then you can use addBodyPart(...) method to do so. If you need to send your message over a transport other than HTTP, then you will need to invoke the setSOAPTransport(...) method.

29. Invoke the send(...) method on the Message object, providing the URL of the endpoint which is providing the service (i.e. http://localhost/soap/servlet/messagerouter), the actionURI, and your envelope. • If your service is returning data, and assuming that the transport supports two-way interaction, then you need to retrieve the SOAPTransport object from the Message object (assuming that you don't already have a handle to it) by using the getSOAPTransport() method. You can then invoke the receive() method on the SOAPTransport object to retrieve the returned data.If the service is returning a SOAP Envelope, then you can parse the XML and pass the root element to org.apache.soap.Envelope's unmarshall(..) method to allow it to reconstruct a SOAP Envelope object for you. If an error has occurred on the server during the processing of the request, the server will automatically send back a SOAP Envelope with a SOAP Fault in the body describing what went wrong.

30. Compile GetMessage.java C:\PROGRA~1\JAVA\JDK15~1.0_0\BIN>javac GetMessage.java -Xlint GetMessage.java:36: warning: [unchecked] unchecked call to addElement(E) as a member of the raw type java.util.Vector parameters.addElement( new Parameter( "message",String.class, message, null ) ); ^ 1 warning C:\PROGRA~1\JAVA\JDK15~1.0_0\BIN>

31. A service routine import java.io.*; import org.w3c.dom.*; import javax.xml.parsers.*; import org.apache.soap.rpc.*; public class SimpleService { public Element getWelcome( ) throws Exception { DocumentBuilderFactory factory =DocumentBuilderFactory.newInstance(); org.w3c.dom.Element root =null; try{ // get DocumentBuilder DocumentBuilder builder = factory.newDocumentBuilder(); //create root node Document document = builder.newDocument(); root = document.createElement("root"); Comment simpleComment=document.createComment("a comment"); root.appendChild(simpleComment);} catch(ParserConfigurationException pce){pce.printStackTrace();} return root; // return message to the request } }//service

32. Client side user • In notes

33. SOAP

34. online soap page

35. soap envelope to pass data via rpc <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"soap:encodingStyle="http://myHost.com/encodings/secureEncoding"><soap:Body><article xmlns="http://www.ibm.com/developer"><name>Soapbox</name><url>http://www-106.ibm.com/developerworks/library/x-soapbx1.html</url></article></soap:Body></soap:Envelope>

36. the rpc client • Create the SOAP-RPC call • Set up any type mappings for custom parameters • Set the URI of the SOAP service to use • Specify the method to invoke • Specify the encoding to use • Add any parameters to the call • Connect to the SOAP service • Receive and interpret a response

37. a client CDAdder • in notes

38. running the soap rpc from the command line • C:\javaxml2>java javaxml2.CDAdder http://localhost:8080/soap/servlet/rpcrouter "Riding the Midnight Train" "Doc Watson"   • Adding CD titled 'Riding the Midnight Train' by 'Doc Watson' • Successful CD Addition

39. CDLister class in notes • another rpc client • running the lister: C:\javaxml2>java javaxml2.CDLister http://localhost:8080/soap/servlet/rpcrouter Listing current CD catalog. 'Riding the Midnight Train' by Doc Watson 'Taproot' by Michael Hedges 'Nickel Creek' by Nickel Creek 'Let it Fall' by Sean Watkins 'Aerial Boundaries' by Michael Hedges

40. custom classes: a CD class: a bean with all get- set- methods and a default constructor package javaxml2;   public class CD {   /** The title of the CD */ private String title;   /** The artist performing on the CD */ private String artist;   /** The label of the CD */ private String label;   public CD( ) { // Default constructor }   public CD(String title, String artist, String label) { this.title = title; this.artist = artist; this.label = label; }   public String getTitle( ) { return title; }   public void setTitle(String title) { this.title = title; }   public String getArtist( ) { return artist; }   public void setArtist(String artist) { this.artist = artist; }   public String getLabel( ) { return label; }   public void setLabel(String label) { this.label = label; }   public String toString( ) { return "'" + title + "' by " + artist + ", on " + label; } }

41. new service using the CD class in notes • you’ll need to make a new jar file with the new class. • jar files go in the common/lib directory of tomcat • java> jar cvf javaxml2.jar javaxml2/CDCatalog.class javaxml2/CD.class

42. a revised deployment descriptor <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:cd-catalog" > <isd:provider type="java" scope="Application" methods="addCD getCD list" > <isd:java class="javaxml2.CDCatalog" static="false" /> </isd:provider>   <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>   <isd:mappings><isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"xmlns:x="urn:cd-catalog-demo" qname="x:cd"javaType="javaxml2.CD"java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/> </isd:mappings> </isd:service>

43. redeploy dd file • java> java org.apache.soap.server.ServiceManagerClient http://localhost:8080/soap/servlet/rpcrouter CDCatalogDD.xml

44. new CDAdder class using CD class in notes • test run: • C:\javaxml2>java javaxml2.CDAdder http://localhost:8080/soap/servlet/rpcrouter "Tony Rice" "Manzanita" "Sugar Hill" Adding CD titled 'Tony Rice' by 'Manzanita', on the label Sugar Hill Successful CD Addition.

45. better error handling import java.util.Iterator; … if (!response.generatedFault( )) { Parameter returnValue = response.getReturnValue( ); Hashtable catalog = (Hashtable)returnValue.getValue( ); Enumeration e = catalog.keys( ); while (e.hasMoreElements( )) { String title = (String)e.nextElement( ); CD cd = (CD)catalog.get(title); System.out.println(" '" + cd.getTitle( ) + "' by " + cd.getArtist( ) + " on the label " + cd.getLabel( )); } } else { Fault fault = response.getFault( ); System.out.println("Error encountered: " + fault.getFaultString( ));   Vector entries = fault.getDetailEntries( ); for (Iterator i = entries.iterator(); i.hasNext( ); ) {org.w3c.dom.Element entry = (org.w3c.dom.Element)i.next( );System.out.println(entry.getFirstChild().getNodeValue( ));} }

46. from dos window C:\PROGRA~1\JAVA\JDK15~1.0_0\BIN\JAVAXML2>java org.apache.soap.server.ServiceMan agerClient http://localhost:8080/soap/servlet/rpcrouter deploy CDCatalogDD.xml C:\PROGRA~1\JAVA\JDK15~1.0_0\BIN>jar cvf javaxml2.jar javaxml2/CDCatalog.class j avaxml2/CD.class added manifest adding: javaxml2/CDCatalog.class(in = 1235) (out= 691)(deflated 44%) adding: javaxml2/CD.class(in = 1049) (out= 507)(deflated 51%) C:\PROGRA~1\JAVA\JDK15~1.0_0\BIN>java javaxml2.CDAdder http://localhost:8080/soa p/servlet/rpcrouter "Tony Rice" "Manzanita" "Sugar Hill" Adding CD titled 'Tony Rice' by 'Manzanita', on the label Sugar Hill Successful CD Addition. C:\PROGRA~1\JAVA\JDK15~1.0_0\BIN>

47. using rpc soap // Create the parametersVector params = new Vector( );params.addElement(new Parameter("flightNumber", Integer.class, flightNumber, null)); params.addElement(new Parameter("numSeats", Integer.class, numSeats, null)); params.addElement(new Parameter("creditCardType", String.class, creditCardType, null)); params.addElement(new Parameter("creditCardNumber", Long.class, creditCardNum, null)); // Create the Call objectCall call = new Call( );call.setTargetObjectURI("urn:xmltoday-airline-tickets");call.setMethodName("buyTickets");call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);call.setParams(params); // InvokeResponse res = call.invoke(new URL("http://rpc.middleearth.com"), "");// Deal with the response

48. installs and configures • you will need • tomcat • xerces • activation.jar (JAF classes), mail.jar (java.sun.com/products/..) in your classpath • can put soap.jar and other jar files in common/lib of tomcat • soap.war needs to go in webapps directory

49. restart tomcat and check various things

50. checking routers for soap services