This chapter discusses about what JAX-WS is and how to get started with developing services using it. The focus of the book will mainly be on JBossWS a Web Service framework developed as part of WildFly (formerly known as JBoss Application Server), that implements the JAX-WS specification (JSR 224, Java API for XML-based Web Services 2.0). Most of what will be explained, especially in this chapter, still applies to any JAX-WS implementation, though.
You will get your hands on the following topics:
- A short introduction to Web Services
- How to easily create your first Web Service endpoint
- How to build and deploy Web Services applications (using Maven directly or IDEs)
JAX-WS is a Java API for producing and consuming SOAP-style web services. It is defined by the JSR-224 specification from the Java Community Process (JCP). It is actually possible to build also REST-style Web Services with JAX-WS (using @WebServiceProvider annotated classes), but that’s not the main goal of JAX-WS.
JAX-WS is the successor of JAX-RPC, an API for XML-based remote procedure call (RPC). The Reference Implementation (RI) for JAX-WS is part of the open source GlassFish project and is named Metro. The current version of JAX-WS is 2.2.x. JAX-WS is officially part of Java Enterprise Edition (Java EE) and is included in JDK since version 1.6.
JAX-WS endpoints can be published on any Java EE compliant application server (or at least implementing the JSR 224 specification); those include for instance WildFly, GlassFish, JBoss EAP, etc. It is also possible to publish JAX-WS endpoints on Servlet containers (like Tomcat) as well as on many HTTP servers (such as Jetty, Grizzly, Undertow) using the convenient Endpoint Publisher API.
Besides the Metro reference implementation, there are multiple alternatives for building JAX-WS services; the most known ones are Apache CXF and Apache Axis2, which are also leveraged by some JavaEE containers to offer Web Services functionality.
The JAX-WS implementation in WildFly comes from JBossWS, a Web Services Framework, which also implements JSR-109. JBossWS internally bundles most components of Apache CXF and provides additional functionalities and customized tooling.
Each vendor specific implementation usually adds features and configuration options to the plain JAX-WS API; however as long as the user sticks with standard JAX-WS API usage only, web services applications should be easily portable into a different container relying on a different -yet compliant- JAX-WS implementation.
Moreover JAX-WS uses standard technologies defined by W3C (such as SOAP or WSDL), which control the messages’ format, the way of describing published services, etc. Therefore, any JAX-WS endpoint can be invoked by proper clients developed with different frameworks or programming language.
Web Services are described using the standard Web Service Description Language (WSDL). This means one or more XML files containing information on the service location (endpoint address), service functionalities (operations), input/output messages involved in the communication and business data structure (usually in the form of one or more XML Schema definition). Recent specifications (like WS-Policy) allow more advanced service capabilities to be stated in the contract through WSDL extensions.
The communication between endpoints (described using WSDL) and clients is standardized by the SOAP specification; SOAP defines the envelope structure, encoding rules, and conventions for representing web service invocation and response XML messages.
The JAX-WS API hides the complexity of WSDL and SOAP from the application developer. On the server side, the developer specifies the web service operations by defining methods in an interface written in the Java programming language. The developer also provides classes implementing that interface according to existing business rules.
On client side, the developer uses a proxy (a local object representing the service) on which methods are invoked to call the corresponding web service operation. Hence, the developer does not generate or parse SOAP messages directly. The developer deals with Java classes that are internally marshalled to and unmarshalled from SOAP messages by the JAX-WS runtime.
Of course, JAX-WS implementations come with tools for automatically generating client proxies as well as initial endpoint interfaces given a WSDL contract. Similarly, WSDL documents can be automatically created given a web service endpoint implementation.
Finally, a note on marshalling / unmarshalling of input / output messages: when processing contracts, JAX-WS tools map WSDL operations and bindings to web service interface methods. The arguments for such methods might be described by complex types in the WSDL, perhaps imported from external schemas. The mapping is performed using an available implementation of JAXB (Java API for XML Binding). In few words, Java classes with JAXB annotations are automatically mapped to schema types defined in the WSDL contract. At runtime, JAX-WS relies on JAXB for mapping the instances of such classes to actual message payloads to be used in the generated SOAP messages.
Software you need to install
In order to be able to run our examples, there are some initial requirements, which need to be satisfied on your machine. The following section contains the list of software and tools which you need to install.
Java Development Kit
As we will code our Web Services endpoints in Java, we obviously need a Java Virtual Machine available. The Java SDK can be downloaded from the following link: http://www.oracle.com/technetwork/pt/java/javase/downloads/index.html
There are several version of Java available. If you are running a Windows machine, you will need to download an executable installer. If you are running Linux machine, you can opt for other alternatives. In this case, I will be using the RPM version on a Red Hat Linux operating system.
After you download Java, we can now begin the Java installation. Use the following commands on a root shell:
[root@alessio ~]# rpm -ivh jdk-7u45-linux-x64.rpm
After installation, we must set the JAVA_HOME environment variable in /etc/profile :
export JAVA_HOME="/usr/java/jdk1.7.0_45" export PATH="$PATH:$JAVA_HOME/bin"
Now run the command below to apply the new configuration:
[root@alessio ~]# source /etc/profile
To check the integrity of the installation, just run a simple Java command to verify:
[root@alessio ~]# java -version java version "1.7.0_45" Java(TM) SE Runtime Environment (build 1.7.0_45-b18) Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)
With the Java installation successfully completed, we are now able to move to the next topic.
WildFly application server
JAX-WS Web Services can be executed on any Java EE compatible container; we will however choose the WildFly application server as main reference for our examples. Later on in this chapter, we will provide instructions for running our first Web Service on other containers such as Tomcat or Glassfish.
WildFly 8 can be downloaded from http://www.wildfly.org by following the Downloads link in the home page, which will take you to the following screen:
Once downloaded, extract the archive to a folder and you are done with the installation:
Creating Java EE applications can be done in a variety of ways. Most developers can begin with quickstarts and demo contained in Eclipse or NetBeans environment. Nevertheless, as your application grows in complexity, so does the amount of libraries to be used (and especially the dependencies between them). For this reason, you are strongly encouraged to use Maven that is the de facto standard tool for project and release management. Maven is distributed in several formats and can be downloaded from this link: http://maven.apache.org/download.html
Once you have completed the download, unzip the distribution archive (for example, apache-maven-3.2.1-bin.zip) in the directory where you wish to install Maven.
Next, add the M2_HOME environment variable to your system, so that it will point to the folder where Maven has been unpacked. Next, update the PATH environment variable by adding the Maven binaries to your system path. For example, on the Windows platform, you should include %M2_HOME%/bin, to make Maven available to the command line.
Once completed with your installation, run mvn –version, to verify that Maven has been correctly installed:
mvn –-version Apache Maven 3.2.1 ( 2014-02-14T18:37:52+01:00) Maven home: C:\apache-maven-3.2.1\bin\.. Java version: 1.7.0_55, vendor: Oracle Corporation Java home: C:\Java\jdk1.7.0_55\jre