Implementing a Web Service in a Web Application

In the IDE, you can create a web service by implementing an existing WSDL file, exposing existing code, or creating one from scratch. The IDE generates deployment information in the deployment descriptors, the necessary Java code that describes this web service (the default implementation; the Service Endpoint Interface, also called SEI; and a compilation target in the Ant build script).

A simple way to create a web service is to start from scratch.

Creating a Web Service

To create a new web service:

Right-click a web application's project node and choose New | Web Service.
In the New Web Service wizard (see Figure 12-6), specify a name and a Java package, select the From Scratch radio button, and click Finish.

Figure 12-6. New Web Service wizard

It is strongly recommended that you do not use the default package (which would occur if you left the Package field blank).

When you complete the wizard, a new web service with no operations is added to your project. You can see a logical node representing this new component in the Web Services node in the Projects window. A new servlet entry is added to the web.xml file, and a webservice-description enTRy is added in the webservices.xml description file (a sibling of the web.xml file). Most of the time, you don't need to worry about these entries, as they are automatically updated by the IDE when necessary.

As a developer, you will use the Projects window most (as opposed to the Files window). It synthesizes the implementation details of a web service (such as its implementation class and its SEI) and allows you to:

Explore the existing operations.
Add new operations for the web service.
Register the web service to the runtime registry that will allow you to test it from within the IDE.
Configure any web service message handler classes that might be associated with it.

Adding an Operation

Choose Add Operation (either by right-clicking the web service's node in the Projects window, as shown in Figure 12-7, or by right-clicking within the web service in the Source Editor). In the Add Operation dialog box (shown in Figure 12-8), you can configure the list of parameters for this operation, as well as the return type and any exceptions.

Figure 12-7. Adding an operation to a web service

Figure 12-8. Add Operation dialog box

The operation is added to the Java class implementing the web service (see Figure 12-9). The IDE automatically synchronizes the SEI, so you need to concentrate only on developing the operation method body.

Figure 12-9. Adding an operation to a web service

Compiling the Web Service

Now that the web service has been added to your web application project, you just need to call the Build Project or Deploy Project command (available by right-clicking the project's node) to trigger an Ant build process that will invoke the wscompile tool with the correct parameters. The web application will be packaged as a WAR file and deployed to the target server for this project. Following is an example of what the Ant output might look like (keeping in mind that by default the lines do not wrap they way they do in this excerpt):

init: deps-module-jar: deps-ear-jar: deps-jar: wscompile-init: Created dir: C:\ludo\WebAppWithWebService\build\web\WEB-INF\wsdl Created dir: C:\ludo\WebAppWithWebService\build\web\WEB-INF\classes Created dir: C:\ludo\WebAppWithWebService\build\generated\wsclient Created dir: C:\ludo\WebAppWithWebService\build\generated\wsservice Created dir: C:\ludo\WebAppWithWebService\build\generated\wsbinary GoogleSearch-client-wscompile: Copying 1 file to C:\ludo\WebAppWithWebService\build\generated\wsclient\wsdl warning: Processing WS-I non conforming operation "doGetCachedPage" with RPC-Style and SOAP-encoded warning: Processing WS-I non conforming operation "doSpellingSuggestion" with RPC-Style and SOAP-encoded warning: Processing WS-I non conforming operation "doGoogleSearch" with RPC-Style and SOAP-encoded web-service-client-generate: Copying 1 file to C:\ludo\WebAppWithWebService\build\web\WEB-INF Created dir: C:\ludo\WebAppWithWebService\build\web\META-INF Copying 1 file to C:\ludo\WebAppWithWebService\build\web\META-INF Copying 5 files to C:\ludo\WebAppWithWebService\build\web Copying 2 files to C:\ludo\WebAppWithWebService\build\web library-inclusion-in-archive: library-inclusion-in-manifest: web-service-client-compile: Compiling 12 source files to C:\ludo\WebAppWithWebService\build\web\WEB INF\classes Compiling 3 source files to C:\ludo\WebAppWithWebService\build\web\WEB INF\classes Copying 1 file to C:\ludo\WebAppWithWebService\build\web\WEB-INF\classes NewWebService_wscompile: command line: wscompile "C:\Program Files\Java\jdk1.6.0\jre\bin\java.exe" -classpath "C:\Program Files\Java\jdk1.6.0\lib\tools.jar;C:\Sun\AppServer82\lib\j2ee.jar;C:\Sun \AppServer82\lib\saaj-api.jar;C:\Sun\AppServer82\lib\saaj impl.jar;C:\Sun\AppServer82\lib\jaxrpc api.jar;C:\Sun\AppServer82\lib\jaxrpc impl.jar;C:\ludo\WebAppWithWebService\build\web\WEB-INF\classes" com.sun.xml.rpc.tools.wscompile.Main -d "C:\ludo\WebAppWithWebService\build\generated\wsbinary" -define- features:documentliteral,strict,useonewayoperations -keep -mapping "C:\ludo\WebAppWithWebService\build\web\WEB-INF\NewWebService- mapping.xml" -nd "C:\ludo\WebAppWithWebService\build\web\WEB-INF\wsdl" -s "C:\ludo\WebAppWithWebService\build\generated\wsservice" -verbose Xprintstacktrace "C:\ludo\WebAppWithWebService\src\java\com\acme\NewWebService config.xml" [creating model: NewWebService] [creating service: NewWebService] [creating port: com.acme.NewWebServiceSEI] [creating operation: getValidation] compile: compile-jsps: Created dir: C:\ludo\WebAppWithWebService\dist Building jar: C:\ludo\WebAppWithWebService\dist\WebAppWithWebService.war do-dist: dist: run-deploy: Incrementally deploying WebAppWithWebService_localhost:4848_server Completed incremental distribution of WebAppWithWebService Trying to create reference for application in target server completed successfully Trying to start application in target server completed successfully Deployment of application WebAppWithWebService completed successfully run-display-browser: Browsing: http://localhost:8080/WebAppWithWebService/ run: BUILD SUCCESSFUL (total time: 10 seconds)

You can use a web browser (as shown in Figure 12-10) to query the deployed and running web application for the published WSDL file for this web service. In this case, the file is http://localhost:8080/WebAppWithWebService/NewWebService?WSDL.

Figure 12-10. Web browser displaying the WDSL file for the web service

Your web service is now published and available to anyone so that other applications (Java enterprise applications, .NET applications, or Java ME applications) can interoperate with its operations.

Creating Web Services from WSDL

You can also create a web service from a WSDL document. A typical scenario when this is necessary is when business partners formulate the way they will communicate in web services. The "contract" between them would be the WSDL, in which they would agree on the data and messages that will be exchanged, as well as on how these messages will be sent and received. Then this WSDL is used to implement the web service.

The elements of a WSDL document can be categorized into abstract and concrete parts. The types, message, and portType elements describe the data that form the messages sent and received by web services and clients, as well as the operations that will use these messages. These sections constitute the abstract portion of the WSDL. The binding and service elements describe the protocols and transport mechanisms used to send and receive the messages, as well as the actual address of the endpoint. This is considered to be the concrete portion of the WSDL file.

When you are creating a web service from a WSDL in the IDE, a new WSDL is created and packaged with the web service. The abstract portion of the original WSDL is copied to the new one. The concrete portion of the original WSDL is normalized for SOAP binding. Because the JAX-RPC runtime that is used in the NetBeans IDE only supports SOAP over HTTP binding, the WSDL is searched for the first occurrence of this binding. If found, it is copied into the new WSDL. If not, a SOAP/HTTP binding is created for the first portType defined in the original WSDL. Thus, the web service created from WSDL in the NetBeans IDE will always have exactly one SOAP binding and one service port corresponding to that binding. The service element that is added will be named according to the web service name specified in the wizard, replacing the service element in the original WSDL.

To create a web service from a WSDL file, click the From Local WSDL File radio button or the From WSDL URL radio button in the wizard, depending on the source of the WSDL document. When the web service is created, classes for the service endpoint interface and implementation bean will be created. These classes will contain all the operations described in the WSDL. The implementation bean class will be displayed in the Source Editor, and you may then enter code to implement these operations. If the WSDL file describes operations that use complex types, classes for these types (known as value types) are also generated so that you may use them in your implementation code.

Because the WSDL document governs the interface to the web service, you may not add new operations to web services that are created from a WSDL, because these operations will not be reflected back in the WSDL.

Note that WSDLs that import other WSDLs are not supported by this facility.

Web Service Types

By default, NetBeans IDE creates document/literal Web services. This refers to the way the SOAP message is sent over the wire and is expressed in the SOAP binding part of the WSDL. The document/literal nomenclature comes from the way SOAP messages are described in the SOAP binding of a WSDL documentnamely, its style and use attributes.

The style attribute refers to the formatting of the SOAP message. This basically refers to what the SOAP body will contain when it is sent over the wire.

There are two ways to format a SOAP message: RPC and document. When the style is RPC, the contents of the SOAP body are dictated by the rules of the SOAP specificationthat is, the first child element is named after the operation, and its children are interpreted as the parameters of the method call. The endpoint will interpret this as an XML representation of a method callthat is, a remote procedure call. On the other hand, if the style attribute is document, the SOAP body consists of arbitrary XML, not constrained by any rules and able to contain whatever is agreed upon by the sender and receiver.

The use attribute describes how data is converted between XML and software objectsthat is, how it is serialized to XML.

If the use attribute is encoded, the rules to encode/decode the data are dictated by some rules for encoding, the most common of which is the SOAP encoding specified in the SOAP specification. Section 5 of the SOAP specification defines how data should be serialized to XML. In this case, web services or clients see data in terms of objects.

If the use attribute is literal, the rules for encoding the data are dictated by an XML schema. There are no encoding rules, and the web service or client sees the data in terms of XML. Here, the developer does the work of parsing the XML to search for needed data.

Thus, document/literal web services typically are used to exchange business documents, whereas RPC/encoded web services typically are used to invoke remote objects. For this reason, document/literal is preferred over RPC/encoded because in document/literal, you have full control of the messages that are being exchanged. The WS-I Basic Profile, which is a specification for web services interoperability, does not support RPC/encoded web services.

Following are the advantages of document/literal over RPC/encoded web services:

Document/literal formatting is more interoperable than RPC/encoded formatting because RPC formatting tends to bind the messages to programming language structures.
Document/literal Web services scale better than RPC/encoded because of the overhead involved in marshalling and unmarshalling RPC data.
Document-centric Web services lend themselves to validation of the documents being exchanged. This is cumbersome to do with RPC-style services.