Installation

Download one of the jibx-ws packages:

  • The minimal zip file. This does not include any dependencies. The dependencies can be obtained:
    • from an existing JiBX installation, or
    • by using the supplied Ant script to download all required dependencies using Ivy, or
    • in the case of the starter project, by using the supplied Maven or Gradle builds.
  • Or the with-deps zip file. This includes all dependencies that are required to run all examples and build JiBX/WS.

Unpacking the zip file will create a jibxws directory that contains the distribution files, including a complete copy of this documentation in the /docs directory. The /build directory provides the full JiBX/WS source and the actual Ant build file, while the /starter and /examples directories contain the starter and example applications (with their own build files). The jibx-ws.jar file containing the compiled JiBX/WS code is in the /lib directory.

The jar files that JiBX/WS depends on are in the /dep-lib folder. JiBX/WS can be used without the Spring Framework, however if you do wish to use it with Spring, the additional jars are in the /spring-lib folder.

Minimal Distribution

If using the minimal distribution, JiBX/WS requires the jibx-bind, jibx-extras, jibx-run and xbis-jibx jars from the JiBX installation. There are 4 configuration options:

  1. Copy these jars to the dep-lib directory of the JiBX/WS distribution (jibxws/dep-lib), or
  2. Install JiBX/WS as a direct child of the JiBX installation (JiBX/WS will check the jibxws/../lib directory), or
  3. Set the JIBX_HOME environment variable to the home of the JiBX installation (JiBX/WS will check the $JIBX_HOME/lib directory), or
  4. Edit the build/ant/common.xml Ant script to set the path directly.

Alternatively, the easiest way to install all the jars that JiBX/WS depends on is to run the "ant retrieve" target from the build folder of the download. This target installs and uses Ivy to download the dependencies. The ivy.xml file describes the dependencies.

Prerequisite Knowledge

In order to use JiBX/WS, you'll need at least a basic understanding of JiBX.

The starter application contains a manually created JiBX binding file. If you are not using existing binding files, the recommended approach is to use the JiBX generator tools. These provide a simple, flexible means for generating bindings, and will also generate an XML schema definition if starting from code, or the Java data model if starting from an XML schema.

Starter Application

The starter application, in the /starter folder, illustrates these basic steps required to build a JiBX/WS application:

Step Example file (in starter folder)
Create Java classes representing the message payloads to be exchanged src/main/java/org/jibx/ws/starter/*.java
Create JiBX binding definitions to describe how to transform these Java classes to/from XML src/main/jibx/hello-binding.xml
Create a Java service src/main/java/org/jibx/ws/starter/server/HelloService.java
Create a service definition src/main/webapp/WEB-INF/welcome-service.xml
Configure the server with a web.xml file referencing the service definition src/main/webapp/WEB-INF/web.xml
Create a Java client to invoke the service src/main/java/org/jibx/ws/starter/client/HelloClient.java

These steps assume the application is running SOAP over HTTP using a text encoding. For other options, configuration changes are required. To run over TCP, JiBX/WS includes a TcpServer, which does not require the service to be packaged as a .war file.

Building and running

The Starter Application can be run using Ant, Maven or Gradle. See /starter/README.html for further details.