Web Service Development with J2EE
This tutorial results from the work of the C5 work component working group
in the Adaptive Services Grid (ASG),
an integrated project supported by the European Comission. It is based on the
HelloService example developed by the C5 member
HPI-DCL. The tutorial is part of the ASG software development kit (SDK) and explains
how to use Eclipse and the modified
JBossIDE integrated with the SDK for developing an
Enterprise Java Beans 2.1
(EJB) based web service and hosting it on a
JBoss application server.
You can download the HelloService example as a complete Eclipse
project containing the Java sources as well as the necessary build scripts.
The ASG SDK is actually not available for the public, but with the help of this document you should
be able to collect the relevant tools by yourself.
Please contact Alexander
Saar for further questions or comments.
Contents
Eclipse Project Setup
Hello Service Sample
Service Deployment & Packaging
The first step to setup your Eclipse development environment for developing J2EE
based web services. Note that the steps described in this section are unnecessary if
you have downloaded the complete ASG SDK, because the HelloService sample is part of
the SDK distribution.
Furthermore the SDK already contains a modified version of the JBossIDE, so it is not
necessary to modify it by yourself.
Download the HelloService sources and extract it to any location on your
computer, e.g. your default Eclipse workspace folder. After that right click on your
package explorer and choose Import... > Existing Project into Workspace. Select the
folder where you have extract the sources of the example and finish the import. If not already
present, you have to download and install the JBossIDE if you want to use their XDoclet,
Packaging, JBoss Deployment & Debugging support instead of using Ant directly.
As described before the SDK comes with a modified version of the JBossIDE (1.4.0). The modifications
are necessary if you want to use the actual version of XDoclet (1.2.2) which support EJB 2.1, because
the current version of the JBossIDE includes version 1.2.1 of the XDoclet distribution. Note that instead
of modifying the JBossIDE it is also possible to to use the needed build scripts directly.
There are three steps to integrate the actual XDoclet version with your JBossIDE.
Download XDoclet 1.2.2 and copy the following JARs to $ECLIPSE_HOME/plugins/org.
jboss.ide.eclipse.xdoclet.core_1.4.0.
xdoclet-1.2.2.jar
xdoclet-ejb-module-1.2.2.jar
xdoclet-jboss-module-1.2.2.jar
xdoclet-wsee-module-1.2.2.jar
xdoclet-xdoclet-module-1.2.2.jar
After copying the JARs you have to edit the
$ECLIPSE_HOME/plugins/org.jboss.ide.eclipse.xdoclet.run_1.4.0/resources/reference.xml
so that the JBossIDE knows the new supported doclet tasks. Listing 1 shows an excerpt
from reference.xml that illustrates how to insert the Wsee doclet. As
you can see you have to declare the tasks you want to used as well as the supported
subtasks and attributes. You can download an already adjusted version of the
reference.xml here. For a complete list of the supported
tasks see the XDoclet
manual.
Listing 1: reference.xml
<task name="wseedoclet" className="xdoclet.modules.wsee.WseeDocletTask" used="true">
<attribute name="wseeSpec" used="false"/>
<attribute name="jaxrpcMappingFile" used="false"/>
<attribute name="wsdlFile" used="false"/>
<attribute name="packageNamespaceMappings" used="false"/>
<attribute name="excludeTags" used="false"/>
<attribute name="destDir" used="false"/>
<attribute name="mergeDir" used="false"/>
<attribute name="force" used="false"/>
<attribute name="verbose" used="false"/>
<attribute name="addedTags" used="false"/>
<element name="configParam" displayName="configParam" used="true">
<attribute name="name" used="true"/>
<attribute name="value" used="true"/>
</element>
<element name="deploymentdescriptor" displayName="deploymentdescriptor" used="true">
<attribute name="description" used="false"/>
<attribute name="displayName" used="false"/>
<attribute name="largeIcon" used="false"/>
<attribute name="name" used="false"/>
...
The last step is to instruct the JBossIDE to load the xtags.xml
tag descriptors of the new XDoclet modules and to create some templates
for auto completion of XDoclet tags. In the Eclipse main menu select
Window > Preferences > JBossIDE > Xdoclet > Code Assist > Refresh XDoclet
Data to refresh the tag descriptions. After that select Code Assist
> Temlates and modifiy the existing templates or create some new templates
according to your needs. For example if you want to use the Wsee doclet you have
to create a new template tree and add the wsee specific tags.
Now the setup of our IDE is done and we are ready to take a look at the HelloService example.
The HelloService sample consists of the EJB that implements procedures to fulfill the service
specification, the needed build scripts as well as some additional templates that can be used
to generate the service description in WSDL format.
Listing 2 shows the source of the HelloService implementation bean. The important things to examine
are the XDoclet tags (ejb.bean, ejb.interface, wsee.port-component) and the implementation of the
service specification. In this case the implementation of the service specification is provided by
the sayHello() method. All other methods are default EJB implementation stuff and will not considered
in this tutorial.
Listing 2: HelloBean.java
...
/**
* A simple session bean for demonstration of
* Web Services with J2EE.
*
* @ejb.bean
* name="HelloBean"
* display-name="Hello"
* description="A simple hello world bean."
* jndi-name="ejb/Hello"
* type="Stateless"
* view-type="service-endpoint"
*
* @ejb.interface
* service-endpoint-class="de.hpi.dcl.asg.interfaces.HelloEndpoint"
*
* @wsee.port-component
* name="HelloEndpointPort"
*/
public class HelloBean implements SessionBean
{
...
/**
* Hello world business interface method.
*
* @ejb.interface-method view-type = "service-endpoint"
*/
public java.lang.String sayHello()
{
return("Hello World!");
}
}
The important class level tags are described below. For a complete list of the supported
tags see the XDoclet
tag reference.
ejb.bean
Contains default EJB specific entries like name, description,
JNDI name, EJB type or view type. It is important to set the
EJB type to stateless, because web services are only supported
for stateless EJBs. Furthermore the view-type must be set to
service-endpoint to generate only the <service-endpoint>
entry in the EJB deployment descriptor, because the JBoss application
server does not like remote or local interface entries combined
with service endpoint entries.
ejb.interface
Defines the beans service endpoint interface (SEI) fully qualified name. The SEI will
be generated later by the EJB doclet. The included EJB doclet configuration generate a
SEI by replacing the name suffix Bean with Endpoint, e.g. HelloBean
will be replaced with HelloEndpoint, and substiuting the ejb part of the package
name with interfaces.
wsee.port-component
Defines the name of the port component assigned with the bean. If you want to generate
the WSDL service description by using the templates provided by the HelloService
sample, you have to follow the convention that the name of the port component must
be the name of the SEI with an appended Port, e.g. HelloEndpointPort from
listing 2.
The important method level tags for the service implementation methods are:
ejb.interface-method
Describes the view type of the interface method. According to the class level tag
ejb.bean the view type of the sayHello() must be set to
service-endpoint.
Before we can start with the generation of the necessary interfaces and deployment descriptors, we
have to set the needed build variables in the xdoclet-build.properties configuration file.
These variables are eclipse.home and jboss.home.
After setting the build variables you can generate the deployment descriptors for the service bean.
The needed deployment descriptors are ejb-jar.xml, jboss.xml and webservices.xml.
Generation of the the JAX-RPC mapping file and the WSDL service description file are also included
with XDoclet, but at the time it lacks because the template files are not full. We will generate the WSDL
later by using some additional templates provided by the HelloService sample. The JAX-RPC mapping file
is very simple for non-complex services, so the sample sources contain a complete mapping file
(ejb-jar.xml) that must not be modified for running this simple example.
To generate the deployment descriptors right click on the project and select Run XDoclet. After
that you should see the generated files in the src/META-INF directory. Additionally the SEI was also
generated. To see which settings must be present to generate the deployment descriptors and interfaces right
click on the project and select Properties > XDoclet Configurations > EJB-Configuration. Now you can
browse the doclet tasks and their settings. A detailed description of the doclet tasks and their settings
is available at the XDoclet home page.
The last generation step is the generation of the WSDL service description. This can be done by running Ant
on the generate-wsdl-script.xml. Therefore right click on generate-wsdl-script.xml and select
Run > Ant. The script then generates a new build script called wsdl-build.xml from the provided
XDoclet template resources/wsdl-build.xdt. The new script contains an Axis Java2WSDL task for the SEI and is
startet automatically by the generate-wsdl-script.xml after the generation. The wsdl-build.xml
generates the WSDL service description from the template resources/template.wsdl. The result of this
is the service WSDL description resided in src/META-INF/wsdl/service.wsdl.
Now all needed files are present and we can start with the packaging and deployment of the sample.
To create the deployable JARs right click on the project and select Run Packaging. This starts the
packaging mechanisms of the JBossIDE and generates the deployable JAR under build/HelloService.jar.
The packaging settings can be explored by right click on the project and selecting Properties > Packaging
Configurations. Figure 1 illustrates the structure of the resulting JAR.
Figure 1: Service JAR structure
The new generated JAR can now be deployed on the JBoss application server. But first, we have to setup the JBoss
debug configuration. To do this right select Run > Debug... in the main menu. After that right click on
Configurations > JBoss 4.0.x and select New. Enter a name and the path to the JBoss home directory
for the configuration. Additionally select the Classpath tab and add $JAVA_HOME/lib/tools.jar and
$JBOSS_HOME/bin/run.jar to ensure that the server works correctly. Now you can run the debug configuration.
You should see the server starting up and some startup information in the console tab. If you have downloaded the
ASG SDK you only have to set the $JBOSS_HOME, because a JBoss configuration comes already with the SDK.
To deploy the service on the server right click on the JAR and select Deployment > Deploy To.... Select the
JBoss configuration you have created previously and press OK. After that open your browser and go to
http://localhost:8080/ws4ee/services. You should see a page like
shown in figure 2.
Figure 2: The service at localhost
Your service is now deployed and is ready for use by some clients.
| 
