This howto will guide you to simplifying web service endpoint development using the JSR181 web service metadata programming model. You can find out more information at JSR 181 Web Service Metadata.

You still have the choice of using the WebService cartridge if you wish to expose session beans or POJOs. Just follow the instructions here.

Using the Andromda Project Generator, you must enable WebServices and if you selected 'ejb3' for the persistence type, then you will get an optional question to enable JSR 181 annotated metadata for the project.

The project generator will add the following properties to your andromda.xml ejb3 namespace.

        <namespace name="ejb3">
                <property name="webServiceEnabled">true</property>
                <property name="webServiceContextRoot">/${application.id}-ws</property>
                <property name="webServiceUrlPattern">/services</property>
The webServiceEnabled property allows you to switch between the WebService cartridge and the EJB3 JSR181 metadata model. The webServiceContextRoot and webServiceUrlPattern allows you to modify the construction of the URL for the webservice endpoints.

The following is a very simple example of a session bean exposing all it's operations and another session bean exposing only 1 of it's operations. This is achieved by modeling the <<WebService>> stereotype on the UserService session bean and <<WebServiceOperation>> on the addUser operation in UserEndPointService session bean. Modeling this is similar to the WebService cartridge process. The EJB3 cartridge introduces a few extra tagged values. The example below models the andromda_webservice_operation_result_name tagged value on the addUser operation in UserService.

  • Auto-generated source that does not need manual editing
  • Auto-generated source that should be edited manually
  • File that is affected by the modifications applied in this section
  • User.java
  • UserDao.java
  • UserDaoBase.java
  • UserDaoImpl.java
  • UserDaoException.java
  • ServiceDelegateBase.java
  • UserEndPointServiceBase.java
  • UserEndPointServiceBean.java
  • UserEndPointServiceRemote.java
  • UserEndPointServiceDelegate.java
  • UserEndPointServiceException.java
  • UserEndPointServiceWSInterface.java
  • UserServiceBase.java
  • UserServiceBean.java
  • UserServiceRemote.java
  • UserServiceDelegate.java
  • UserServiceException.java
  • UserServiceWSInterface.java
  • UserException.java

The UserServiceBean and UserEndPointServiceBean implementations contain the @WebService annotation defining the endpointInterface property that references the web service interface UserServiceWSInterface and UserEndPointServiceWSInterface correspondingly, containing all other annotations. Default values are provided via namespace properties, but you can override them using tagged values.

WebService Client

Here is a very brief example on calling a web service endpoint with the help of JBoss client libraries.

Create a configuration file for generating the client side artifact jaxrpc-mapping.xml. The config below assumes JBoss is running on the localhost and you have deployed your project exposing web service endpoints on the location specified below.

<configuration xmlns="http://www.jboss.org/jbossws-tools">
    <wsdlToJava wsdlLocation="http://localhost:8080/howtomodel-ws/services/UserService?wsdl">
        <mapping fileName="jaxrpc-mapping.xml"/>

Now run the wstools binary (available in JBoss 5.x or from JBoss 4.0.4-CR3 onwards) on this configuration file.

jboss-inst/bin/wstools.sh -cp ".;./core/target/src" -config jbosswsConfig.xml

This will create the jaxrpc-mapping.xml artifact.

The client can invoke exposed operations like so.

URL wsdlURL = new URL("http://localhost:8080/howtomodel-ws/services/UserService?wsdl");
org.jboss.ws.jaxrpc.ServiceFactoryImpl factory = new org.jboss.ws.jaxrpc.ServiceFactoryImpl();
File mappingFile = new File("jaxrpc-mapping.xml");
Service service = factory.createService(wsdlURL, null, mappingFile.toURL());
UserServiceWSInterface port = (UserServiceWSInterface)service.getPort(UserServiceWSInterface.class);

Helpful Hints

Do not over-load operations as this will cause conflicts when exposing similarly named session bean operations as web service endpoints.

In the example above, UserServiceBean is generated once only since it contains the session bean implementation. Therefore, the @WebService annotation is enabled on generation of the class. To stop exposing this bean, you must manually comment out the following in UserServiceBean.java:

@javax.jws.WebService(endpointInterface = "org.andromda.test.howto18.a.UserServiceWSInterface")

Currently, the following tags are not available in the WebService profile; therefore, you must add them to your model if you wish to use them.


To see how you can use embedded value objects as part of your entities, click here.