Jboss Admin Tutorial: Web Services and JBoss

12. Web Services and JBoss

12.1. Web Services Overview

  • Web services is a new integration technology that allows applications on different systems to pass data back and forth
  • Web services are self-contained, self-describing, and modular applications that can be published, located, and invoked across the Internet
  • They can implement simple functions like a currency converter, or complicated business processes like ordering of books
  • Once deployed, other applications (and other web services) can discover and invoke it
  • Like RPC
  • Platform and technology independent (a client can be implemented in C and the web service can run within a J2EE app server)
  • Built on existing standards: HTTP and XML
  • Less efficient than other middleware technology (RMI, Jini, CORBA, DCOM etc.) but simpler and more ubiquitous (because it is based on HTTP)

12.2. Service Oriented Architecture


Platform elements:

  • SOAP (Simple Object Access Protocol): remote invocation - defines the envelope structure, encoding rules, and conventions for representing remote procedure calls and responses
  • UDDI (Universal Description, Discovery and Integration): It’s a mechanism used to publish Web Services
  • WSDL (Web Services Description Language): expression of service characteristics

12.3. Web Services With JAX-WS

  • Java API for XML-Based Web Services

    • Remote Procedure Calls over XML
    • Messages based on SOAP
    • Messages transmitted over HTTP
  • JAX-WS API hides the complexity of SOAP from the developers (makes it easier)

    • Runtime converts API calls and responses to/from SOAP messages
  • Also allows access to services that are not running on a Java platform

Although SOAP messages are complex, the JAX-WS API hides this complexity from the application developer. On the server side, the developer specifies the remote procedures by defining methods in an interface written in the Java programming language. The developer also codes one or more classes that implement those methods with annotations. Client programs are also easy to code. A client creates a proxy (a local object representing the service) and then simply invokes methods on the proxy. With JAX-WS, the developer does not generate or parse SOAP messages, the JAX-WS runtime takes care of all Java to/from SOAP transcoding.


JAX-WS is now included in Java SE 6. If you’re using Java SE 5, you’ll have to use JBoss libraries to compile and/or run client or web services.

12.4. Web Services on JBoss

  • On JBoss AS 5.x, Java EE components can act both as web service providers and consumers.
  • Java EE applications can expose a web service from

    • The EJB tier using a stateless session bean
    • The web tier using a plain Java object
  • Both server-side components and Java EE client applications have a standard way of declaring references to external web services

On JBoss, the support for web services is provided by deploy/jbossws.sar.

The HTTP transport is handled by the embedded Tomcat engine and the SAOP handling is provided by the embedded Apache’s Axis engine.

To view the list of all web services deployed on your server, go to http://localhost:8080/jbossws/services

When a Web Service is deployed, the WSDL contract is automatically generated.

12.5. JBoss Web Services Tools

  • JBoss AS ships with some tools that helps in the Web Services lifecycle development

    • wsprovide
    • wsconsume
    • wsrunclient
    • wstools

For the purpose of this class, we’ll only cover wsconsume, wsprovide and wsrunclient.


These tools are available for Windows (.bat) and Unix (.sh) systems.

12.5.1. wsprovide tool

  • When a developer create a Web Service for JBoss thanks to JBoss annotation, he can:

    • deploy it directly to JBoss and the WSDL is automatically generated
    • use wsprovide tool

      wsprovide –o output –c XXX –w com.example.CurrencyConverter
    • -o option specify the output directory for the generated file
    • -c option specify the classpath where you can find the endpoint class
    • -w option specify to generate the WSDL file
    • Finally com.example.CurrencyConverter is the endpoint class
usage: WSProvide [options] <endpoint class name>

-h, --help                  Show this help message
-k, --keep                  Keep/Generate Java source
-w, --wsdl                  Enable WSDL file generation
-c, --classpath=<path>      The classpath that contains the endpoint
-o, --output=<directory>    The directory to put generated artifacts
-r, --resource=<directory>  The directory to put resource artifacts
-s, --source=<directory>    The directory to put Java source
-q, --quiet                 Be somewhat more quiet
-t, --show-traces           Show full exception stack traces
-l, --load-provider         Load the provider and exit (debug utility)

Generate the WSDL from the end point class is called bottom-up development

12.5.2. wsconsume tool

  • Generate proxy classes (Java classes) that are used to communicate with the web services in an object-oriented way

    wsconsume -k -p com.example.client -o output
    • -k option specify Java classes generation
    • -p option specify the package name for the generated classes
    • -o option specify the output folder for your generated classes
    • in this example is where you can find the WSDL file
usage: org.jboss.wsf.spi.tools.cmd.WSConsume [options] <wsdl-url>

-h, --help                  Show this help message
-b, --binding=<file>        One or more JAX-WS or JAXB binding files
-k, --keep                  Keep/Generate Java source
-c  --catalog=<file>        Oasis XML Catalog file for entity resolution
-p  --package=<name>        The target package for generated source
-w  --wsdlLocation=<loc>    Value to use for @WebService.wsdlLocation
-o, --output=<directory>    The directory to put generated artifacts
-s, --source=<directory>    The directory to put Java source
-t, --target=<2.0|2.1>      The JAX-WS specification target
-q, --quiet                 Be somewhat more quiet
-v, --verbose               Show full exception stack traces
-l, --load-consumer         Load the consumer and exit (debug utility)
-e, --extension             Enable SOAP 1.2 binding extension

12.5.3. wsrunclient tool

  • wsrunclient invokes a JBossWS JAX-WS Web Service client
  • Builds the correct classpath and endorsed libs for you.
usage: wsrunclient.sh [-classpath <additional class path>] <java-main-class> [arguments...]

If you use JDK 6, JAX-WS is already included in it so you don’t need to use wsrunclient

12.6. Lab: Web Services

  • With the given my-ws.war web service, deploy it to JBoss.
  • Locate the automatically generated WSDL contract.
  • With the given my-ws-client.jar, run the client using wsrunclient, the client class name is com.marakana.ws.simple.client.Client