Author: cschneider
Date: Wed Sep 23 07:34:41 2009
New Revision: 817993
URL: http://svn.apache.org/viewvc?rev=817993&view=rev
Log:
CXF-52 added documentation and test for one way call
Modified:
cxf/trunk/distribution/src/main/release/samples/wsdl_first/README.txt
cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/client/CustomerServiceTester.java
cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/server/CustomerServiceImpl.java
Modified: cxf/trunk/distribution/src/main/release/samples/wsdl_first/README.txt
URL:
http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/wsdl_first/README.txt?rev=817993&r1=817992&r2=817993&view=diff
==============================================================================
--- cxf/trunk/distribution/src/main/release/samples/wsdl_first/README.txt
(original)
+++ cxf/trunk/distribution/src/main/release/samples/wsdl_first/README.txt Wed
Sep 23 07:34:41 2009
@@ -1,46 +1,70 @@
-Hello World Demo using Document/Literal Style
-=============================================
+WSDL First Demo
+===============
-This demo illustrates the use of the JAX-WS APIs to run a simple
-client against a standalone server using SOAP 1.1 over HTTP.
+This demo shows how to build and call a webservice using a given WSDL (also
called Contract First).
+As writing a WSDL by hand is not so easy the following Howto may also be an
interesting read:
+http://cxf.apache.org/docs/defining-contract-first-webservices-with-wsdl-generation-from-java.html
-It also shows how CXF configuration can be used to enable schema validation
-on the client and/or server side: By default the message parameters would not
-be validated, but the presence of the cxf.xml configuration file on
-the classpath, and its content change this default behavior:
-The configuration file specifies that
-
-a) if a JAX-WS client proxy is created for port
{http://apache.org/hello_world_soap_http}SoapPort
-it should have schema validation enabled.
-
-b) if a JAX-WS server endpoint is created for port
{http://apache.org/hello_world_soap_http}SoapPort
-it should have schema validation enabled.
-
-The client's second greetMe invocation causes an exception (a marshalling
-error) on the client side, i.e. before the request with the invalid parameter
-goes on the wire.
-After commenting the definition of the <jaxws:client> element in cxf.xml you
-will notice that the client's second greetMe invocation still throws an
exception,
-but that this time the exception is caused by an unmarshalling error on the
-server side.
-Commenting both elements, or renaming/removing the cfg.xml file, and thus
-restoring the default behavior, results in the second greetMe invocation
-not causing an exception.
+This demo mainly addresses SOAP over HTTP in Document / Literal or Document /
Literal wrapped style.
+For other transports or styles the configuration may look different.
-Please review the README in the samples directory before continuing.
+The Demo consist of three parts:
+- Creating the server and client code stubs from the WSDL
+- Service implementation (using JAX-WS or using Spring)
+- Client implementation (using JAX-WS or using Spring)
+
+Code generation
+---------------
+
+When using maven the code generation is done using the maven cxf-codegen-plugin
+(see http://cxf.apache.org/docs/maven-cxf-codegen-plugin-wsdl-to-java.html).
+In case ant is used the macro wsdl2java in the common_build.xml builds the code
+(see http://cxf.apache.org/docs/wsdl-to-java.html).
+
+The code generation is tuned using a binding.xml file. In this case the file
configures that
+normal java Date is used for xsd:date and xsd:DateTime. If this is not present
then XMLGregorianCalendar
+will be used.
+
+One other common use of the binding file is to also generate asynchronous
stubs. The line
+jaxws:enableAsyncMapping has to be uncommented to use this.
+
+More info about the binding file can be found here:
+https://jax-ws.dev.java.net/jax-ws-20-fcs/docs/customizations.html
+
+Server implementation
+---------------------
+
+The service is implemented in the class CustomerServiceImpl. The class simply
implements the previously
+generated service interface. The method getCustomersByName demonstrates how a
query function could look like.
+The idea is to search and return all customers with the given name. If the
searched name is none then the method
+returns an exception to indicate that no matching customer was found. (In a
real implementation probably a list with
+zero objects would be used. This is mainly to show how custom exceptions can
be used).
+For any other name the method will return a list of two Customer objects. The
number of objects can be increased to
+test how fast CXF works for larger data.
+
+Now that the service is implemented it needs to be made available. In this
example a standalone server is used.
+This can be done either with the JAX-WS API demonstrated in the class
CustomerService or using a spring config as
+demonstrated in the class CustomerServiceSpringServer.
+
+Client implementation
+---------------------
+
+The main client code lives in the class CustomerServiceTester. This class
needs a proxy to the service and then
+demonstrates some calls and their expected outcome using junit assertions.
+
+The first call is a request getCustomersByName for all customers with name
"Smith". The result is then checked.
+Then the same method is called with the invalid name "None". In this case a
NoSuchCustomerException is expected.
+The third call shows that the one way method updateCustomer will return
instantly even if the service needs some
+time to process the request.
+
+The classes CustomerServiceClient and CustomerServiceSpringClient show how to
get a service proxy using JAX-WS
+or Spring and how to wire it to your business class (in this case
CustomerServiceTester).
Prerequisite
------------
-If your environment already includes cxf-manifest.jar on the
-CLASSPATH, and the JDK and ant bin directories on the PATH
-it is not necessary to set the environment as described in
-the samples directory README. If your environment is not
-properly configured, or if you are planning on using wsdl2java,
-javac, and java to build and run the demos, you must set the
-environment.
-
+Please review the README in the samples main directory before continuing.
Building and running the demo using Ant
---------------------------------------
@@ -77,116 +101,17 @@
To remove the code generated from the WSDL file and the .class
files, run "mvn clean".
+There is no special maven profile for the spring client and server but you can
easily set it up yourself.
+Using eclipse to run and test the demo
+--------------------------------------
-Building the demo using wsdl2java and javac
--------------------------------------------
-
-From the base directory of this sample (i.e., where this README file is
-located) first create the target directory build/classes and then
-generate code from the WSDL file.
-
-For UNIX:
- mkdir -p build/classes
-
- wsdl2java -d build/classes -compile ./wsdl/hello_world.wsdl
-
-For Windows:
- mkdir build\classes
- Must use back slashes.
-
- wsdl2java -d build\classes -compile .\wsdl\hello_world.wsdl
- May use either forward or back slashes.
-
-Now compile the provided client and server applications with the commands:
-
-For UNIX:
-
- export CLASSPATH=$CLASSPATH:$CXF_HOME/lib/cxf-manifest.jar:./build/classes
- javac -d build/classes src/demo/hw/client/*.java
- javac -d build/classes src/demo/hw/server/*.java
-
-For Windows:
- set classpath=%classpath%;%CXF_HOME%\lib\cxf-manifest.jar;.\build\classes
- javac -d build\classes src\demo\hw\client\*.java
- javac -d build\classes src\demo\hw\server\*.java
-
-
-Running the demo using java
----------------------------
-
-From the base directory of this sample (i.e., where this README file is
-located) run the commands, entered on a single command line:
-
-For UNIX (must use forward slashes):
- java -Djava.util.logging.config.file=$CXF_HOME/etc/logging.properties
- com.example.customerservice.server.Server &
-
- java -Djava.util.logging.config.file=$CXF_HOME/etc/logging.properties
- com.example.customerservice.client.Client ./wsdl/hello_world.wsdl
-
-The server process starts in the background. After running the client,
-use the kill command to terminate the server process.
-
-For Windows (may use either forward or back slashes):
- start
- java -Djava.util.logging.config.file=%CXF_HOME%\etc\logging.properties
- com.example.customerservice.server.Server
-
- java -Djava.util.logging.config.file=%CXF_HOME%\etc\logging.properties
- com.example.customerservice.client.Client .\wsdl\hello_world.wsdl
-
-A new command windows opens for the server process. After running the
-client, terminate the server process by issuing Ctrl-C in its command window.
-
-To remove the code generated from the WSDL file and the .class
-files, either delete the build directory and its contents or run:
-
- ant clean
-
-
-Building and running the demo in a servlet container
-----------------------------------------------------
-
-Please refer to samples directory README for building demo in a servlet
container.
-
-Using ant, run the client application with the command:
-
- ant client-servlet -Dbase.url=http://localhost:#
-
-Where # is the TCP/IP port used by the servlet container,
-e.g., 8080.
-
-Or
- ant client-servlet -Dhost=localhost -Dport=8080
-
-You can ignore the -Dhost and -Dport if your tomcat setup is same, i.e ant
client-servlet
-
-Using java, run the client application with the command:
-
- For UNIX:
-
- java -Djava.util.logging.config.file=$CXF_HOME/etc/logging.properties
- com.example.customerservice.client.Client
http://localhost:#/helloworld/services/hello_world?wsdl
-
- For Windows:
-
- java -Djava.util.logging.config.file=%CXF_HOME%\etc\logging.properties
- com.example.customerservice.client.Client
http://localhost:#/helloworld/services/hello_world?wsdl
-
-Where # is the TCP/IP port used by the servlet container,
-e.g., 8080.
-
-
-Running demo with HTTP GET
---------------------------
-APACHE CXF support HTTP GET to invoke the service, instead of running
-
- ant client
+run the following in the demo base directory
-you can use
+mvn eclipse:eclipse
- ant client.get
+Then use Import / Existing projects into workspace and browse to the
wsdl_first directory. Import the wsdl_first project.
-to invoke the service with simple HttpURLConnection, or you can even
-use your favorite browser to get the results back.
+The demo can now be started using "Run as Java Application" on the
CustomerServiceServer.java
+and the CustomerServiceClient. For the spring demo run the classes
CustomerServiceSpringClient.java
+or CustomerServiceSpringServer.java
Modified:
cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/client/CustomerServiceTester.java
URL:
http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/client/CustomerServiceTester.java?rev=817993&r1=817992&r2=817993&view=diff
==============================================================================
---
cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/client/CustomerServiceTester.java
(original)
+++
cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/client/CustomerServiceTester.java
Wed Sep 23 07:34:41 2009
@@ -61,6 +61,14 @@
Assert.assertEquals("None", e.getFaultInfo().getCustomerName());
System.out.println("NoSuchCustomer exception was received as
expected");
}
+
+ // The implementation of updateCustomer is set to sleep for some
seconds.
+ // Still this method should return instantly as the method is declared
+ // as a one way method in the WSDL
+ Customer customer = new Customer();
+ customer.setName("Smith");
+ customerService.updateCustomer(customer);
+
System.out.println("All calls were succesful");
}
Modified:
cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/server/CustomerServiceImpl.java
URL:
http://svn.apache.org/viewvc/cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/server/CustomerServiceImpl.java?rev=817993&r1=817992&r2=817993&view=diff
==============================================================================
---
cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/server/CustomerServiceImpl.java
(original)
+++
cxf/trunk/distribution/src/main/release/samples/wsdl_first/src/main/java/com/example/customerservice/server/CustomerServiceImpl.java
Wed Sep 23 07:34:41 2009
@@ -34,6 +34,11 @@
import com.example.customerservice.NoSuchCustomerException;
public class CustomerServiceImpl implements CustomerService {
+
+ /**
+ * The WebServiceContext can be used to retrieve special attributes like
the
+ * user principal. Normally it is not needed
+ */
@Resource
WebServiceContext wsContext;
@@ -63,8 +68,13 @@
}
public void updateCustomer(Customer customer) {
- // TODO Auto-generated method stub
-
+ System.out.println("update request was received");
+ try {
+ Thread.sleep(10000);
+ } catch (InterruptedException e) {
+ // Nothing to do here
+ }
+ System.out.println("Customer was updated");
}
}
