<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="https://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
Wise-core Programmer Guide (version 2.0)
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="https://community.jboss.org/people/asoldano">Alessio Soldano</a> in <i>Wise</i> - <a href="https://community.jboss.org/docs/DOC-48312">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p><div class="toc" style="border: 1px dashed black; padding: 10px;"><ul><li>
<a class="jive-link-anchor-small" href="#Whats_new" rel="nofollow">What's new</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#What_is_wisecore" rel="nofollow">What is wise-core</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#API_description" rel="nofollow">API description</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Configuration" rel="nofollow">Configuration</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Wise_API_usage" rel="nofollow">Wise API usage</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#One_line_of_code_invocation" rel="nofollow">One line of code invocation</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Interactive_wsdl_exploration" rel="nofollow">Interactive wsdl exploration</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#WiseMapper_from_your_own_object_model_to_the_generated_JAXWS_model_and_vice_versa" rel="nofollow">WiseMapper: from your own object model to the generated JAX-WS model and vice versa</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Adding_standard_JAXWS_handlers" rel="nofollow">Adding standard JAXWS handlers</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#Logging_Handler" rel="nofollow">Logging Handler</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Smooks_Handler" rel="nofollow">Smooks Handler</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Adding_your_own_Handler" rel="nofollow">Adding your own Handler</a>
</li>
</ul></ul><li>
<a class="jive-link-anchor-small" href="#Requirements_and_dependencies" rel="nofollow">Requirements and dependencies</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Getting_started" rel="nofollow">Getting started</a>
</li>
<ul><li>
<a class="jive-link-anchor-small" href="#Setting_Wise_dependencies_in_your_application" rel="nofollow">Setting Wise dependencies in your application</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Building_from_sources" rel="nofollow">Building from sources</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Testsuite" rel="nofollow">Testsuite</a>
</li>
<li>
<a class="jive-link-anchor-small" href="#Samples" rel="nofollow">Samples</a>
</li>
</ul></ul></div></p><h1 id="Whats_new">What's new</h1><p>Wise-core 2.0 is a major revisit of former 1.x versions 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.</p><p>The project module structure has also been updated to let it build with Apache Maven 3 and to better isolate integration testsuites.</p><h1 id="What_is_wisecore">What is wise-core</h1><p>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.</p><p>In other words wise-core aims at providing web services client invocation in a dynamic manner.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>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.</p><p><em>So what is the alternative?</em></p><p>Generating stubs at runtime and using dynamic mapping on generated stub.</p><p><em>How does wise-core perform this generic task?</em></p><p>In a nutshell it generates classes on the fly using <em>wsconsume</em> 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.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>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.</p><p>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.</p><p>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.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h1 id="API_description">API description</h1><p>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.</p><p>The core elements of our API are:</p><ul><li><span style="text-decoration: underline;">WSDynamicClient</span>: 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.</li><li><span style="text-decoration: underline;">WSService</span>: represents a single service. It can be used to retrieve the current service endpoints (Ports).</li><li><span style="text-decoration: underline;">WSEndpoint</span>: represents an Endpoint(Port) and has utility methods to edit username, password, endpoint address, attach handlers, etc.</li><li><span style="text-decoration: underline;">WSMethod</span>: 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.</li><li><span style="text-decoration: underline;">WebParameter</span>: holds single parameter's data required for an invocation</li><li><span style="text-decoration: underline;">InvocationResult</span>: 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</li><li><span style="text-decoration: underline;">WiseMapper</span>: is a simple interface implemented by any mapper used within wise-core requiring a single method applyMapping.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>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:</p><ol><li><span style="text-decoration: underline;">One line of code invocation</span>: 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.</li><li><span style="text-decoration: underline;">Interactively explore your wsdl</span>: 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.</li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h1 id="Configuration">Configuration</h1><p>Wise-core configurations are provided by setting properties on WSDynamicClientBuilder during WSDynamicClient instance creation.</p><p>Properties and their purpose are well documented in WSDynamicClientBuilder javadoc. Here is and example on how to leverage the builder to get the WSDynamicClient:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">[...]
URL wsdlURL = <font color="navy"><b>new</b></font> URL(getServerHostAndPort() + /wsaandwsse/WSAandWSSE?wsdl);
WSDynamicClientBuilder clientBuilder = WSDynamicClientFactory.getJAXWSClientBuilder();
WSDynamicClient client = clientBuilder.tmpDir(target/temp/wise).verbose(<font color="navy"><b>true</b></font>).keepSource(<font color="navy"><b>true</b></font>).wsdlURL(wsdlURL.toString()).build();
[...]
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h1 id="Wise_API_usage">Wise API usage</h1><p>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.</p><p>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.</p><p>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).</p><h2 id="One_line_of_code_invocation">One line of code invocation</h2><p>A sample may be much more clear than a lot of explanation:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">WSMethod method = client.getWSMethod(<font color="red">"HelloService"</font>, <font color="red">"HelloWorldBeanPort"</font>, <font color="red">"echo"</font>);
Map<String, Object> args = <font color="navy"><b>new</b></font> java.util.HashMap<String, Object>();
args.put(<font color="red">"arg0"</font>, <font color="red">"from-wise-client"</font>);
InvocationResult result = method.invoke(args, <font color="navy"><b>null</b></font>);
</code></pre><p>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.</p><p>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.</p><h2 id="Interactive_wsdl_exploration">Interactive wsdl exploration</h2><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java"><font color="navy"><b>try</b></font> <font color="navy">{</font>
    WSDynamicClientBuilder clientBuilder = WSDynamicClientFactory.getJAXWSClientBuilder();
    WSDynamicClient client = clientBuilder.tmpDir(<font color="red">"target/temp/wise"</font>).verbose(<font color="navy"><b>true</b></font>).keepSource(<font color="navy"><b>true</b></font>)
       .wsdlURL(<font color="red">"http://127.0.0.1:8080/InteractiveHelloWorld/InteractiveHelloWorldWS?wsdl"</font>).build();
    Map<String, WSService> services = client.processServices();
    System.out.println(<font color="red">"Available services are:"</font>);
    <font color="navy"><b>for</b></font> (String key : services.keySet()) <font color="navy">{</font>
        System.out.println(key);
    <font color="navy">}</font>
    System.out.println(<font color="red">"Selectting the first one"</font>);
    Map<String, WSEndpoint> endpoints = services.values().iterator().next().processEndpoints();
    System.out.println(<font color="red">"Available endpoints are:"</font>);
    <font color="navy"><b>for</b></font> (String key : endpoints.keySet()) <font color="navy">{</font>
        System.out.println(key);
    <font color="navy">}</font>
    System.out.println(<font color="red">"Selectting the first one"</font>);
    Map<String, WSMethod> methods = endpoints.values().iterator().next().getWSMethods();
    System.out.println(<font color="red">"Available methods are:"</font>);
    <font color="navy"><b>for</b></font> (String key : methods.keySet()) <font color="navy">{</font>
        System.out.println(key);
    <font color="navy">}</font>
    System.out.println(<font color="red">"Selectting the first one"</font>);
    WSMethod method = methods.values().iterator().next();
    HashMap<String, Object> requestMap = <font color="navy"><b>new</b></font> HashMap<String, Object>();
    requestMap.put(<font color="red">"toWhom"</font>, <font color="red">"SpiderMan"</font>);
    InvocationResult result = method.invoke(requestMap, <font color="navy"><b>null</b></font>);
    System.out.println(result.getMapRequestAndResult(null, <font color="navy"><b>null</b></font>));
    System.out.println(result.getMapRequestAndResult(null, requestMap));
    client.close();
<font color="navy">}</font> <font color="navy"><b>catch</b></font> (Exception e) <font color="navy">{</font>
     e.printStackTrace();
<font color="navy">}</font>
 
</code></pre><p>You can find a running sample called IntercativeHelloWorld using exactly this code in our samples directory.</p><h2 id="WiseMapper_from_your_own_object_model_to_the_generated_JAXWS_model_and_vice_versa">WiseMapper: from your own object model to the generated JAX-WS model and vice versa</h2><p>The core idea of Wise is to allow users to call webservice using their own object model, loading at runtime (and hiding) the JAX-WS generated client classes. Of course developers who have a complex object model and/or are using a webservice with a complex model have to provide some kind of mapping between them.</p><p>This task is done by applying a <em>WiseMapper</em> which is responsible for this mapping. Mappers are applied on both the WSMethod invocation and the results coming from InvocationResult. Of course the first one maps the custom model to the JAX-WS one, while the second one takes care of the other way.</p><p>Wise provides a Smooks based mapper, but it should be easy to write your own.</p><h2 id="Adding_standard_JAXWS_handlers"><span style="font-size: 21px;">Adding standard JAXWS handlers</span></h2><p>WSEndPoint class has a method to add standard JAX-WS handlers to the endpoint. Wise takes care of the handler chain construction and ensures your client side handlers are fired during any invocations.</p><p>We provide two standard handlers: one to log the request/response SOAP message for any invocation and one applying Smooks transformation on your SOAP content.</p><h3 id="Logging_Handler">Logging Handler</h3><p>This simple SOAPHandler will output the contents of incoming and outgoing messages. It checks the MESSAGE_OUTBOUND_PROPERTY in the context to see if this is an outgoing or incoming message. Finally, it writes a brief message to the print stream and outputs the message.</p><h3 id="Smooks_Handler">Smooks Handler</h3><p>A SOAPHandler extension. It applies Smooks transformations on SOAP messages. The transformation can also use freemarker, using provided javaBeans map to get values. It can apply transformation on inbound messages only, outbound ones only or both, depending on setInBoundHandlingEnabled(boolean) and setOutBoundHandlingEnabled(boolean) methods.</p><p>Take a look at our unit test org.jboss.wise.core.mapper.SmooksMapperTest in test-src directory.</p><h3 id="Adding_your_own_Handler">Adding your own Handler</h3><p>Since Wise's handlers are JAX-WS standard handlers, you just have to provide a class that implements SOAPHandler<SOAPMessageContext></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h1 id="Requirements_and_dependencies">Requirements and dependencies</h1><p>Wise-core depends on JBossWS, in particular on JBossWS-CXF stack, given that's what is used on JBoss AS 7. You can have a look at the Maven project dependencies by running:</p><pre class="jive-pre"><code class="jive-code">mvn dependency:tree
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h1 id="Getting_started">Getting started</h1><p>First of all, make sure to have the JBoss.org Maven repository <a class="jive-link-wiki-small" href="https://community.jboss.org/docs/DOC-15169">properly setup</a>.</p><p>The relevant artifacts for the current release are available on the <a class="jive-link-external-small" href="https://repository.jboss.org/nexus/content/groups/public-jboss/org/jboss/wise/" rel="nofollow">public repository</a>.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2 id="Setting_Wise_dependencies_in_your_application">Setting Wise dependencies in your application</h2><p>The binary distribution contains the required dependency libraries to simply setting classpath for an application willing to use Wise.</p><p>Maven based application should set dependencies on the <em><strong>org.jboss.wise:wise-core-cxf</strong></em> artifact. If the application is meant to run in-container on JBoss AS 7, you should evaluate excluding some of Wise core dependencies from the target application deployment archive, as they are already available on the application server. Consider having a look at the <em>incontainer</em> sample included in the distribution or at the <em>Wise WebGUI</em> for details on how to achieve that by using a <em>jboss-deployment-structure.xml</em> descriptor.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2 id="Building_from_sources">Building from sources</h2><p>Should you want to build from source and install artifacts into the local Maven repository, that's done as for any other Maven 3 project, by running:</p><pre class="jive-pre"><code class="jive-code">mvn clean install
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2 id="Testsuite">Testsuite</h2><p>You can run the integration testsuite as follows:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">mvn -Djboss.bind.address=localhost integration-test
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Where ofcourse 'localhost' is the host for your currently running JBoss AS.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Wise-core 2.0 has been fully tested on JBoss AS 7.1.1.Final. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h2 id="Samples">Samples</h2><p>Plese refer to sample specific direcotory README.txt for a full description of the samples and how to run them.</p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="https://community.jboss.org/docs/DOC-48312">going to Community</a></p>
<p style="margin: 0;">Create a new document in Wise at <a href="https://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2048">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>