AS-75.3600 Semantic Web-services

Course assignment instructions

Tuukka Ruotsalo ja Eetu Mäkelä

General instructions

Read these instructions fully before doing anything else.
Register for these demonstration sessions using TOPI. The sessions take place at the AS computing room on thursdays 12-14 and 14-16.
The course work is expected to be done individually, but students are encouraged to discuss it and aid each other. However, everyone must be able to demonstrate and explain the solutions they have applied.
It is both possible and recommended to advance the course work on your own time.
The idea of the demonstrations sessions is to advice students on the course work. However, you probably must use extra time (in addition to these demonstration sessions) to get the course work done.

Syntax: markup [] that occurs in this document means that you have to put something related to you own file structure etc. in place of this markup.

Environment

Tomcat and Axis software have been installed to each AS-computing class computer. These are used locally. Scripts to start and shutdown Tomcat can be found from startup-menu.

The windows server environment contains a folder \\win.hut.fi\gen\courses\AS\75\3600. This folder has a subfolder "general", that contains scripts and examples created for you to make the course work easier. The subfolder "students" can be used to share files between the students if necessary.

To be able to use the scripts in the general subdirectory, you must run command \\win.hut.fi\gen\courses\AS\75\3600\general\SetupAxis.bat in the Windows command prompt.

After running this script you should be able to use the commands wsdl2java, java2wsdl, adminclient and tcpmon.

When running the commands some WARN messages may occur. If these are related to lo4j, mail or xmlsec you don't have to pay attention on the warnings. In general, only if ERROR messages occurs you should get worried.

Whenever you log on the computer, do the following: 1. Close tomcat if it is running (Start menu) 2. Replace original axis-setup (Start menu) This is because some other student might have been using the computer and axis setup and you need to "clean up the table" first.

Examples and Support Material

Example Web Service project
Example WS client project
Example client for the Amazon web services

Wiki-page for those doing the exercise work at home on how to make the command line tools work the way they are described here.

Two basic functions

This chapter explains two common functions that you will be using in our Web Services -environment.

Function 1: Publishing your own web service

Design and implement JavaBeans to support a datamodel for the service
Design and implement a service interface
Compile classes (javac *.java)
Compile service classes and create a jar-archive. (jar cvf sws-example-server.jar bin/*)
Copy the jar-file to folder c:\programs\axis\webapps\axis\WEB-INF\lib. This makes the classes available for Tomcat and Axis service
Restart tomcat (start menu)
Create deploy.wsdd by refactoring an example file that can be found from \\win.hut.fi\gen\courses\AS\75\3600\general\sws-example-server.
Run command adminclient deploy.wsdd
Check that your service can be accessed by listing the available services in address (http://localhost:8080/)

Running example

Make sure that the scripts work properly: run on command line \\win.hut.fi\gen\courses\AS\75\3600\general\SetupAxis.bat

cd z:\[folder]\sws-example-server\src\fi\seco\courses\sws\example

javac *.java

cd z:\[folder]\sws-example-server\src

jar cvf sws-example-server.jar . (<- note the dot)

copy sws-example-server.jar c:\programs\axis\webapps\axis\WEB-INF\lib

restart tomcat

Done for you

adminclient z:\[hakemisto]\sws-example-server\deploy.wsdd

start browser at http://localhost:8080/axis/servlet/AxisServlet

Function 2: Using a web service

Go to project root source folder [src]
Run command wsdl2java -p [packagename, e.g. fi.seco.courses.sws.example.gen] [wsdl network address, e.e. http://localhost:8080/axis/services/CurrencyExchangeService?wsdl
Program a client that uses the service. Examples can be found from folder: \\win.hut.fi\gen\courses\AS\75\3600\general\sws-example-client and \\win.hut.fi\gen\courses\AS\75\3600\general\sws-example-amazon-client.
Compile client (e.g. javac -cp %AXISCP% *.java gen/*.java)
Run and test the client (java -cp %AXISCP% fi.seco.courses.sws.example.TestCurrencyExchangeRateService)

Running example

Make sure that the scripts work. Run on command line: \\win.hut.fi\gen\courses\AS\75\3600\general\SetupAxis.bat

cd z:\[hakemisto]\sws-example-client\src

wsdl2java -p fi.seco.courses.sws.example.gen http://localhost:8080/axis/services/CurrencyExchangeService?wsdl

cd fi\seco\courses\sws\example

javac -cp %AXISCP% *.java gen\*.java

cd z:\[folder]\sws-example-client\src

java -cp %AXISCP% fi.seco.courses.sws.example.TestCurrencyExchangeRateService

Function 3.

Detecting Web Servicen SOAP-traffic

run command tcpmon

Fill in Host (The address of the web service)

Fill in Port (Port of the web service)

Fill in Listen Port (some port e.g. 8888)

Run client locator using address that is visible in tcpmon (change locator.get[SomeService]() to locator.get[SomeService](new URL("[urli]")); and add imports and throws-code) This results to a service that goes through monitor (tcpmon).

Running example

Run new cmd.exe from start menu

Run on command line \\win.hut.fi\gen\courses\AS\75\3600\general\SetupAxis.bat

Run command tcpmon

Open listener with parameters Listen Port = 8888, Target hostname = soap.amazon.com and Target port = 80

Change client in a way that locator sends the messages through tcpmon: service = locator.getAmazonSearchPort(new URL("http://localhost:8888/onca/soap2"));> (In addition change java code: "throws ServiceException, RemoteException" to "throws ServiceException, RemoteException, MalformedURLException" and add import-clause "import java.net.URL;" and "import java.net.MalformedURLException".

Compile client

Tick tcpmon XML Format on and run client code. Now you are able to visualise SOAP-messages.

Coursework

The students will design and implement bookretailer service that connects to Amazon.com bookshop using web services. The retailer service will use payment service that is external from the retailer service. Students will design and implement the payment service. Students will a?so program a client that uses the retailer service.

1. Session

Getting familiar with the environment
Deploy and run ready made service within the environment
Test Amazon.com search service with test client

Detailed instructions

Install example web service (copy to your local disk from \\win.hut.fi\gen\courses\AS\75\3600\general\sws-example-server) to local Tomcat

Copy folder \\win.hut.fi\gen\courses\AS\75\3600\general\sws-example-client to your local disk. Create client code from the service that you installed to folder src using command wsdl2java. Call service running a client.

Copy folder \\win.hut.fi\gen\courses\AS\75\3600\general\sws-example-amazon-client to your local filesystem. Create client code to folder src using command "wsdl2java -p fi.seco.courses.sws.example.gen http://soap.amazon.com/schemas2/AmazonWebServices.wsdl". Call the service running a client.

2. Session

Design workflow / actionflow between the services as discussed on the lectures. In addition design datamodel and beans used to transfer the information required in according to actionflow.

Tip: Pay attention on which actors communicate with each other, what messages should be changed and what information is required in each message so that the following process parts have enough information to act. As shown on the lectures, there are multiple choices for actionflow.

To pass the coursework, your application should contain at least: information about the books, information about the order and information about the invoice. In addition you should have at least three services: retailer service, payment service and amazon.com service.

Information about the book should contain at least: name of the book. Price of the book. Order and invoice should contain at least total price and information abou the person ordering.

Design the datamodel using some suitable method, such as UML. Draw also a sequence diagram or similar to make clear the action flow and data structures changed within the flow. Remember the tips given on lecture about Java Beans specification, Handling lists and Serializable interface.

Design service interfaces. Think about what interfaces and methods you need to provide the required services. Remember that the services you create are typically distributed and owned by different stakeholders. This is why they should be as much independent of each other as possible. They should also have their own data models (as they would in real life use case). Remember that you can not have session information in server side. This implies that you have to send all the required information in the datastructures.

You don't have to take care of transactions or security issues. However, you should design the service in a such way that this would be possible if required.

Summary: Before implementing anything, design: (1) data structures, (2) service interfaces, (3) communication model (action flow).

3. Session

Fix the plan based on possible instructions by the assistants. As soon as your plan is sufficient you can start to implement the service.