Author: sam.griffith(a)jboss.com Date: 2007-01-11 10:39:18 -0500 (Thu, 11 Jan 2007) New Revision: 1933 Modified: trunk/jbossws-docs/online/tutorial-doc/en/master.xml trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/tutorial-1.xml trunk/jbossws-docs/online/tutorial-src/jax-ws-hello-world/build.xml trunk/jbossws-docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/HelloWorldWS.java Log: Modifications covering: Tutorial #1, Screenshots, build file changes, testing of web service and others. Modified: trunk/jbossws-docs/online/tutorial-doc/en/master.xml =================================================================== --- trunk/jbossws-docs/online/tutorial-doc/en/master.xml 2007-01-11 15:14:41 UTC (rev 1932) +++ trunk/jbossws-docs/online/tutorial-doc/en/master.xml 2007-01-11 15:39:18 UTC (rev 1933) @@ -19,8 +19,8 @@ <bookinfo> <title>JBossWS Tutorials</title> - <subtitle>jbossws-1.2.0.CR2</subtitle> - <releaseinfo>05-Jan-2007</releaseinfo> + <subtitle>jbossws-1.2.0.CR3</subtitle> + <releaseinfo>11-Jan-2007</releaseinfo> <releaseinfo> <ulink url="http://labs.jboss.com/jbossws/tutorials/en/html/index.html"... Pages]</ulink>, <ulink url="http://labs.jboss.com/jbossws/tutorials/en/html_single/index.ht... Page]</ulink>, Modified: trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/tutorial-1.xml =================================================================== --- trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/tutorial-1.xml 2007-01-11 15:14:41 UTC (rev 1932) +++ trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/tutorial-1.xml 2007-01-11 15:39:18 UTC (rev 1933) @@ -41,6 +41,7 @@ venerable "HelloWorld" known world over. </para> <programlisting> +<![CDATA[ package org.jboss.samples.helloworld; import javax.jws.WebService; @@ -55,6 +56,7 @@ return "Hello " + toWhom + "!" + " The date and time is: " + new java.util.Date(); } } +]]> </programlisting> <para> @@ -76,13 +78,343 @@ <title>ANT Build File</title> <para>We'll see these main things in this build file:</para> <itemizedlist> - <listitem>Libs needed</listitem> - <listitem>WSTool call to get WSDL</listitem> - <listitem>Packaging it up</listitem> + <listitem>The libs needed to build</listitem> + <listitem>How to get the WSDL file generated</listitem> + <listitem>Packaging and deploying</listitem> </itemizedlist> - + <para> + In the program listing below you can see that the library we need is: jbossws-client.jar. This file is in the jboss application server "client" directory. This jar provides all the needed classes for us to build our web service. + </para> + <para> + You can also see the task definition for the "wstools" helper class that calls out to the wstools command line application. The "wstools" application is used to generate WSDL's from Java code or to create Java code from WSDL's. In our case we are going to create a WSDL from the Java code above. The "wstool" call in our example takes two arguments. One being the "wstools" configuration file and one being where to put the generated output files. We'll see the "wstools" configuration file more in the next section. + </para> + <para> + The packaging of a web service is done in this example by putting it in a standard WAR file. For EJB's you can also package it in a EAR file. In this example we use a web.xml file to specify the web services url mapping. + <!-- I think also a SAR file, but need to check again. --> + </para> + <programlisting> +<![CDATA[ +<?xml version="1.0"?> +<!-- Build file for Hello World Web Service Example using new JBoss JAX-WS 2.0 Stack --> +<project name="JAX-WS 2.0 Hello World Web Service Buildfile" default="main" basedir="."> +<!-- Standard Properties --> + <property name="top.dir" value="${basedir}"/> + <property name="server.config" value="default"/> + <property name="src.dir" value="${top.dir}/src"/> + <property name="build.classes" value="${top.dir}/classes"/> + <property name="java.dir" value="${top.dir}/src/java"/> + <property name="resources.dir" value="${top.dir}/resources"/> + <property name="jboss.dir" value="/Users/sgriffith/jboss-5.0.0.Beta2"/> + <property name="jboss.client" value="${jboss.dir}/client"/> + <property name="jboss.lib" value="${jboss.dir}/lib"/> + <property name="jboss.server" value="${jboss.dir}/server/${server.config}"/> + <property name="jboss.server.lib" value="${jboss.server}/lib"/> + <property name="jboss.server.deploy" value="${jboss.server}/deploy"/> + +<!-- JDK Detection --> + <available classname="java.lang.Enum" property="HAVE_JDK_1.5"/> + +<!-- Check for new WS jar file --> + <available file="${jboss.client}/jbossws-client.jar" value="jbossws-client.jar" property="jbossws.client.jar"/> + +<!-- Path Definitions --> + <path id="client.classpath"> + <fileset dir="${jboss.client}"> + <include name="*.jar"/> + </fileset> + </path> + <path id="compile.classpath"> + <path refid="client.classpath"/> + <pathelement location="${jboss.server.lib}/jboss.jar"/> + </path> + +<!-- Targets --> + +<!-- Helper target --> + <target name="generate-sources" depends="" description="Generate the deployment resources and WSDL." if="HAVE_JDK_1.5"> + <!-- Define a taskdef for the wstools ant task --> + <echo message="Inside generate-sources"/> + <taskdef name="wstools" classname="org.jboss.ws.tools.ant.wstools"> + <classpath refid="client.classpath"/> + <classpath path="${top.dir}/classes"/> + <classpath path="${top.dir}"/> + </taskdef> + <echo message="wstools about to run"/> + <wstools dest="${top.dir}/META-INF" config="${resources.dir}/wstools-config.xml"/> + </target> + +<!-- Reset everything for a build from scratch --> + <target name="clean"> + <echo message="In clean"/> + <delete file="${top.dir}/helloworldws.war"/> + <delete dir="${build.classes}"/> + <delete dir="${top.dir}/META-INF"/> + </target> + +<!-- + Compile the java sources +--> +<!-- + Compile with jdk-1.5 as JAX-WS 2.0 needs annotations so we must use Java 5 or above. +--> + <target name="compile15" depends="" description="compile the sources" if="HAVE_JDK_1.5"> + <javac destdir="${build.classes}" classpathref="compile.classpath" debug="on"> + <src path="${java.dir}"/> + </javac> + </target> + + <target name="main" depends="compile15, generate-sources" if="jbossws.client.jar"> + <echo message="In main"/> + <mkdir dir="${build.classes}"/> + <war warfile="helloworldws.war" webxml="${src.dir}/metadata/web.xml"> + <classes dir="${top.dir}/classes"> + <include name="**/*.class"/> + </classes> + </war> + <!-- <antcall target="deploy"/> --> + </target> + +<!-- + Deployment targets +--> + <target name="deploy"> + <echo message="In deploy"/> + <copy file="${top.dir}/helloworldws.war" todir="${jboss.server.deploy}"/> + <delete file="${top.dir}/helloworldws.war"/> + </target> + + <target name="undeploy"> + <echo message="In undeploy"/> + <delete> + <fileset id="web_service_wars" dir="${jboss.server.deploy}" includes="*hello*.war"/> + </delete> + </target> + +</project> + +]]> + </programlisting> + + <para> + Since we use a WAR file we can specify the web services url mapping in the "web.xml" file just like you can for any web application. For this sample we've got the web service mapped to url path /HelloWorldWS. You'll see when we deploy the web service that this url path and the service name are important to the final url to the web service. + </para> + <programlisting> + <![CDATA[ +<?xml version="1.0"?> +<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> + <display-name>HelloWorldWS</display-name> + <servlet> + <display-name>HelloWorldWS</display-name> + <servlet-name>HelloWorldWS</servlet-name> + <servlet-class>org.jboss.samples.helloworld.HelloWorldWS</servlet-class> + </servlet> + <servlet-mapping> + <servlet-name>HelloWorldWS</servlet-name> + <url-pattern>/HelloWorldWS</url-pattern> + </servlet-mapping> + <session-config> + <session-timeout>30</session-timeout> + </session-config> +</web-app> + ]]> + </programlisting> </section> + + <section> + <title> + WSTools configuration file + </title> + <para> + The "wstools-config.xml" file is used by the "wstools" taskdef. The "wstools-config.xml" file contains the instructions about what we want "wstools" to do for us. In our example we are using "wstools" to generate the WSDL file for our sample web service. If we started with a WSDL, we could ask "wstools" to generate the Java source files for us as well. In this example though, we started with Java code so we only need to create the WSDL. The "java-wsdl" tag tells "wstools" that we want that WSDL generated for our service. In this example we tell "wstools" to use the file "HelloWorldWSEndpointInterface.java". The config file also tells "wstools" that we want our service to be know as "HellowWorldWS" and we want the SOAP invocation style to be "RPC". Finally, it also declares the target and type namespaces that the WSDL generated definitions should use. + </para> + <programlisting> + <![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> +<!-- +wstools -config wstools-config.xml +--> +<configuration xmlns="http://www.jboss.org/jbossws-tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.jboss.org/jbossws-tools http://www.jboss.org/jbossws-tools/schema/jbossws-tool_1_0.xsd"> + <global> + <package-namespace package="org.jboss.samples.helloworld" namespace="http://org.jboss.ws/samples/helloworld"/> + </global> + <java-wsdl> + <service name="HelloWorldWS" endpoint="org.jboss.samples.helloworld.HelloWorldWSEndpointInterface" style="rpc"/> + <namespaces target-namespace="http://org.jboss.ws/samples/helloworld" type-namespace="http://org.jboss.ws/samples/helloworld/types"/> + </java-wsdl> +</configuration> +]]> + </programlisting> + + <para> + One thing you might notice is that we have a separate endpoint interface class defined in addition to our real web service class. This seperation is not required in JAX-WS 2.0. You could just have the endpoint property reference the actual implementation class "HelloWorldWS.java". If you do just use the real implementing class, then you do not need a separate endpoint interface class. + </para> + <para> + Having a separated endpoint is particularly relevant to people upgrading from the older JAX-RPC web services architecture under JavaEE 1.4. It allows for them to stay with there older definitions, but still use the new features of JAX-WS 2.0 and migrate to using the new annotaions and web service features gradually. + </para> + <para> + If you do not have the separate interface class then the "wstools" looks at the annotations and other metadata about the java class that you've specified as the endpoint and comes up with reasonable defaults for all the needed WSDL values. For all new code you more than likely just need the real annotated class that implements the web service. For this example thought, we are going to stay with having a separate interface class. + </para> + + </section> + + <section> + <title> + Building our web service + </title> + <para> + To build the web service example do the following: + <itemizedlist> + <listitem>ant clean</listitem> + <listitem>ant</listitem> + <listitem>ant deploy</listitem> + </itemizedlist> + </para> + <para> + NOTE: In the current version of JBoss Application Server you have to manually deploy the "war" file created by the build, so do not do the "ant deploy" step above. We'll see how to manually deploy in the next section. + </para> + </section> + + <section> + <title> + Manually Deploying the web service WAR file + </title> + <para> + To deploy the web service, open the JMX Console. On a system with the default install of JBoss you will normally find it at: http://localhost:8080/jmx-console/. Depending on your setup you may need to change the url host and port. + </para> + <para> + Once your at the console find the "Main Deployer" (jboss.system:service=MainDeployer). Select that link. That will take you to the JMX Bean View of the Main Deployer. Now find the "deploy" action that takes a "String" as it's argument. Type in the full path to your WAR file and click the "invoke" button to deploy your WAR file. For example my full path is: /Users/sgriffith/svn_sandbox/jbossws_head/jbossws-docs/online/tutorial-src/jax-ws-hello-world/helloworldws.war. Your JMX Console will then display a new page titled "JMX MBean Operation Result". In the body of the page you should see "Operation completed successfully without a return value." if it succeeded in deploying. + </para> + <para>NOTE: If you did the "ant deploy" step above you'll need to go remove the WAR file that that step deployed before doing this step or this won't work properly. + </para> + <para> + In your shell or console you should also see something like: + </para> + <programlisting> + <![CDATA[ +07:39:01,467 INFO [MainDeployer] deploy, url=file:/Users/sgriffith/svn_sandbox/jbossws_head/jbossws-docs/online/tutorial-src/jax-ws-hello-world/helloworldws.war +07:39:08,755 INFO [TomcatDeployment] deploy, ctxPath=/helloworldws, warUrl=.../tmp/deploy/helloworldws30731-exp.war/ +07:39:09,655 INFO [StandardContext] Container org.apache.catalina.core.ContainerBase.[jboss.web].[localhost].[/helloworldws] has already been started +07:39:09,971 INFO [WSDLFilePublisher] WSDL published to: file:/Users/sgriffith/jboss-5.0.0.Beta2/server/default/data/wsdl/helloworldws.war/HelloWorldWSService30728.wsdl +07:39:10,446 INFO [ServiceEndpointManager] WebService started: http://Sam-Griffiths.local:8080/helloworldws/HelloWorldWS + ]]> + </programlisting> + <para> + You can see in the console output that our web service was deployed and started. You can also see that it is called "HelloWorldWS" which is what we specified in our "wstools-config.xml" file for the service name. One other thing to notice is that because we have a web.xml file for our WAR, our web service is mapped according to the settings in there. + </para> + </section> + <section> + <title> + View web service in JBoss Web Console + </title> + <para> + We can also see the deployed web service in the JBoss Web Services Console. If you did a default server install you'll be able to find it at: http://localhost:8080/jbossws/. Once your there you should see a link entitled "View the list of deployed Web Services". Click the word "View" to go to the list of deployed web services. After you've clicked on "View" you'll be taken to a page entitled "Registered Service Endpoints". You should now see our web service Endpoint ID and Addresses displayed in the table. For example this Endpoint address: http://Sam-Griffiths.local:8080/helloworldws/HelloWorldWS?wsdl. If you click on the Endpoint address link, depending on your browser you may see the WSDL XML. On some browsers you can see the WSDL XML source by going to your "View Source" or equivalent menu. Below you can see the WSDL for our sample. + </para> + <programlisting> + <![CDATA[ +<definitions name='HelloWorldWSService' targetNamespace='http://helloworld.samples.jboss.org/' xmlns='http://schemas.xmlsoap.org/wsdl/' xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' xmlns:tns='http://helloworld.samples.jboss.org/' xmlns:xsd='http://www.w3.org/2001/XMLSchema'> + <types> + <xs:schema targetNamespace='http://helloworld.samples.jboss.org/' version='1.0' xmlns:tns='http://helloworld.samples.jboss.org/' xmlns:xs='http://www.w3.org/2001/XMLSchema'> + <xs:element name='sayHello' type='tns:sayHello'/> + <xs:element name='sayHelloResponse' type='tns:sayHelloResponse'/> + <xs:complexType name='sayHello'> + <xs:sequence> + <xs:element minOccurs='0' name='arg0' type='xs:string'/> + </xs:sequence> + </xs:complexType> + <xs:complexType name='sayHelloResponse'> + <xs:sequence> + <xs:element minOccurs='0' name='return' type='xs:string'/> + </xs:sequence> + </xs:complexType> + </xs:schema> + </types> + <message name='HelloWorldWS_sayHello'> + <part element='tns:sayHello' name='sayHello'/> + </message> + <message name='HelloWorldWS_sayHelloResponse'> + <part element='tns:sayHelloResponse' name='sayHelloResponse'/> + </message> + <portType name='HelloWorldWS'> + <operation name='sayHello' parameterOrder='sayHello'> + <input message='tns:HelloWorldWS_sayHello'/> + <output message='tns:HelloWorldWS_sayHelloResponse'/> + </operation> + </portType> + <binding name='HelloWorldWSBinding' type='tns:HelloWorldWS'> + <soap:binding style='document' transport='http://schemas.xmlsoap.org/soap/http'/> + <operation name='sayHello'> + <soap:operation soapAction=''/> + <input> + <soap:body use='literal'/> + </input> + <output> + <soap:body use='literal'/> + </output> + </operation> + </binding> + <service name='HelloWorldWSService'> + <port binding='tns:HelloWorldWSBinding' name='HelloWorldWSPort'> + <soap:address location='http://Sam-Griffiths.local:8080/helloworldws/HelloWorldWS'/> + </port> + </service> +</definitions> + ]]> + </programlisting> + </section> + + <section> + <title> + Test web service + </title> + <para> + To test the web service we are going to make use of a commercial XML editor that has a built in tool for testing web services. That tool is Oxygen, but you can use any tool that supports doing web service calls. + </para> + <para> + In Oxygen go to the "Tools" menu and choose the "WSDL SOAP Analyser" sub-menu. It will bring up a dialog box asking you for the WSDL URL. Put in the value from the JBoss Web Service Console for the ServiceEndpointAddress. For the tutorial web service it is: http://Sam-Griffiths.local:8080/helloworldws/HelloWorldWS?wsdl. Once you've done that, it will parse the WSDL and bring up a test dialog. Change the value for the "Arg0" tag to a string value of someone's name. Now click the "Send" button to call the web service. You should get back a response much like that in the figure below. The figure below shows the request and response values of the web service. + </para> + <figure> + <title>Test of Web Services Call in Oxygen</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/Oxygen_WSDL_Test.png"/> + </imageobject> + </mediaobject> + </figure> + </section> + + <section> + <title> + Where from here? + </title> + <para> + There is much more to the JAX-WS 2.0 web service framework and more can be found in the JBoss JAX-WS 2.0 Reference Manual. In there you will find more details about specific features such as adding security, mtom and others. + Additonally, you'll also want to check out the JBoss IDE 2.0. It has GUI support for creating web services from with the Eclipse IDE. If your not using the JBoss Eclipse IDE, you can also use NetBeans or the standard Eclipse release from Eclipse.org. Look for more tutorials on our site covering how to use some of these IDE's. + </para> + <para> + You may also be interested in the following list of links that provide much more information on JAX-WS 2.0 and web services in general. + <itemizedlist> + <listitem>????</listitem> + <listitem>????</listitem> + <listitem>http://www.soapui.org/jbossws/gettingstarted.html</listite... + </itemizedlist> + </para> + + </section> + +<!-- How to add figures in Docbook + <figure> + <title> TCPMon output of Web Services Call </title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/jbossj2ee.book-17.gif"/> + </imageobject> + </mediaobject> + <para> You can also make changes to the request message and + resend it, making TCPMon a useful debugging tool as well.</para> + </figure> +--> + </chapter> Modified: trunk/jbossws-docs/online/tutorial-src/jax-ws-hello-world/build.xml =================================================================== --- trunk/jbossws-docs/online/tutorial-src/jax-ws-hello-world/build.xml 2007-01-11 15:14:41 UTC (rev 1932) +++ trunk/jbossws-docs/online/tutorial-src/jax-ws-hello-world/build.xml 2007-01-11 15:39:18 UTC (rev 1933) @@ -1,16 +1,14 @@ <?xml version="1.0"?> -<!-- Build file for JSR 181 POJO Hello World Web Service Example using new WS Stack --> -<project name="JSR 181 POJO Hello World Web Service Buildfile" default="main" basedir="."> +<!-- Build file for Hello World Web Service Example using new JBoss JAX-WS 2.0 Stack --> +<project name="JAX-WS 2.0 Hello World Web Service Buildfile" default="main" basedir="."> <!-- Standard Properties --> <property name="top.dir" value="${basedir}"/> - <property name="user.home.dir" value="/Users/sgriffith/"/> <property name="server.config" value="default"/> <property name="src.dir" value="${top.dir}/src"/> <property name="build.classes" value="${top.dir}/classes"/> <property name="java.dir" value="${top.dir}/src/java"/> <property name="resources.dir" value="${top.dir}/resources"/> - <!-- <property name="jboss.dir" value="${user.home.dir}/jboss-5.0.0.Beta2"/> --> - <property name="jboss.dir" value="${user.home.dir}/jboss-4.0.5.GA"/> + <property name="jboss.dir" value="/Users/sgriffith/jboss-5.0.0.Beta2"/> <property name="jboss.client" value="${jboss.dir}/client"/> <property name="jboss.lib" value="${jboss.dir}/lib"/> <property name="jboss.server" value="${jboss.dir}/server/${server.config}"/> @@ -23,10 +21,6 @@ <!-- Check for new WS jar file --> <available file="${jboss.client}/jbossws-client.jar" value="jbossws-client.jar" property="jbossws.client.jar"/> -<!-- Mapper definitions --> -<!-- <mapper id="deployedFileMapper" type="regexp" from="*hello*.war"/> --> - <available property="jbossws.client.jar" value="jbossws-client.jar" file="${jboss.client}/jbossws-client.jar"/> - <!-- Path Definitions --> <path id="client.classpath"> <fileset dir="${jboss.client}"> @@ -39,8 +33,10 @@ </path> <!-- Targets --> + +<!-- Helper target --> <target name="generate-sources" depends="" description="Generate the deployment resources and WSDL." if="HAVE_JDK_1.5"> -<!-- Define a taskdef for the wstools ant task --> + <!-- Define a taskdef for the wstools ant task --> <echo message="Inside generate-sources"/> <taskdef name="wstools" classname="org.jboss.ws.tools.ant.wstools"> <classpath refid="client.classpath"/> @@ -50,27 +46,28 @@ <echo message="wstools about to run"/> <wstools dest="${top.dir}/META-INF" config="${resources.dir}/wstools-config.xml"/> </target> - + +<!-- Reset everything for a build from scratch --> <target name="clean"> <echo message="In clean"/> <delete file="${top.dir}/helloworldws.war"/> <delete dir="${build.classes}"/> <delete dir="${top.dir}/META-INF"/> - <mkdir dir="${build.classes}"/> </target> + <!-- - Compile the java sources - --> + Compile the java sources +--> <!-- - Compile the java sources with jdk-1.5 - --> + Compile with jdk-1.5 as JAX-WS 2.0 needs annotations so we must use Java 5 or above. +--> <target name="compile15" depends="" description="compile the sources" if="HAVE_JDK_1.5"> + <mkdir dir="${build.classes}"/> <javac destdir="${build.classes}" classpathref="compile.classpath" debug="on"> <src path="${java.dir}"/> </javac> </target> - <target name="main" depends="compile15, generate-sources" if="jbossws.client.jar"> <echo message="In main"/> <war warfile="helloworldws.war" webxml="${src.dir}/metadata/web.xml"> @@ -81,8 +78,10 @@ </war> <!-- <antcall target="deploy"/> --> </target> - -<!-- + +<!-- + Deployment targets +--> <target name="deploy"> <echo message="In deploy"/> <copy file="${top.dir}/helloworldws.war" todir="${jboss.server.deploy}"/> @@ -95,5 +94,5 @@ <fileset id="web_service_wars" dir="${jboss.server.deploy}" includes="*hello*.war"/> </delete> </target> ---> + </project> Modified: trunk/jbossws-docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/HelloWorldWS.java =================================================================== --- trunk/jbossws-docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/HelloWorldWS.java 2007-01-11 15:14:41 UTC (rev 1932) +++ trunk/jbossws-docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/HelloWorldWS.java 2007-01-11 15:39:18 UTC (rev 1933) @@ -9,7 +9,10 @@ @WebMethod public String sayHello(String toWhom) { + if (toWhom == null) + return "It's null"; + // System.out.println("I'm Hit! " + toWhom); - return "Hello " + toWhom + "!" + " The date and time is: " + new java.util.Date(); - } + return "Hello " + toWhom + "!" + " The date and time is: " + new java.util.Date(); + } }