JBossWS - Setup your IDE

    Even if you can create, build and deploy your web service application with a simple text editor and a shell console, a properly configured IDE and/or Ant build file might help you and speed up your development.

     

     

    JBossWS-CXF Testsuite Eclipse project

     

    The JBossWS-CXF Samples testsuite covers the web service functionalities it currently supports. Running the tests in an IDE is an effective way to start your web service training.  This article describes how to install a JBossWS-CXF source code distribution as an Eclipse project, build the testsuite, deploy it and run it on a JBoss server configured in the IDE.

     

    1 Prerequisites

     

    1.1 Red Hat JBoss Developer Studio or Eclipse

    There are several choices of Eclipse releases.  The directions provided here will work for any of these releases.  I recommend using the Red Hat JBoss Developer Studio Edition [1]. It is built on Eclipse [2] and includes a broad set of features that will help you quickly get started developing java applications on JBoss.  This article uses Red Hat JBoss Developer Studio 8.

     

    Red Hat JBoss Developer Studio 8 (build on Eclipse Luna)

    Red Hat JBoss Developer Studio 7 (build on Eclipse Kepler)

    Red Hat JBoss Developer Studio 6 (build on Eclipse Juno)

    Eclipse (Luna)

    Eclipse (Kepler)

    Eclipse (Juno)

     

    1.2 JBossWS-CXF source code distribution bundle

    Download one of the JBossWS-CXF source code distribution bundles [3].  You must use a version that is compatible with the version of the JBoss server it will be run on [6].  This article uses version JBossWS-CXF 4.3.x.

     

    Each JBossWS-CXF distribution supports more than one JBoss server version.  A unique property for each supported version is defined in the build.xml file in the bundle's root directory.  Search the build.xml file for the ".home" text.  Names such as jboss720.home and wildfly810.home will be found.  This means the bundle supports version JBoss AS 7.2.0 and WildFly 8.1.0 respectively.

     

    Compatibility table

    JBossWS-CXF version
    Server version / property name
    JBossWS - CXF 4.3.x

    JBoss AS 7.2.0 / jboss720.home

    WildFly8.0.0     / wildfly800.home

    WildFly8.1.0     / wildfly810.home

    JBossWS - CXF 4.2.x

    JBoss AS 7.1.2 / jboss712.home

    JBoss AS 7.1.3 / jboss713.home

    JBoss AS 7.2.0 / jboss720.home

    WildFly8.0.0     / wildfly800.home

    JBossWS - CXF 4.0.x/4.1.x

    JBoss AS 7.1.1 / jboss711.home

    JBoss AS 7.1.2 / jboss712.home

    JBoss AS 7.1.3 / jboss713.home

    JBoss AS 7.2.0 / jboss720.home

    JBossWS - Native 4.0.x

    JBoss AS 7.0.1 / jboss701.home

    JBoss AS 7.0.2 / jboss702.home

    JBoss AS 7.1.0 / jboss710.home

    JBoss AS 7.1.1 / jboss711.home

     

    1.3 JBoss AS or WildFly Community Edition

    Download and install the JBoss AS [4] or WildFly [5] version compatible with the installed JBossWS-CXF distribution bundle.  This article is using WildFly 8.1.0.

     

     

    2 Tasks to Setup JBossWS-CXF in Eclipse

    There are 3 tasks to setup JBossWS-CXF in Eclipse.

      1. Import the JBossWS-CXF distribution source code.
      2. Create a server configuration
      3. Create 2 "External Tool" commands

     

    2.1. Import the JBossWS-CXF distribution source code

      1. Start Red Hat JBoss Developer Studio
      2. Select File | Import.. | Maven | Existing Maven Projects
      3. Click Next

    s1-Import-Existing-Maven-Projects.png

     

     

      1. Browse to the root directory of the JBossWS-CXF source distribution.
      2. All pom.xml files should be selected.
      3. I am using the default project name.  Set it as you like.
      4. Click Finish

    (This is a large project.  It will take time to load.  Be patient.)

     

     

    s2-Import-Maven-Project.png

     

     

    You may notice that Eclipse flags "Problems" s4-Problem-icon.pngand "Warnings" s5-Warning-icon.pngon some of the modules.  Ignore this.  JBossWS-CXF is an Apache Maven based project, but it is not a traditional maven project.  It does not build with the standard maven goals. Instead JBossWS-CXF defines maven profiles to perform the requisite compile and deployment of tests from the testsuite and ant scripts to configure the server.

     

    (Optional) Disable automatic build of the project.  Uncheckmark the auto build feature.

      1. Select Project | Build Automatically

     

     

     

    s3-project-imported.png

     

    2.2. Create a server configuration

      1. Click the Server tab to configure the JBoss server to use.
      2. Click the link.

     

     

     

    s3.1-project-imported.png

     

    Enlarge the New Server dialog.  This makes it easier to scroll through the list of servers.  Select the server version you are using.  This article is using WildFly 8.1.0.

      1. Select JBoss Community |  WildFly 8.x.
      2. Click Next

     

     

    S6.1-New-Server-screen-1.png.png

     

     

    There are no adapter changes.

      1. Click Next

     

     

    S6-New-Server-screen-2.png

     

     

    (I've changed the name, to wildfly-8.1.0.Final.  This is optional.)

      1. Set the Home Directory to the installation directory of the JBoss server.
      2. Click Next

     

     

    S6.1-New-Server-screen-3.png

     

     

    No resources need to be modified.

      1. Click Finish

     

     

    S6-New-Server-screen-4.png

     

     

    The server is now listed on the Servers tab.

     

     

    S6.1-New-Server-screen-5.png

     

     

     

    2.3 Create 2 "External Tool" commands

     

    Two external tool commands need to be created.  One is an ant commend to install JBossWS-CXF modules in the server and the other is a maven command to run the testsuite.  Both commands require input arguments.  Several of the arguments are server version specific. See the comment about how to find the supported server versions in the JBossWS-CXF distribution bundle.  The ant and maven commands require the designation of the JBoss home directory.  It is specified as an ant property/value pair.

     

    -D<server version>.home=<absolute path to the JBoss installation directory>

     

    example

     

    -Dwildfly810.home=/home/rsearls/j1/wfly-8.x/wildfly/build/target/wildfly-8.1.0.Final

     

     

    2.3.1 Ant command

      1. Select Run | External Tools | External Tool Configurations ...
      2. Select "Ant Build" and the "New Launch Configuration" icon.
      3. Give this command a name.  (antWfly810 is being used here.)

     

     

    s7-external-tools-config-1.png

     

    The build.xml file is in the jbossws-cxf module.

      1. In the "Buildfile" area (see screen shot) select the "Browse workspace" button
      2. Select build.xml in the right-hand box.
      3. Click OK.

     

     

    s7-external-tools-config-2.png

     

     

    Designate the root directory from which the ant command is to be run.

      1. In the "Base Directory" area (see screen shot)  select the "Browse workspace" button
      2. Select the jbossws-cxf module name.  This is the JBossWS-CXF project root.  The ant command must be run from here.
      3. Click OK

     

     

    s7-external-tools-config-3.png

     

     

    The ant command requires 2 input arguments.

      • The JBoss server installation location specified by property <server version>.home (e.g. jboss720.home wildfly800.home)
      • The ant target name deploy-<server version>.  (e.g. deploy-jboss720 deploy-wildfly800)

     

    1. Copy this text into the "Arguments" text field (see screen shot).

    -Dwildfly810.home=/home/rsearls/j1/wfly-8.x/wildfly/build/target/wildfly-8.1.0.Final  deploy-wildfly810

    2. Click Apply

    3. Click Run     (This will run the ant command that configures the JBoss server with the needed JBossWS-CXF modules.  This command only needs to be run once.)

     

     

    s7-external-tools-config-4.png

     

     

    2.3.2 Maven Command

      1. Select Run | External Tools | External Tool Configurations ...
      2. Select "Program" and the "New Launch Configuration" icon.
      3. Give the command a name.  (mvnWfly810 is used here.)

     

     

    s7-external-tools-config-mvn-1.png

     

     

    In the Location area designate the absolute path to the localhost's maven command.

      1. Click "Browse File System" Button

     

     

    s7-external-tools-config-mvn-2.png

     

     

    Designate the root directory from which the maven command is to be run.

      1. In the "Working Directory" area select the "Browse workspace" button
      2. Select the jbossws-cxf module name.  (This is the JBossWS-CXF project root.  The maven command must be run from there.)
      3. Click OK

     

     

    s7-external-tools-config-mvn-3.png

     

     

    The maven command requires 3 input arguments.  There is an optional fourth argument.

      • The JBoss server installation location specified by property <server version>.home (e.g. jboss720.home, wildfly800.home)
      • The maven profile to use, -P<server version> (e.g. -Pjboss720, -P jboss701, -Pwildfly800)
      • The maven execution path to use, "integration-test"
      • (optional) One or more individual tests can be specified to be run. A comma separated list of fully qualified class names within quotation marks are designated via property -Dtest  (e.g. -Dtest="org.jboss.test.ws.jaxws.cxf.jbws3827.JBWS3827TestCaseForked,org.jboss.test.ws.jaxws.samples.wsse.policy.oasis.WSSecurityPolicyExamples23xTestCase")

     

      1. The testsuite takes quite a while to run.  It is suggested to initially run a single test using the -Dtest argument to confirm your setup is working and then run the full testsuite.  Copy this text into the "Arguments" text field (see screen shot)

    -Dwildfly810.home=/home/rsearls/j1/wfly-8.x/wildfly/build/target/wildfly-8.1.0.Final -Pwildfly810  integration-test -Dtest="org.jboss.test.ws.jaxws.cxf.jbws3827.JBWS3827TestCaseForked"

      2. Click Apply

      3. Click Close  (Do not click Run yet.  The JBoss server needs to be started first.)

     

     

    s7.1-external-tools-config-mvn-4.png

    3 Run the Testsuite

    The JBoss server must be started before running the testsuite

      1. Select the Server tab
      2. Select server WildFly 8.x
      3. Click the Start icon

    Check that the server started up cleanly in the Console tab.

     

     

    S9-valid-server-startup.png

     

    Run the testsuite using the mvnWfly810 command.

      1. Select Run | External Tools | External Tool Configurations ...
      2. Select mvnWfly8100
      3. Click Run

     

    S9-running-testsuite.png

     

    Now that the basic setup has been confirmed, edit the mvnWfly810 command and remove the -Dtest="org.jboss.test.ws.jaxws.cxf.jbws3827.JBWS3827TestCaseForked" argument and run the full testsuite.

      1. Select Run | External Tools | External Tool Configuration ...
      2. Select mvnWfly810
      3. Edit the Argument field.
      4. Click Apply
      5. Click Run  (Unless you stopped the server it should still be running, so just run the testsuite.)

     

     

     

     

     

    JBossWS user project generator

    Since 3.0.1 (Native, Metro, CXF)

    In order to increase the web service user productivity, JBossWS native ships with an Ant-based web service project generator. This can be used to automatically create a simple project along with an Ant build file to compile and deploy it as well as a basic Eclipse configuration (further IDEs might be supported in future). The most commonly required libraries are referenced from the user specified JBoss application server home, so that the user simply needs to code its web service provider / consumer application.

    Configuring a new project

    The JBossWS user project generator is triggered by the main JBossWS build available in every binary release. You just need to run the setup-new-project target and answer to a few questions about the project you'd like to create:

    • project workspace: this is where the generator will create your project directory
    • project name
    • project type: this can be either jar or war depending on your need for EJB3 components support
    [alessio@localhost jbossws-native-dist]$ ant setup-new-project
    Buildfile: build.xml
    
    tests-prepare:
         [echo] 
         [echo] -----------------------------------------------
         [echo] jboss.home   = /dati/jboss-4.2.2.GA
         [echo] excludesfile = ${excludesfile}
         [echo] java.home    = /usr/java/jdk1.5.0_13/jre
         [echo] jboss.bind   = localhost
         [echo] -----------------------------------------------
    
    tests-classpath-jboss50:
    
    tests-classpath-jboss42:
    
    tests-classpath:
    
    init-project-properties:
    
    setup-new-project:
         [echo] -------------------------------------------------
         [echo]   Welcome to the JBossWS user project generator
         [echo] -------------------------------------------------
         [echo] 
        [input] Enter your Java project workspace (the directory that contains your projects)  [C:/Projects]
    /dati/project/ws
        [input] Enter the project name  [myproject]
    TestProject
        [input] Is this project deployed as an JAR (with EJB3 components) or a WAR (with no EJB3 support)  ([jar], war)
    jar
    [propertyfile] Creating new property file: /home/alessio/dati/jbossws/stack/native/trunk/output/jbossws-native-dist/user-project.properties
         [echo] 
         [echo] Your project settings have been saved in file 'user-project.properties'.
         [echo] Please type 'ant create-project' to create the new project.
    
    BUILD SUCCESSFUL
    Total time: 32 seconds

    Once this has been executed, the generator writes your settings to the user-project.properties file (it creates it during the first run). As you can see the script gets the JBoss installation home and the configuration/instance to use from the current ant.properties file.

    [alessio@localhost jbossws-native-dist]$ cat user-project.properties 
    #Generated by JBossWS user project setup
    #Fri Mar 14 10:05:47 CET 2008
    project.name=TestProject
    project.jboss.home=/dati/jboss-4.2.2.GA
    project.type=jar
    workspace.home=/dati/project/ws
    project.jboss.conf=default

    Creating the project

    Given your settings, creating the project is straightforward. You just need to run the create-project target of the JBossWS main build:

    [alessio@localhost jbossws-native-dist]$ ant create-project
    Buildfile: build.xml
    
    tests-prepare:
         [echo] 
         [echo] -----------------------------------------------
         [echo] jboss.home   = /dati/jboss-4.2.2.GA
         [echo] excludesfile = ${excludesfile}
         [echo] java.home    = /usr/java/jdk1.5.0_13/jre
         [echo] jboss.bind   = localhost
         [echo] -----------------------------------------------
    
    tests-classpath-jboss50:
    
    tests-classpath-jboss42:
    
    tests-classpath:
    
    init-project-properties:
    
    validate-settings:
    
    configure-project:
        [mkdir] Created dir: /dati/project/ws/TestProject/src/main/java
        [mkdir] Created dir: /dati/project/ws/TestProject/src/main/resources
         [copy] Copying 1 file to /dati/project/ws/TestProject
         [copy] Copying 1 file to /dati/project/ws/TestProject
    
    create-project:
         [echo] A basic webservice project named 'TestProject' has been created in the /dati/project/ws directory.
         [echo] It includes a simple Ant build file and references the required libraries.
         [echo] Please refer to http://jbws.dyndns.org/mediawiki/index.php?title=JBossWS for the authoritative documentation.
         [echo] 
         [echo] If you are an Eclipse user, import the project into Eclipse: right click in 
         [echo] 'Package Explorer -> Import...' and select 'General -> Existing Projects into Workspace'.
         [echo] Then click on 'Next' and set the root directory browsing to your workspace directory.
    
    BUILD SUCCESSFUL
    Total time: 0 seconds

    The generator simply creates a new project according to the settings in the user-project.properties file; the right libraries are referenced from the currently configured JBoss AS installation.

    Please note that different AS versions require different sets of libraries, thus it's important to carefully set the jbossws.integration.target properties in the ant.properties file before running this script.

    Using the project

    The new project comes with a simple Eclipse configuration you might want to import: right click in 'Package Explorer -> Import...', select 'General -> Existing Projects into Workspace', then click on 'Next' and set the root directory browsing to your workspace directory.

    An Ant build.xml file is also created and can be used both from command line and from Eclipse; it has the following targets:

    • compile: compiles the Java source code
    • copyclasses: copys the classes that were compiled by Eclipse
    • deploy: deploys to JBoss AS
    • dist: creates the application distribution archive
    • undeploy: undeploys from JBoss AS

    You're most probably going to need deploy and undeploy only.

    Your new basic project is ready; you can start creating your web service endpoint or client. Of course both the build file and the Eclipse configuration are meant to be the starting point for a common WS-enabled project; you may want to edit them according to your business requirements and/or fine setting preferences. For instance, one of the most common changes you're probably going to do is adding some proprietary libraries to the build: take a look at the generated libraries.xml file that is imported by the generated build.xml.

     

     

    References:

    [1] JBoss Developer Studio - Downloads

    [2] Eclipse Downloads

    [3] JBossWS Downloads - Latest (4.x) - JBoss Community

    [4] JBoss Application Server Downloads - JBoss Community

    [5] Downloads · WildFly

    [6] JBossWS - Supported Target Containers | JBoss Developer