[wise-users] [Wise] - Wise-core Programmer Guide (version 2.0)

[Alessio Soldano]

Alessio Soldano [https://community.jboss.org/people/asoldano] modified the document:

"Wise-core Programmer Guide (version 2.0)"

To view the document, visit: https://community.jboss.org/docs/DOC-48312

--------------------------------------------------------------
h2. What's new
Wise-core 2.0 is a major revisit of former 1.x version to make the project run on top of JBoss Application Server 7.1 / 7.2 and use JBossWS (Apache CXF based) 4.x generation stack.
The project module structure has also been updated to let it build with Apache Maven 3 and to better isolate integratation testsuites.
h2. What is wise-core
Wise-core is a library to simplify web service invocation from a client point of view; it aims at providing a near zero-code solution to parse wsdls, select service/port and call operations by mapping a user defined object model to the JAX-WS objects required to perform the call.
In other words wise-core aims at providing web services client invocation in a dynamic manner.

While basic JAX-WS tool for wsdl-to-java generation (like wsconsume) are great for most Java developer usecases, the generated stub classes kind of introduce a new (or renewed :)) level of coupling very similar to Corba IDL; by generating statical webservice stubs you actually couple client and server.
+So what is the alternative?+
Generating stubs at runtime and using dynamic mapping on generated stub.
+How does wise-core perform this generic task?+
In a nutshell it generates classes on the fly using +wsconsume+ runtime API, loading them in current class loader and using them with Java Reflection API. What we add is a generic mapping API to transform an arbitrary object model in the wsconsume generated ones, make the call and map the answer back again to the custom model using Smooks. Moreover this is achieved keeping the API general enough to plug in other mappers (perhaps custom ones) to transform user defined object into JAX-WS generated objects.

Wise supports standard JAX-WS handlers too and a generic smooks transformation handler to apply transformation to generated SOAP messages; currently there's also a basic support for some WS-* specifications, which will be futher developed in the next future.
The key to understand the Wise-core idea is to keep in mind it is an API hiding JAX-WS wsconsume tools to generate JAX-WS stub classes and providing API to invoke them in a dynamic way using mappers to convert your own object model to JAX-WS generated one.
One of the most important aspects of this approach is that Wise delegates everything concerning standards and interoperability to the underlying JAX-WS client implementation (JBossWS / Apache CXF in the current implementation). In other words if an hand written webservice client using JBossWS is interoperable and respects standards, the same applies to a Wise-generated client! We are just adding commodities and dynamical transparent generation and access to JAX-WS clients, we are not rewriting client APIs, the well tested and working ones from JBossWS is fine with us.

h2. API description
Below is a description of Wise-core API, its goals and how it can be used in practice to simplify your webservice client development. Anyway we strongly suggest you to take a look at our javadoc as a more complete reference for the API.
The core elements of our API are:
* WSDynamicClient: This is the Wise core class responsible for the invocation of the JAX-WS tools and that handles wsdl retrieval and parsing. It is used to build the list of WSService representing the services published in parsed wsdl.  It can also be used to directly get the WSMethod to invoke the specified action on specified port of specified service. It is the base method for "one line of code invocation". Each single instance of this class is responsible of its own temp files, smooks instance and so on. It is importanto to call close() method to dispose resources and clean temp directories.
* WSService: represents a single service. It can be used to retrieve the current service endpoints (Ports).
* WSEndpoint: represents an Endpoint(Port) and has utility methods to edit username, password, endpoint address, attach handlers, etc.
* WSMethod: represents a webservice operation(action) invocation and it always refers to a specific endpoint. It is used for effective invocation of a web service action.
* WebParameter: holds single parameter's data required for an invocation
* InvocationResult: holds the webservice's invocation result data. Anyway it returns a Map<String, Object> with webservice's call results, eventually applying a  mapping to custom objects using a WiseMapper
* WiseMapper: is a simple interface implemented by any mapper used within wise-core requiring a single method applyMapping.

All the elements mentioned above can be combined and used to perform web service invocation and get results. They basically support two kinds of invocation:
1. One line of code invocation: with this name we mean a near zero code invocation where developer who have well configured Wise just have to know wsdl location, endpoint and port name to invoke the service and get results. For a complete description and sample of this Wise usecase please refer to paragraph 5.1.
2. Interactively explore your wsdl: Wise can support a more interactive style of development exploring all wsdl artifact dynamically loaded. This kind of use is ideal for an interactive interface to call the service and is by the way how we are developed our web GUI. For a complete description and sample of this Wise usecase please refer to paragraph 5.2.

h2. Configuration
Wise-core configurations are provided by setting properties on WSDynamicClientBuilder during WSDynamicClient instance creation.
Properties and their purpose are well documented in WSDynamicClientBuilder javadoc. Here is and example on how to leverage the builder to get the WSDynamicClient:

[...]
URL wsdlURL = new URL(getServerHostAndPort() + /wsaandwsse/WSAandWSSE?wsdl);
WSDynamicClientBuilder clientBuilder = WSDynamicClientFactory.getJAXWSClientBuilder();
WSDynamicClient client = clientBuilder.tmpDir(target/temp/wise).verbose(true).keepSource(true).wsdlURL(wsdlURL.toString()).build();
[...]


h2. Wise API usage
Wise can be used either as near zero code web service invocation framework or as an API to (interactively) explore wsdl generated objects and then perform the invocation through theselected service/endpoint/port.
The first approach is very useful when Wise is integrated in a server side solution, while the second one is ideal when you are building an interactive client with some (or intense) user interaction.
By the way the first approach is the one that has been used while integrating Wise in JBossESB, while the second one is the base on which we built our web based generic interactive client of web service (Wise-webgui).
h3. One line of code invocation
A sample may be much more clear than a lot of explanation:

WSMethod method = client.getWSMethod("HelloService", "HelloWorldBeanPort", "echo");
Map<String, Object> args = new java.util.HashMap<String, Object>();
args.put("arg0", "from-wise-client");
InvocationResult result = method.invoke(args, null);

I can already hear you saying: "hey, you said just 1 line of code, not 4!!". Yes, but if you exclude lines 2 and 3 where we are constructing a Map to put in request parameters that are normally build in other ways from your own program, you can easily compact the other 2 lines in just one line of code invocation. By the way keeping 2 or 3 lines of code makes the code more readable, but we would remark that conceptually you are writing a single line of code.
You can find a running integration test called WiseIntegrationBasicTest using exactly this code. Of course thre are few more lines of code to create client and to make assertion on the results, but trust us they are very few line of code.
h3. Interactive wsdl exploration

try {
    WSDynamicClientBuilder clientBuilder = WSDynamicClientFactory.getJAXWSClientBuilder();
    WSDynamicClient client = clientBuilder.tmpDir("target/temp/wise").verbose(true).keepSource(true)
       .wsdlURL("http://127.0.0.1:8080/InteractiveHelloWorld/InteractiveHelloWorldWS?wsdl").build();
    Map<String, WSService> services = client.processServices();
    System.out.println("Available services are:");
    for (String key : services.keySet()) {
        System.out.println(key);
    }
    System.out.println("Selectting the first one");
    Map<String, WSEndpoint> endpoints = services.values().iterator().next().processEndpoints();
    System.out.println("Available endpoints are:");
    for (String key : endpoints.keySet()) {
        System.out.println(key);
    }
    System.out.println("Selectting the first one");
    Map<String, WSMethod> methods = endpoints.values().iterator().next().getWSMethods();
    System.out.println("Available methods are:");
    for (String key : methods.keySet()) {
        System.out.println(key);
    }
    System.out.println("Selectting the first one");
    WSMethod method = methods.values().iterator().next();
    HashMap<String, Object> requestMap = new HashMap<String, Object>();
    requestMap.put("toWhom", "SpiderMan");
    InvocationResult result = method.invoke(requestMap, null);
    System.out.println(result.getMapRequestAndResult(null, null));
    System.out.println(result.getMapRequestAndResult(null, requestMap));
    client.close();
} catch (Exception e) {
     e.printStackTrace();
}
 

You can find a running sample called IntercativeHelloWorld using exactly this code in our samples directory.
h2. WiseMapper: from your own object model to the generated JAX-WS model and vice versa
fdsfs
h2. Adding standard JAXWS handlers
fd
h2. Requirements and dependencies
fdfs
h2. Getting started
dsada
h3. Testsuite
dsdfsa
h3. Samples
fdsgfs
--------------------------------------------------------------

Comment by going to Community
[https://community.jboss.org/docs/DOC-48312]

Create a new document in Wise at Community
[https://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2048]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/wise-users/attachments/20130205/9e65fdcb/attachment-0001.html