Beruflich Dokumente
Kultur Dokumente
pintux@pintux.it
1 2
4 5 6
Introduction ................................................................................................................................................... 2 Web Services with JWSDP........................................................................................................................... 2 2.1 Requirements......................................................................................................................................... 2 2.1.1 JWSDP............................................................................................................................................... 2 2.1.2 Apache Tomcat and JWSDP......................................................................................................... 2 2.1.3 Apache Ant ....................................................................................................................................... 3 2.2 Building a Web Service (Server) from a Java class........................................................................... 4 2.3 Building a Web Service (Server) from a WSDL file ........................................................................ 6 2.4 Building a Web Service Client from WSDL file .............................................................................. 9 Web Services with Axis............................................................................................................................... 11 3.1 Requirements....................................................................................................................................... 11 3.2 A little note about .jws....................................................................................................................... 11 3.3 Writing a Web Service with Axis...................................................................................................... 12 3.4 Web Service Interface definition...................................................................................................... 12 3.5 Web Service Generation.................................................................................................................... 13 3.6 Writing the web service implementation......................................................................................... 13 3.7 Deploying the web service ................................................................................................................ 14 3.8 Testing the service .............................................................................................................................. 14 Conclusion.................................................................................................................................................... 15 License........................................................................................................................................................... 15 APPENDIX A: Ant build files and Configuration files ........................................................................ 15 6.1 build.properties ................................................................................................................................... 15 6.2 build-ws-client.xml ............................................................................................................................. 15 6.3 build-ws-server.xml ............................................................................................................................ 16 6.4 wscompile-config.xml ........................................................................................................................ 17
pintux@pintux.it
1 Introduction
This short tutorial shows how to build web services using two popular frameworks for web service development with the Java platform: Java Web Services Developer Pack provided by Sun Axis from Apache
The chosen container for all deployment tasks is Apache Tomcat for both frameworks. In some steps of this tutorial (in particular for JWSDP) Ive used Apache Ant tool in order to automate the generation process for clients; reading the build file you can understand how to use tools by hand. Ant build files and the other configuration files are reported in APPENDIX A: Ant build files and Configuration files.
2.1.1 JWSDP
Download and install Java Web Services Developer Pack 1.6. Set an environment variable JWSDP_HOME with value equals to the installation directory.
pintux@pintux.it
FastInfoset.jar jaas.jar jaxb-api.jar jaxb-impl.jar jaxb-libs.jar jaxb-xjc.jar jaxp-api.jar jax-qname.jar jaxrpc-api.jar jaxrpc-impl.jar jaxrpc-spi.jar jsr173_api.jar jta-spec1_0_1.jar mail.jar namespace.jar relaxngDatatype.jar saaj-api.jar saaj-impl.jar sjsxp.jar xercesImpl.jar xmlsec.jar xsdlib.jar If you install the version for JWSDP (available on http://java.sun.com/webservices/containers/tomcat_for_JWSDP_1_5.html) the container is already configured and all libraries are installed. In both cases then set the TOMCAT_HOME environment variable with the installation directory as value.
pintux@pintux.it
Pay attention to the extension of Remote interface. The interface describes an adder service which exposes two remote methods (two operations), the first adds two integers and returns the result, the second returns a String representing the service version. Save it in the <src> directory. Now, write the service implementation:
package px.ws; public class AdderWebServiceImpl implements AdderWebService { public AdderWebServiceImpl() { } public String getVersion() throws java.rmi.RemoteException { return "Adder Web Service - vers. 1.0"; } public int add(int x, int y) throws java.rmi.RemoteException { return x+y; }
pintux@pintux.it
In order to prepare a deployment package we have to create appropriate directories tree to contain all generated files: Into the <web> directory create the following directories: <web>/WEB-INF <web>/WEB-INF/classes For deployment task well use the wsdeploy tool provided by JWSDP, so we have to write a configuration file for it. Create an xml file called jaxrpc-ri.xml which defines the Web Service.
<?xml version="1.0" encoding="UTF-8"?> <!-- configuration file for JWSDP wsdeploy tool --> <webServices xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/dd" version="1.0" targetNamespaceBase="http://px.pxserver.org/op/msg" typeNamespaceBase="http:// px.pxserver.org /typeNamespaceBase/type"> <!-- the endpoint name becomes the service name in the WSDL --> <endpoint name="AdderWebService" interface="px.ws.AdderWebService" implementation=" px.ws.AdderWebServiceImpl"/> <endpointMapping endpointName="AdderWebService" urlPattern="/Adder"/> </webServices>
Save it in the <web>/WEB-INF directory Create a web.xml file, and save it in the <web>/WEB-INF directory, with the following content: <?xml version="1.0" encoding="UTF-8"?> <web-app> <display-name>AdderWebService</display-name> <description>A simple Adder web service</description> <session-config> <session-timeout>60</session-timeout> </session-config> </web-app> Create a <bin> folder in the <root> directory. Compile all .java files in the <bin> directory: javac d <bin> <src>\px\ws\*.java Copy content under <bin> folder into the <web>/WEB-INF/classes directory; Now, the directories tree created in <web> is ready to be packaged, so were going to create a war file: jar cvf adder-tmp.war C <web>\ .
pintux@pintux.it
In this way we have a deployment package ready to be processed by the wsdeploy tool of JWSDP, use it to obtain a final deployment package for our web service:
%JWSDP_HOME%\jaxrpc\bin\wsdeploy verbose o adder.war adder-tmp.war
The adder.war archive file is ready to be deployed on Tomcat. Simply copy it to the %TOMCAT_HOME%/webapps directory and it will be automatically deployed. Test the web service, for example requesting the WSDL file, opening a browser to URL: http://localhost:8080/adder/Adder?WSDL
pintux@pintux.it
In this way weve generated a Service Endpoint Interface (SEI), Tie class etc Its name is related to WSDL file definition. We assume it is called MyWebService_PortType, this interface exposes all web service operations. Now we have to write an implementation class for that interface. 7. In the generated package under <src> write an implementation class, i.e.
package mypackage.package; public class MyWebService_PortTypeImpl implements MyWebService_PortType { //methods implementation ... }
8. Create a <bin> directory under <root> and build all files including in the classpath the following libraries:
javac cp %JWSDP_HOME%\jaxrpc\lib\jaxrpc-api.jar; %JWSDP_HOME%\jaxrpc\lib\jaxrpc-spi.jar; %JWSDP_HOME%\jaxrpc\lib\jaxrpc-impl.jar; %JWSDP_HOME%\jwsdp-shared\lib\jax-qname.jar; %JWSDP_HOME%\jwsdp-shared\lib\activation.jar; %JWSDP_HOME%\jwsdp-shared\lib\mail.jar; %JWSDP_HOME%\saaj\lib\saaj-impl.jar; %JWSDP_HOME%\saaj\lib\saaj-api.jar; %JWSDP_HOME%\jaxp\lib\endorsed\xercesImpl.jar; %JWSDP_HOME%\jaxp\lib\endorsed\dom.jar; d <bin> <src>\mypackage\package\*.java Now, were ready to create a deployment package directories tree. Into the <web> directory create the following directories: <web>/WEB-INF <web>/WEB-INF/classes 9. Copy the WSDL file under <web>/WEB-INF directory 10. Copy the content of <bin> directory under <web>/WEB-INF/classes directory 11. In the <web>/WEB-INF directory create a jaxrpc-ri-runtime.xml file and a web.xml file, these are deployment files for Tomcat and they have the following content:
pintux@pintux.it
For jaxrpc-ri-runtime.xml <?xml version="1.0" encoding="UTF-8"?> <endpoints xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/runtime" version="1.0"> <endpoint name="MyWebService" interface="mypackage.package.MyWebService_PortType" implementation="mypackage.package.MyWebService_PortTypeImpl" tie=" mypackage.package.MyWebService_PortType_Tie" wsdl="/WEB-INF/mywebservice.wsdl" service="{http://www.myserver.it/operation/message/mws}MyWebService" port="{http://www.myserver.it/operation/message/mws}MyWebServicePortTypePort" urlpattern="/adder"/> </endpoints> For web.xml: <?xml version="1.0" encoding="UTF-8"?> <web-app> <display-name>MyWebService</display-name> <description>A simple web service</description> <listener> <listener-class>com.sun.xml.rpc.server.http.JAXRPCContextListener</listener-class> </listener> <servlet> <servlet-name>MyWebService</servlet-name> <servlet-class>com.sun.xml.rpc.server.http.JAXRPCServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>MyWebService</servlet-name> <url-pattern>/mywebservice</url-pattern> </servlet-mapping> <session-config> <session-timeout>60</session-timeout> </session-config> </web-app> 12. Create the deployment package using the comand:
jar cvf mywebservice.war C <web>\ .
The mywebservice.war archive file is, now, ready to be deployed on Tomcat. Simply copy it to the %TOMCAT_HOME%/webapps directory and it will be automatically deployed. Test the web service, for example requesting the WSDL file, opening a browser to URL: http://localhost:8080/mywebservice/mywebservice?WSDL
pintux@pintux.it
This step creates a <src> directory, a <gen> directory and puts into them the generated stub and classes needed for web service client calls implementation. Notice that the package created is the one specified in the wscompile-config.xml file. 8. Write a web Service client, for example for the Adder Web Service, a simple client could be
package px.ws.client.stub; public class AdderClient {
pintux@pintux.it
public static void main(String[] args) { //instantiates the loader factory AdderWebService_Service service = new AdderWebService_Service_Impl(); AdderWebService_PortType port=null; //declares the Web Service Stub Interface try { //instantiates the Web Service Stub port = service.getAdderWebServicePort(); ((AdderWebService_PortType_Stub)port)._setProperty(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, "http://myserver.it:8080/adder/Adder"); //Sets the Web Service endpoint URL
} catch(javax.xml.rpc.ServiceException e) { e.printStackTrace(System.err); } try { String ver = port.getVersion(); // web service operation call System.out.println("Adder version is " + ver); int sum = port.add(2, 3); // web service operation call System.out.println("Sum = " + sum);
} catch(Exception e) { e.printStackTrace(); } }
9. Build all files (by command line or using an IDE) including in the classpath the following libraries: %JWSDP_HOME%\jaxrpc\lib\jaxrpc-api.jar; %JWSDP_HOME%\jaxrpc\lib\jaxrpc-spi.jar; %JWSDP_HOME%\jaxrpc\lib\jaxrpc-impl.jar; %JWSDP_HOME%\jwsdp-shared\lib\jax-qname.jar; %JWSDP_HOME%\jwsdp-shared\lib\activation.jar; %JWSDP_HOME%\jwsdp-shared\lib\mail.jar; 10
pintux@pintux.it
%JWSDP_HOME%\saaj\lib\saaj-impl.jar; %JWSDP_HOME%\saaj\lib\saaj-api.jar; %JWSDP_HOME%\jaxp\lib\endorsed\xercesImpl.jar; %JWSDP_HOME%\jaxp\lib\endorsed\dom.jar; 10. Run your client setting the classpath as shown in the previous step.
11
pintux@pintux.it
Now: 1. copy the Adder.java file into the %TOMCAT_HOME%/webapps/axis directory 2. rename the copied file from Adder.java to Adder.jws 3. Test the web service putting in a browser the URL: http://localhost:8080/axis/Adder.jws?wsdl for WSDL visualization, and: http://localhost:8080/axis/Adder.jws?method=getVersion to test a method call. JWS feature is nice but too simple for production quality web services. For example, you cannot use packages in the pages, and as the code is compiled at run time you can not find out about errors until after deployment. Production quality web services should use Java classes with custom deployment, as recommended by Apache: JWS files are great quick ways to get your classes out there as Web Services, but they're not always the best choice. For one thing, you need the source code - there might be times when you want to expose a pre-existing class on your system without source. Also, the amount of configuration you can do as to how the service gets accessed is pretty limited - you can't specify custom type mappings, or control which Handlers get invoked when people are using your service. (Note for the future : the Axis team, and the Java SOAP community at large, are thinking about ways to be able to embed this sort of metadata into your source files if desired - stay tuned!)
12
pintux@pintux.it
Save it under the directory <root>/px/axws. The following list shows what we have to do now: 1. 2. generate the WSDL from Java interface generate skeleton, stub, serializers, deployment descriptors and so on, from WSDL file
Running the previous script we generate the WSDL and all required stub and serializers. What we have to do now is to write a service implementation.
Now compile all generated classes (notice the AXIS_HOME variable, it must point to the Axis installation directory):
set AXIS_HOME=C:\devtools\axis-1_3 set AXIS_LIB=%AXIS_HOME%\lib
13
pintux@pintux.it
Save it in the <root> directory and run it. If all is ok, the web service is deployed.
pintux@pintux.it
in this way you should get the SOAP document with the web service response.
4 Conclusion
This short how-to aims to show a way to start coding Web Services in Java using two popular frameworks: Sun JWSDP and Apache Axis deploying services on Tomcat web container. The document covers some issues discovered in developing web services and for each of them a sample is provided. In the sections related to JWSDP, Ant build tool is used; all configuration and build files are reported in APPENDIX A.
5 License
This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/2.5/ or send a letter to Creative Commons, 543 Howard Street, 5th Floor, San Francisco, California, 94105, USA.
6.1 build.properties
This file is to be customized with the real JWSDP installation directory used.
test=Properties are OK jwsdp-home=<jwsdp-install-directory> wsdl=wscompile-config.xml
6.2 build-ws-client.xml
<?xml version="1.0"?> <!-- Ant build for WebService development with JWSDP --> <!-- author: Antonio Pintus --> <project name="WebServiceClientGenerator" default="copy-files" basedir="."> <property name="src" value="src"/> <property name="gen" value="gen"/> <target name="info"> <echo message="Web Service client stub and classes generator from WSDL "/> <echo message="px v. 1.0 "/> <splash/> </target>
15
pintux@pintux.it
<target name="init" depends="info"> <mkdir dir="${gen}"/> <mkdir dir="${src}"/> <echo message="">${test}</echo> </target> <target name="generate" depends="init"> <!-- Generates java code from WSDL file--> <echo message="Running wscompile...."/> <exec dir="." executable="${jwsdp-home}\jaxrpc\bin\wscompile.bat" output="gen-log.txt"> <arg line="-d"/> <arg line="${gen}"/> <arg line="-gen:client -keep"/> <arg line="${wsdl}"/> </exec> </target> <target name="copy-files" depends="generate"> <copy todir="${src}"> <fileset dir="${gen}"> </fileset> </copy> </target> </project>
6.3 build-ws-server.xml
<?xml version="1.0"?> <!-- Ant build for WebService development with JWSDP --> <!-- author: Antonio Pintus --> <project name="WebServiceServerGenerator" default="copy-files" basedir="."> <property name="src" value="src"/> <property name="gen" value="gen"/> <target name="info"> <echo message="Web Service server tie and classes generator from WSDL "/> <echo message="px v. 1.0 "/> <splash/> </target> <target name="init" depends="info"> <mkdir dir="${gen}"/> <mkdir dir="${src}"/> <echo message="">${test}</echo> </target> <target name="generate" depends="init"> <!-- Generates java code from WSDL file--> <echo message="Running wscompile...."/> <exec dir="." executable="${jwsdp-home}\jaxrpc\bin\wscompile.bat" output="gen-log.txt"> <arg line="-d"/> <arg line="${gen}"/> <arg line="-gen:server -keep"/>
16
pintux@pintux.it
<arg line="${wsdl}"/> </exec> </target> <target name="copy-files" depends="generate"> <copy todir="${src}"> <fileset dir="${gen}"> </fileset> </copy> </target> </project>
6.4 wscompile-config.xml
This file is intended to be an example and it has to be edited to be adapted to a particular web service.
<?xml version="1.0"?> <configuration xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config"> <!-- WSDL URL and generated package name --> <wsdl location="MyWebService.wsdl" packageName="org.mywebservice.stub"/> </configuration>
17