Introduction

This is a quick-start guide, aimed to get you going with InstantSoap. Before you begin this, you should ensure that you have been through the requirements documentation. When you have completed this guide, you will have deployed an InstantSoap WAR into Tomcat, interacted with it using its web interface, and also developed your first Java client to an InstantSOAP service.

Deploying the Echotest WAR

Before you start this section, you must have an internet connection, and a running Tomcat installation. When you have completed this section, you will have deployed the echotest example WAR and checked that it is running correctly.

1. Download instantsoap-ws-echotest-1.0.war and save to a convenient place on your local computer, for example, your desktop.
2. Open a web browser, and navigate to your Tomcat instance . This should display the Tomcat welcome page. If it is not then you may wish to refer to the Tomcat FAQ . We find that the content of the most recent $TOMCAT/logs/localhost file is often helpful in tracking down problems.
3. Follow the link to the left for 'Tomcat Manager'. The first time you do this, it will ask you for a username and password. You must enter details of a Tomcat account with 'manager' privilages, as described in requirements . The manager page allows you to check on the status of web applications, and manage them by starting, stopping, installing and uninstalling them.
4. Scroll down towards the bottom of the page. There will be a section called 'Deploy' with two sections, one for server-side deployment, the other for client-side deployment labelled 'WAR file to deploy'. In the 'Select WAR file to upload' box, sellect the instantsoap-ws-echotest-1.0.war file you downloaded earlier. Click on 'Deploy'.
5. The manager will refresh. If all has gone well, then a new web application will be listed in the 'Applications' table. If not, then the 'Message' area above that should give you some idea what has gone wrong.
6. Check that the application is running--the "running" column in the applications table should say "true"; if it is not, then you should check the tomcat logs to find out why. The most usual reason for these services to fail to start is for Tomcat to be running on an incompattible version of Java. This will result in the logs containing messages about trusted libraries.
7. Lastly, click on the instantsoap-ws-echotest-1.0.war in the applications list. This will take you to the front page of InstantSoap, described in the next section. If the page fails to load, or the URL does not resolve, then most likely the web application has failed to enter the running state. See above .

At this point, you should have instantsoap-ws-echotest deployed and running on your system. You may now either proceeed to the next section where we will ensure that the example services are working, by using the web interface, or skip on to writing a programmatic client.

Using the Management Interface

InstantSoap provides a Web interface for accessing and managing deployed applications in a running installation. We will use this to check that your installation is behaving as expected, and to mount the common bioinformatics BLAST application.

Before you start this section, you should ensure that you have a working deployment of instantsoap-ws-echotest.war as described in Deploying the Echotest WAR . When you have worked through this section, you should be able to use the web interface to manage InstantSoap.

1. Ensure that the deployed instantsoap-ws-echotest.war web application is running in Tomcat. Open up the application front page in your browser as described in the last step of the previous section.
2. There is a table near the top of the page labelled 'Applications'. This should contain four entries called 'echoMap', 'echoBook', 'stringEcho' and 'cat'. Each of these have a name, a description and one or more actions.
3. Click on the 'Run' action of 'echoBook'. This will bring up a new page, with the description of the application and a form that lets you fill in each of the parameters the application expects.
4. Fill out the book title, author name and number of pages. If you need an example, "Markov Chains" was written by J.R. Morris, and is 237 pages long.
5. Click 'Execute echoBook'. This will take you to a results page. This contains a table with two columns. The first column names the outputs. The seccond gives the values of these. Because this application simply coppies the inputs to the outputs, the table will contain the values you typed into the input form.
6. Try running the echoMap and stringEcho applications in a similar way. These test the different service provider strategies, and service deployment methods, which are described elsewhere .
7. Next try running the 'cat' application. It provides the same functionality as stringEcho does, however it is implemented using the a command-line application; in this case, cat echos its input; if you are running on Windows, this probably won't work as cat is not standard. You should be able to diagnose this by looking at the Tomcat logs
8. Click on the 'Fetch XML' action for 'cat'. This will open up the XML configuration that makes the command-line cat application available to InstantSoap. This is discussed in more detail in another guide . For now, make sure that you save this XML into an easily accessible local file. For example, onto your desktop as 'cat.xml '.
9. You can remove ("undeploy") the cat application by clicking on 'Unload application'. This will remove cat from the server, and refresh the page to display the new applications list.
10. You can now re-load the cat application by pasting the content of cat.xml into the 'Upload a new command-line application profile' text area. Click on 'Upload Application' to upload that XML. When you do this, the page will refresh, and cat will appear again in the list of applications.

By now, you will have exercised much of the code that InstantSoap relies upon. You have invoked applications through the web form, and added and removed command-line applications from the InstantSoap service.