G52IWS: Example Web-services

1. G52IWS: Example Web-services Chris Greenhalgh

2. Contents • Software requirements • AXIS web service run-time components • Getting started with Jetty & AXIS • Examples • Building • testing • File structure • Development components

3. Software • Jetty • A Java servlet container, i.e. runs Java web applications • AXIS • Apache project SOAP support, including web application-based server, client APIs and stub-generating tools • tcpmon – a TCP connection proxy and monitor for observing (e.g.) SOAP interactions • Ant • Apache project Java build tool – automates Java project compilation, etc from an XML project file

4. Software downloads • Should be installed in C:\G52IWS on terminal room machines • Download: • Jetty, e.g. http://dist.codehaus.org/jetty/jetty-6.1.5/jetty-6.1.5.zip • Ant, e.g. http://www.mirrorservice.org/sites/ftp.apache.org/ant/binaries/apache-ant-1.7.0-bin.zip • AXIS, e.g. http://mirror.public-internet.co.uk/apache/ws/axis/1_4/axis-bin-1_4.zip • Java SDK, e.g. from http://java.sun.com/javase/downloads/index.jsp

5. Web Service client & server runtime components Client Service/Server Client(Java) Jetty (or other servlet container)- handles HTTP & TCP Stub classes(optional) AXIS web application- handles SOAP & WSDL AXIStcpmon(optional) Server code(Java classesor JWS file)- handles applicationlogic SOAP (AXIS)client lib. Serverconfig(WSDD) SOAPoverHTTPoverTCP Browser(optional)

6. Getting started with Jetty & AXIS (1) • Create a webapps directory • on H: (Unix home directory) in the dept. • Use command “create webapps” on Unix machine • Should also create a log directory • Copy the AXIS webapp to it • Should be done automatically by “create webapps” • Otherwise, dir is webapps/axis in axis-1_4 binary distribution

7. Getting started with Jetty & AXIS (2) • If you are using your own Jetty installation • Check the configuration in jetty-6.1.5/etc/jetty.xml • By default webapps dir is jetty-6.1.5/webapps • Run jetty on local machine • In dept. C:\G52IWS\jetty-6.1.5\runJetty.bat • Otherwise, in jetty-6.1.5 dir (after configuring for Java if required)java -jar start.jar • Should start running without errors

8. Aside: selecting Java • Jetty requires a JDK rather than JRE for full functionality • Assume Java is installed in C:\Program Files\Java\jdk1.6.0_03: set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_03 set PATH=%JAVA_HOME%\bin;%PATH% • Check…javac -version • Shouldn’t give an error: “javac 1.6.0_03” (for example)

9. Getting started with Jetty & AXIS (3) • Open a web browser and enter this URL:http://localhost:8080/axis/index.html • i.e. local machine, port 8080 (jetty default), top-level path • Should see Apache AXIS welcome page • If not, • check jetty console output for errors • Check jetty.xml configuration for port and webapps directory • Check webapps/axis exists in right place • Check proxy not configured for local host (in browser) • Check it is a recent version of Java • Check it has a JDK and not just a JRE (esp. if first page shows but not redirected main page)

10. Getting started with Jetty & AXIS (4) • Click “Validation” link • Should report found needed components • If not, may have old JDK? • Go back and click “List” • Should show AdminService & Version services • Click “Version (wsdl)” • Should see WSDL for Version service • Go back twice and click “Call” • Should see SOAP response showing HTML header items • If not, probably using a JRE rather than a JDK

11. Building the examples (1) • Download g52iws-examples-20071016-1130.zip from G52IWS page • http://www.cs.nott.ac.uk/~cmg/G52IWS • Unzip • Open a command shell • Run program: “cmd”

12. Building the examples (2) • Set up the environment for Java & ANT e.g. set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_03 set ANT_HOME=C:\G52IWS\apache-ant-1.7.0 set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH% • Check that ant runs OK: ant • If it gives an error try setting the CLASSPATH: Set CLASSPATH=.

13. Building the examples (3) • Move into the examples directory • Edit build.properties to set the paths for AXIS and your webapps/axis directory:axis.webapp=H:/webapps/axisaxis.home=C:/G52IWS/axis-1_4… • Compile the server and two clientsant all • Deploy the servers to the Jetty-hosted axis webapp (while it is running!)ant deploy

14. Testing the examples (1) • In a browser, from the AXIS home page click the “List” link • The “SamplePort” service should now be visible with operations listAll, getMetadata & listMatching • Follow the “(wsdl)” to see the service’s WSDL • Call the service directly: enter the URL http://localhost:8080/axis/services/SamplePort?method=listAll • View the WSDL for JWS service SampleServer2: http://localhost:8080/axis/SampleServer2.jws?wsdl • Call the service: enter the URL http://localhost:8080/axis/SampleServer2.jws?method=handleString

15. Testing the examples (2) • In a new command shell, open a telnet (TCP) session to the server telnet localhost 8080 • Open the file list_all_unformatted.txt from the course web site, • select the region starting “POST” and ending immediately before “==== Response ====“ • Paste it into the telnet session

16. Testing the examples (3) • Run the example clients from ant: ant test ant test2

17. Running tcpmon • AXIS tcpmon allows the TCP communication to be monitored • Run tcpmon using the example ANT file: ant tcpmon • The tcpmon window will open • runs by default on port 8090, talking to local server on port 8080 (see ANT build.xml file)

18. Testing the examples via tcpmon • Repeat the test using URLs with …:8090/… rather than …:8080/… • This will communicate via tcpmon as a kind of proxy • tcpmon will show the messages sent/received • Various examples are included on the web page

19. Example code file structure: provided files • build.xml – ANT build file • build.properties – ANT configuration • etc/ - configuration files • SampleWebServices.wsdl – hand-crafted WSDL service definition • SampleServer2.wsdl – auto-generated WSDL for SampleServer2.jws • src/ - source files • SampleServer2.jws – simple Java Web Service • sample/client/SimpleClient.java – stub-based client • sample/client/SaajClient.java – SAAJ-based client • sample/client2/SimpleClient2.java – stub-based client for SampleServer2.jws • sample/server/stub/SampleSoapLiteralBindingImpl.java – server implementation

20. Example code file structure: built files • generated/ - generated from WSDL • sample/client/types/… - XSD type wrappers • Record.java, NameValuePair.java • sample/client/stub/… - service stub for client • SamplePortType.java, … • sample/client2/stub/… - JWS service stub • sample/server/types – XSD type wrappers for server • same as for client • sample/server/stub/… - service interface/skeleton, and WSDD deploy and undeploy definitions: • deploy.wsdd & undeploy.wsdd • build/… - compiled java .class files

21. Development components:WSDL-driven WSDL definition Defines WS interface and types e.g. SampleWebService.wsdl AXISWSDL2Java(or similar) Run by ant …_generate tasks Server deploymentinformation(WSDD) e.g. Record.java, SamplePortType.java, … DeterminesJava/SOAP mapping etc. deploy.wsdd,undeploy.wsdd Generates Serverskeletonand types Clientstuband types Implements interface Uses Serverimplementationsource Clientsource e.g. SimpleClient.java e.g. SampleSoapLiteralBindingImpl.java

22. Development components:Java (server)-driven Generates(by reflection) Serverimplementationsource (.jws) AXISwebapp WSDL definition Hostedby e.g. SampleServer2.jws e.g. SampleServer2.wsdl AXISWSDL2Java(or similar) Generates Clientstuband types Clientsource Uses e.g. SimpleClient2.java

23. Additional notes • SAAJ client does not use WSDL-defined stubs • Uses SAAJ API directly, “hand”-building XML input