|
|||||||||||||||||||||||||||||||||||||||||||||||||
|
Server-Side SOAP 4. Writing and Deploying your own Services This section walks you through the steps you are required to take to write and deploy your own web services using Tomcat and Apache SOAP for Java. The basic idea here is that we will be developing and running the service within a Java IDE (rather than starting tomcat at the command line and using precompiled class files). The greatest benefit of this is that you can debug the services with your IDE's debugger as they are being invoked. You can use the IDE of your choice. It is presumed only that you are quite familiar with how to use and configure it. These instructions can be applied to both Win32 and UNIX operating systems. The service we will be writing as an example is the Quotation Database service (which, notably, is the same as the service that is implemented and available online in the Demo Section). It is basically a service that gives you access to a list of quotations categorised by author's name. The database of quotations is persistent across shutdowns of the appserver so the data (while in memory at runtime) is stored in an xml file that is updated on a regular basis. As for service methods, things are fairly simple: you can get a full list of quotations, get a list of quotations by author, or you can submit a quotation to the database. Here are the three service method signatures: Quotation[] getAllQuotations ( ); String[] getQuotationsByAuthor ( String author ); void submitQuotation ( String author, String text ); Where the user-defined type Quotation is defined as: Quotation { String author; String text; }
The java source files for the Quotation Database service are available for you in the soapuser-1.0 archive: For Win32 : soapuser-1.0.zipSave the file to your machine and unpack it to the soap directory (ie. C:\soap under Win32 or /home/me/soap under Unix). Everything will be contained in a subdirectory called soapuser-1.0. In particular the quotation service java source files will be under soapuser-1.0\src in a directory structure that complies with the package name (ie. com\soapuser\soap\server\quotation). Along with the java source files there are also some xml files and some java client source files which are explained in detail further down on this page. To develop using the example source files take the following steps (note that the root level directory "soap" in the following instructions is is C:\soap on Win32 and /home/me/soap on UNIX):
Things to ensure when developing your own classes:
Alongside the java source files for the Quotation Database service is the corresponding deployment descriptor (DeploymentDescriptor.xml). If you are developing your own service classes then note the sections shown in green below - these are where you will potentially need to make changes. Explanatory notes follow.
Respective explanatory notes:
You already made the Tomcat jars available to your project in step nine. To startup Tomcat is then simply a matter of setting your project's main class to be org.apache.tomcat.startup.Tomcat and specifying the application parameters. The only application parameter you are required to specify is the Tomcat home directory from which the appserver will find its way to its configuration information (Tomcat looks for configuration information in %TOMCAT_HOME%/conf/server.xml). To do this, set the application parameters to the following: Win32 -home C:\soap\jakarta-tomcat-3.2.x UNIX -home /home/me/soap/jakarta-tomcat-3.2.x Now, before we go on, let's revisit the logic behind the third java source file, namely QuotationDBInitServlet.java as it has repercussions on the Tomcat configuration. As mentioned in step nine, this is a very simple servlet that will be used to pass parameters to the implementing class (QuotationDB). The parameters pertain to the database file that gives us persistency across shutdowns of the appserver. The basic idea is that we create a servlet which is loaded at Tomcat startup time and whose sole purpose in life is to read the QuotationDB parameters and store them in memory. At some time later when the QuotationDB is instantiated it will ask the QuotationDBInitServlet for the parameters. There are only two: a fully qualified filename for the database file and the interval time for flushing the database to disk. Once the QuotationDB constructor has the parameters it shall, if the database file exists, construct the database in memory from the contents of the file. It will also launch a thread that wakes up from time to time according to the flush interval and dumps the database to disk. The handy part about using a servlet to read the parameters for us is that we can make use of the servlet parameter framework already in place for servlets. To make Tomcat aware of the new servlet we have to declare it as a webapp in the server.xml configuration file. Add the following context information (in bold) at the end of the server.xml config file which can be found in soap\jakarta-tomcat-3.2.x\conf (again, the root directory "soap" as mentioned here is C:\soap on Win32 and /home/me/soap on UNIX). Note that the webapp configuration file is soap\soapuser-1.0\src\com\soapuser\soap\server\quotation\web-inf\web.xml and is declared via the docBase attribute (Tomcat will expect it under the web-inf subdirectory of the docBase). It is this file that declares the class that implements the servlet (QuotationDBInitServlet) and that holds the values for the QuotationDB parameters.
Important: You may also need to update the quotation database fully qualified path name in the web.xml configuration file (soap\soapuser-1.0\src\com\soapuser\soap\server\quotation\web-inf\web.xml) to match your actual soap directory (UNIX developers will definitely need to do this unless they actually have set up the user 'me'!). As delivered, the value is as follows. If the directory as shown here exists you do not need to change anything. Do not concern yourself with ensuring that the file quotationdb.xml exists - it will be created by the service at the appropriate time. Win32 <param-value>C:\soap\soapuser-1.0\quotationdb.xml</param-value> UNIX <param-value>/home/me/soap/soapuser-1.0/quotationdb.xml</param-value> You can now startup Tomcat within the IDE. First ensure that any Tomcat server that you started via the command line when going though the previous sections has been shutdown (so that we free up port 8080) and then start Tomcat from within the IDE by running the main class as configured above. You should get output similar to the following - notice the new context (aka webapp) called quotation. 2001-07-24 01:18:15 - ContextManager: Adding context Ctx( /examples ) Starting tomcat. Check logs/tomcat.log for error messages 2001-07-24 01:18:15 - ContextManager: Adding context Ctx( /admin ) 2001-07-24 01:18:15 - ContextManager: Adding context Ctx( /quotation ) 2001-07-24 01:18:15 - ContextManager: Adding context Ctx( ) 2001-07-24 01:18:15 - ContextManager: Adding context Ctx( /test ) 2001-07-24 01:18:15 - ContextManager: Adding context Ctx( /soap ) 2001-07-24 01:18:20 - PoolTcpConnector: Starting HttpConnectionHandler on 8080 2001-07-24 01:18:20 - PoolTcpConnector: Starting Ajp12ConnectionHandler on 8007 Note that as the Tomcat server is running within the IDE you can run it in debug mode and put
breakpoints in the service code. If you download the source code for SOAP and Tomcat from
Apache you can even debug all the way through those levels as well (to do that you will need
to add the SOAP and Tomcat source files to your project's source path, remove the corresponding
jars from the required librearies and recompile). As a further aid to debugging you can run the
TCP/IP Tunnel GUI (as specified in the previous sections) to see the SOAP dialogue as it is
happening.
Once Tomcat has completed its startup run the deployer script (as developed in step seven), giving the quotation service deployment descriptor's filename as a parameter, like this (note that the line breaks are only for display purposes - type the whole command on a single line): Win32 > mydeployer.bat C:\soap\soapuser-1.0\src\com\soapuser\soap\server\quotation\DeploymentDescriptor.xml UNIX > mydeployer.sh /home/me/soap/soapuser-1.0/src/com/soapuser/soap/server/quotation/DeploymentDescriptor.xmlJust as before, if there was no error it means the service was deployed successfully. You should be able to see it listed as urn:QuotationService on the SOAP admin page http://localhost:8080/soap/admin/index.html.
Included in the soapuser-1.0.zip archive are a few java source files for some simple SOAP clients to the quotation service. Whereas our server-side code was in com\soapuser\soap\server\quotation the client-side source files are under com\soapuser\soap\client\quotation. Create a new project with same source path and libraries (attention pedants, technically this time you will not need the Tomcat jars), add the three java source files and compile the project. Running GetAllQuotations (specifying only your SOAP server URL as an application parameter) should result in a list comprised of the two default quotations (one by Winston Churchill and another by Oscar Wilde). You can add a third quotation by running SubmitQuotation (specifying the URL, the author and the text as parameters). Running GetAllQuotations again should result in a list of quotations including the new one. You can test the getQuotationsByAuthor service method by running GetQuotationsByAuthor (specifying the URL and the author as parameters). Below is one way to run these clients (you will probably need to alter the classpath entry shown
in bold so that it corresponds to the place where your class files are created). Note that the arrow
(
You should now also see that a file called quotationdb.xml has been created in the soapuser-1.0 directory and that this file is being updated every 30 minutes. Note that the filename (including the path) and the interval can be configured by altering the web.xml file in soapuser-1.0\src\com\soapuser\soap\server\quotation\web-inf but you will have to bounce your Tomcat server before any change is taken into account. Check that the database is being persisted correctly by taking a look at the contents of the file (noting that it can be out of sync with what is in memory if you have submitted new quotations since the last flush). One final test is to shutdown and restart Tomcat to check if your submitted quotations were persisted and picked back up at restart. To test this simply bounce the Tomcat server and run GetAllQuotations again.
That winds things up for the server-side tutorial. Now that you have a Tomcat server running and the quotation service deployed you are ready to see how the service can be exploited using a variety of client-side technologies. To get started, go to the section on Client-Side SOAP. [ Nicholas Quaine ] Copyright © 2001-2007 Nicholas Quaine. All rights reserved. |