With the emergence of XML and a few arcane ancestors of contemporary WS-* standards in the 1990s, a few frontrunners soon recognized that exchanging data through standard interfaces over the Internet (eg, XML over HTTP) was the way to go. Initially standards and tooling support was very limited, but later the emergence of industry-wide standards such as SOAP and WSDL gave rise to a “peak of inflated expectations” at which time the use of XML and Web Services became ubiquitous--some would say without good reason.
Eventually, we learned the true value of Web Services: to enable interoperability (where it is needed) and span heterogeneous technology via standards. This nicely fits the idea of service-orientation and reuse where a client can use Web Services to consume a service regardless of the underlying technology and infrastructure.
We now have a wide variety of tools and frameworks to support Web Service development. In the Java world we have seen a fair share of them, such as DOM-based XML parsers and some crude Web Service frameworks that require lots of manual coding yet do not always result in WS-I compliant Web Services. (Several vendors include WS-I support in their tooling, and the nonprofit WS-I offers tools that will verify Web Services compliance. See the Eclipse Wiki for a how-to on testing Web Service artifacts on WS-I compliance.)
The Java Community Process formalized the JAX-RPC (Java API for XML-based RPC; JSR-101) specification in the early 2000s to support XML-based RPC standards in Java. This led to numerous tools and frameworks that were able to generate JAX-RPC Web Services and Web Service clients instead of creating proprietary implementations.
JAX-RPC later evolved into JAX-WS (Java API for XML Web Services; JSR-224)--mainly to reflect that Web Services are more than just RPC and are about communicating XML documents. Some benefits of JAX-WS over JAX-RPC include support for newer standards, improved data binding, better support for attachments using MTOM, support for EJB 3, and an improved and easier programming model using annotations.
JAX-WS also separates the Web Services runtime from data binding functionality, which were intermingled in JAX-RPC, by delegating data binding to JAXB (Java Architecture for XML Binding; JSR-222). JAXB is a framework used to transform XML documents into Java objects–known as marshalling (and vice versa, unmarshalling). This process is referred to as Object-XML Mapping (OXM) and is comparable to Object-Relational Mapping (ORM).
EclipseLink, for example, supports both ORM and OXM through standards such as JPA and JAXB. Note that JAXB can just as well be used on a “standalone basis” to perform data binding without Web Services being involved--for example, when importing XML files and persisting this data.
JAX-WS 2 and JAXB 2 are part of the JEE 5 specification and just like other Java/JEE 5 technologies use annotations and “configuration-by-exception.”That means that you can easily expose a Java class as a Web Service by adding a single @WebService annotation. However, if you want to change the default behavior, you’ll need to use more annotations and/or the JAX-WS API. (The WebLogic Server 10g Rel 3 implementation of JAX-WS is based on the JAX-WS Reference Implementation [JAX-WS RI] version 2.1.4. JAX-WS RI is an open source project that is part of Glassfish. Besides Web Service basics, this release of WebLogic supports various WS-* standards such as WS-Security, WS-Addressing, WS-Policy, SAML, and so on.)
Oracle Enterprise Pack for Eclipse 11g provides a set of certified standards-based plug-ins for the Eclipse IDE that enhances JEE development, debugging, and deployment for Oracle WebLogic Server. At the time of this writing, these plug-ins are available for Eclipse 3.4 (Ganymede) and can be downloaded as all-in-one installer or separate set of plug-ins that can be added to your existing Eclipse environment. Features include Fastswap (Java Class Redefinition support for WebLogic Server), virtual EAR technology (improving WebLogic Server deployment performance for large applications), graphical editors for WebLogic Server deployment descriptors, and an Oracle Database Plug-in for the Eclipse Data Tools Platform.
Now let’s take a closer look at how Web Service development is done with Oracle Enterprise Pack for Eclipse. Although Web Service development using JAX-WS and JAXB is also possible in default Eclipse distributions, Oracle Enterprise Pack for Eclipse delivers added value by providing additional wizards, project types, and other support that eases Web Service development (especially when using Oracle WebLogic Server as runtime).
Creating a Web Service: How to Choose the Right Approach?
Before we start developing Web Services it is important to know that there are several approaches to create a Web Service. Oracle Enterprise Pack for Eclipse offers support for each one.
* Top-down or contract first. The starting point here is the contract of the Web Service: its WSDL. You either design it or it is provided as a “given fact”. From the WSDL you generate the Java implementation. If the contract frequently changes, regeneration of the Java code can cause difficulties since the implementation is overridden. If you use this method, make sure you don't change the generated Java classes.
* Bottom-up or implementation first. The starting point is the Java implementation; all Web Service artifacts–such as its WSDL–are generated. This is a fast approach when you want to expose existing components as Web Service. However, you need to be careful because you have limited control over the generated Web Service artifacts and it is therefore easy to break an interface if the Web Service is regenerated.
* Meet-in-the-middle approach. Here you define both contract and implementation yourself and later on use JAX-WS and JAXB APIs and code to create the glue between them. This is a very flexible approach: you can change both the WSDL and the implementation. It requires more work in the beginning, but is easier to change later on.
Let’s begin with a sample app for illustration purposes.
Sample App: OTN MovieGadget
This fictitious app is based on an addition to the Oracle’s public wiki (wiki.oracle.com). To extend its social networking capabilities, several gadgets are added. One of these is the “OTN MovieGadget” that lets people interact, discuss, and connect based on their love for movies. It’s nice to be linked to others in the Oracle community, but even better to those that love The Wrestler or are a huge fan of Brad Pitt or Kate Winslet. To implement such a gadget a Web Service is needed that provides the required services such as searching for movies based on actor or title.
In this step-by-step tutorial you will build this Web Service from scratch using Oracle Enterprise Pack for Eclipse for development and Oracle WebLogic Server as runtime application server. The Web Service will be exposed using JAX-WS. Next you’ll create a client for the Web Service and use JAXB to import an XML file containing new movie data. We will use a bottom-up approach in this article since the source code is already provided and bottom-up generation provides a jumpstart for the other tasks in this tutorial. Remember, there’s no overall “best” approach; choose the one that best fits your needs.
Installation and configuration
Perform the following steps to set up your environment:
* Download and install Oracle WebLogic Server 10g Rel 3 or later (see Downloads portlet).
* Create a new Oracle WebLogic domain called “otn_examples” to which the projects from this tutorial will be deployed and run.
* Download and install Oracle Enterprise Pack for Eclipse 11g (see Downloads portlet).
* Configure a server connection in Oracle Enterprise Pack for Eclipse to the newly created “otn_examples” domain.
Instructions for these steps can be found at the Oracle Enterprise Pack for Eclipse page on OTN.
The following UML Class Diagram depicts the design of the MovieGadgetService component that will implement the gadget.
You can find the MovieGadget project that contains the plain Java code in the accompanying zip file. Import it in Oracle Enterprise Pack for Eclipse and run the MovieServicesTester to see how it works. (Note that movie data is stubbed using the MovieServicesDataPopulator class; in a real life project this data would come from a datastore such as a relational database.)
Creating a Web Service project
We start the tutorial by creating a project that will contain our Web Service.
1. Create a new Web Service project. From the menu select File -> New -> Other... . In the dialog select WebLogic Web Services -> Web Service Project. Click Next.
Note that for convenience we create a WebLogic Web Service Project that contains all the right facets, libraries, and so on from the start. In a bottom-up approach, the project containing Java class(es) you want to expose as Web Service usually already exists. In such a case you add JAX-WS and JAXB annotations, add the required libraries and facets, and, if needed, create an EAR project that packages the Java code after which you deploy it on an application server.
2. Enter “MovieGadgetWebService” as project name. If the target runtime is not yet set to “Oracle WebLogic Server 10gR3” then select it from the dropdown list. Select Add project to an EAR. Keep all other default values and click Next.
3. Keep all defaults in the Web Module dialog and click Finish to create the new Web Service Project.
4. The new project is created and all relevant facets, libraries, and required deployment descriptors such as web.xml and weblogic.xml are added to the project. Eclipse asks if you want to change the perspective to Java EE. Select Yes. This opens all views that are relevant to Java EE software development.
Note that you can change the perspective using the top-right hand side tabs and the Open Perspective icon.
Creating the “MovieGadget” Web Service
Now let’s create the actual Web Service.
1. Add a new JAX-WS Web Service by right-clicking the “MovieGadgetWebService” project and selecting New -> WebLogic Web Service.
2. In the Web Service dialog enter “MovieGadgetWebService/src/com/oracle/otn/movie/service” as parent folder and “MovieServices” as file name. Click Finish to create the Web Service.