SOS

Ive spent a few days playing around with EJB 3.0 and JBoss WebServices. After JBoss was J2EE-1.4 certified they decided to develop their own SOAP stack independent of Apache Axis. This implementation is JBoss 4.04GA. Here I explain how to set up a working example of JBossWS in Eclipse. I also highly recommend you download Eclipse 3.2 and WTP 1.5, which contains better WSDL and XML editors and a better J2EE view for launching and managing your JBoss Server.

• Download the latest version of the JBoss Application Server 4.04. Usually when I install a JBoss AS I download a zip file and unzip it in my JBoss_Home folder however to correctly configure the JBoss WebServices components it is necessary to to run the JBoss AS 4.04 GA Installer. The "Run Installer" option is the last one on the right hand side. Using the former approach causes configuration nightmares later on.
• You are given a list of installation options (some of which are; "all"- full J2EE 1.4 server with enterprise extensions, "default" - base J2EE 1.4 server profile, "ejb3" - An ejb3 profile supporting the full ejb3 spec with tomcat). For the purpose of JBoss WebServices developement it is only necessary to chose "ejb3".
  
• After finishing the installation you have successfully installed JBoss AS 4.04 and JBossWS 1.0.0 GA. However there a relatively critical bug found in JBossWS 1.0.0 where the application continously resolves an external URL meaning that deployed WebServices behind a firewall or offline wont work. To this end the next step is to install the latest JBossWS 1.02 GA
• After downloading the zip file, no installer this time, unzip JBossWS to it's JBossWS_home directory. Its not necessary to install it in the JBoss AS 4.04 directory. One thing to take note of however, in the zip file there is no root directory so you need to create a dedicated JBossWS directory otherwise it gets very messy.
• Open \Install.txt and follow the directions.
• The first line reads: "Copy lib/jbossws-client.jar to /client/" but should read: "Copy lib/jboss-jdk1.5/jbossws-client.jar to /client/"
• Dont forget to download the latest jboss-xml-binding.jar as explained in point 3
• Unzip \jbossws-samples-1.0.2.GA.zip to your eclipse work space. This approach is better than the eclipse import approach as it means you are not overwriting the original directory.
• Now start your Eclipse IDE and select the eclipse workspace (where you extract the JBossWS samples directory)
• From the menu option "File" chose "new java project", in the "Create a Java Project" wizard, choose "Create new project in workspace", insert the exact name of the folder that you extracted into your workspace (jbossws-samples-1.0.2.GA). It is always good practice in the "Create a Java Project" wizard to select the last radio button under "project layout" - "create separate source and output folders". You will now see a message at the bottom of the wizard "The specified location already exists...". Click next and Eclipse will create a JBossWS project
• Open your project in navigator. Rename ant.properties.example to ant.properties, it is defined like this in the build file imported-build.xml found under the "common" direcory. This file is imported in the build.xml
• In ant.properties update the variable jboss.jdk15.home with your JBoss AS 4.04 GA directory. The other variables do need to be adjusted (assuming you are using the default container)
• Run the clean task
• In the Navigator or Package view the EJB3 Bean code can be seen in the JSR181 directory. Here we have the bean code (EJB3Bean01.java), the Remote Interface (EJB3RemoteInterface.java) and an interface used by client deployment (EndpointInterface.java)
• Note we have no Home Interface as we would have had in J2EE 2.1. A remote client finds relevant bean using the remote business Interface. From the specification section 3.2.1: In EJB 3.0, a remote client accesses a session bean through the bean’s remote business interface. For a session bean client and component written to the EJB 2.1 and earlier APIs, the remote client accesses the session bean through the session bean’s remote home and remote component interfaces. Compatibility Note: The EJB 2.1 and earlier API required that a remote client access the session bean by means of the session bean’s remote home and remote component interfaces. These interfaces remain available for use with EJB 3.0 Therefore we no longer have the factory pattern of J2EE 2.1 where we use a home interface to create a remote interface, rather we have a handle on the remote interface from the outset. This is much more similiar to what CORBA and Java programmers have been traditionally used to.
• Also note that the bean type is now defined by an annotation, for example in EJB3Bean01.java we have defined "@Stateless" which is a standard JSR 181 annotation now used in EJB 3.0
• As well as other JSR 181 Annotations we also have JBoss specific annotations; @RemoteBinding, @PortComponent, @SecurityDomain, @HandlerChain
• The following libraries are required on the classpath to get the project to build, from /client directory jbossall-client.jar, jboss-jaxrpc.jar, jbossws-client.jar, jboss-ejb3x.jar
• Build the project by running the main task in build.xml. If you view the project outside of eclipse in Internet Explorer you will see this genereated the output directory containing amongst others the lib folder. In the lib folder an *.ejb3 file is generated. This is the deployable ejb bean. Both *.ejb3 or *.jar extensions can be used in EJB 3.0. Deploy the bean in the JBoss/Server/default/deploy directory
• Go to http://localhost:8080/jbossws to view a list of deployed services. */jbossws-samples-jsr181ejb/EJB3Bean01?wsdl will be listed as a deployed service. If you click on the service you'll be prompted for a username and password.
• The authentication requirements are now defined by JBoss specific annotations in the bean code. (Previously this was done by config in JBoss). The (JSR181 annotaion) @RolesAllowed defines the role "friend". The annotation @SecurityDomain defines the security domain as JBossWS. In the login-config.xml we can see that jbossws-user.properties defined as the user.properties file which contains the username/password kermit/thefrog
• Submit the username and password on the webclient to view a generated WSDL that represents the JBoss WebService Bean.
• As a further step, its useful to take the generated WSDL above and create a simple client (in my example I used Axis).
• Taking the generated WSDL as is and running WSDL2Java to generate the client causes some problems as the WSDL is missing necessary definitions, in the JBoss example the following had to be added to the generated WSDL:
  targetNamespace="http://org.jboss.ws/samples/jsr181ejb"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:tns="http://org.jboss.ws/samples/jsr181ejb"
  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  


• After creating the client it is also necessary to add the username and password properties:
  endpt_i = (EndpointInterface) locator.getPort(
  new QName("", "EndpointInterfacePort"),
  EndpointInterface.class
  );
  
  ((Stub)endpt_i)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,
  endpointUrl);
  ((Stub)endpt_i)._setProperty(Stub.USERNAME_PROPERTY, "kermit");
  ((Stub)endpt_i)._setProperty(Stub.PASSWORD_PROPERTY, "thefrog");
  

The above 2 projects (The Jboss sample and Axis Client) I can make available to anyone who is interested.

Now Im off to configure Apache CeltiXfire!