<h1>Providing EJB-based Web Services with JBoss.net</h1>

<p> 
<img SRC="../../../../../modules/html/developers/guides/jboss.net/jboss-net.png" align=LEFT> 
Axis already comes with a general <em>web service provider</em> implementation 
that will wrap any stateless Enterprise SessionBean that is individually 
deployed within the J2EE container. In JBoss.net,
the deployment unit of a 
<a href="../../../developers/guides/jboss.net/deployment">web service archive</a> 
allows to assemble these ejb and the web service bits of an enterprise 
application. Since this eases the lookup procedure, JBoss.net comes 
with a dedicated <code>org.jboss.net.axis.server.EJBProvider</code> 
that exhibits less invocation overhead and better WSDL-generation facilities wrt
transport-specific issues (such as SOAPAction headers).
</p>

<p>
<img SRC="../../../../../modules/html/developers/guides/jboss.net/hello-ear.jpg" align=RIGHT>
<cite>
Here is an <a href="../../../../../modules/html/developers/guides/jboss.net/HelloBean.java">example bean implementation</a> and its <a href="../../../../../modules/html/developers/guides/jboss.net/hello-web-service.xml">wsdd</a>. 
Please note that the provider - being usually located in the same VM as the EJBContainer -  
can hit remote as well as local beans.
</cite>
</p>

<p>
<img SRC="../../../../../modules/html/developers/guides/jboss.net/hello-wsr.jpg" align=text>
</p>

<p>
In addition, the JBoss.net EJBProvider is able to interact with Stateful 
SessionBeans in a reasonable manner. Depending on the chosen transport, 
it is possible to maintain sessions with a web service client, e.g., through 
persistent http/s sessions and the use of cookies. If the EJB-based web 
service is deployed with session-scope (as opposed to the default call-scope), 
the JBoss.net/JAX-RPC lifecycle management will bind a reference to a 
stateful bean to the individual transport sessions. 
</p>

<p><cite>Here is an <a href="../../../../../modules/html/developers/guides/jboss.net/state-web-service.xml">example wsdd wrapping a stateful ejb web service</a>.</cite></p>

<p>
If the complexity of the wsdd documents shocks you, please do not despair: 
Even the presented example documents have been auto-generated 
from the source code using the <a href="../../../developers/guides/jboss.net/xdoclet">jboss.net xdoclet module</a>.
</p>

<h2>Entity Beans?</h2>

<p>
You usually would NOT want to expose your Entity Beans as Web Services! This 
is for the same practicability, security and design reasons as you 
usually would not expose them to remote applications. Instead, the value object 
pattern is employed to stream their state via serializable JavaBeans to the client and vice versa.
Using JAX-RPC/Axis typemappings that convert your value objects into/from 
XML structures is hence the straightforward way of distributing entity bean 
information via SOAP.
</p>

<p><cite><a href="../../../../../modules/html/developers/guides/jboss.net/hello-web-service.xml">The wsdd example of before</a> 
contains an example of such a typemapping using the 
<code>org.apache.axis.encoding.ser.BeanSerializer</code> implementation.</cite>
</p>

<h2>For the Crazy Guys</h2>

<p>
Value objects often destroy your nice application design. 
Value objects are often dependent on a specific client use case. 
Value objects are sometimes hard to synchronize with the application 
and transactional state. That is why we experiment with another approach 
to the issue where we assume that any client or remote 
communication will happen over the web service layer and any inter-application 
communication will happen over local ejb interfaces. In that approach, 
the web service layer is reponsible for building purpose-specific 
"value structures" by (de-)serializing the entity bean state immediately 
into/from the XML.
</p>

<p>This starts to work by a combination of the Axis BeanSerializer and the
<code>org.jboss.axis.server.EntityBeanDeserializer</code> which currently 
requires a single attribute of the XML representation to operate as the 
primary key. Before deserializing the xml into approriate 
setter-calls, EntityBeanDeserializer will call the find method to 
get a reference to the identified entity bean.
</p>

<p> 
Since the web service layer has a similar position to the web application 
layer with respect to the EJB application, above scheme will only work, if we 
extend the transactional context over the de-serialization process. For that 
purpose, the pair of <code>org.jboss.net.axis.server.TransactionRequestHandler</code>
and the <code>org.jboss.net.axis.server.TransactionResponseHandler</code> will 
spawn a minimal user transaction around the exposed Web-Service method when 
embedded into the service-specific message chains. 
The <code>org.jboss.net.axis.server.SerializationResponseHandler</code> 
is used to force serialization to happen within the transactional borders. 
</p>

<p> <cite>see this <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jboss/contrib/jboss.net/testsuite/src/main/org/jboss/net/samples/store/">complex example of the jboss.net testsuite</a></cite></p>

<p> 
However, in the context of <a href="../../../developers/guides/jboss.net/ws4ee">WS4EE 1.0 support</a>,
the relation of JAX-RPC handlers and the EJB invocation stack will be redesigned 
such that (de-)serialization will generally happen within the call context of 
the target bean. The described procedure hence can be much simplified.
</p>

<p>"Dr. Schorsch" (<a ref="mailto:christoph.Jung@jboss.org">christoph.jung@jboss.org</a>) - 2001/09/29, Last update on 2003/10/15</p>

<p><small>All mentioned trademarks on this page are 
copyright of their respective owners ... like that ... </small></p>
