1. 1 G52IWS: Example Web-services Chris Greenhalgh

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

3. 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. 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. 5 Web Service client & server runtime components Client (Java) AXIS tcpmon (optional) Jetty (or other servlet container) - handles HTTP & TCP AXIS web application - handles SOAP & WSDL Server code (Java classes or JWS file) - handles application logic Server config (WSDD) SOAP over HTTP over TCP Stub classes (optional) SOAP (AXIS) client lib. ClientService/Server Browser (optional)

6. 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. 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. 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. 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. 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. 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. 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. 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/axis axis.home=C:/G52IWS/axis-1_4 … Compile the server and two clients ant all Deploy the servers to the Jetty-hosted axis webapp (while it is running!) ant deploy

14. 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. 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. 16 Testing the examples (3) Run the example clients from ant: ant test ant test2

17. 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. 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. 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. 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. 21 Development components: WSDL-driven WSDL definition AXIS WSDL2Java (or similar) Client stub and types Server skeleton and types Server deployment information (WSDD) Client source Server implementation source Generates Implements interface Uses Defines WS interface and types e.g. SampleWebService.wsdl Determines Java/SOAP mapping etc. deploy.wsdd, undeploy.wsdd e.g. SampleSoapLiteralBindingImpl.javae.g. SimpleClient.java e.g. Record.java, SamplePortType.java, … Run by ant …_generate tasks

22. 22 Development components: Java (server)-driven Server implementation source (.jws) AXIS webapp Hosted by WSDL definition Generates (by reflection) AXIS WSDL2Java (or similar) Client stub and types Client source Generates Uses e.g. SampleServer2.jws e.g. SampleServer2.wsdl e.g. SimpleClient2.java

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