18.1 About Developing and Securing Web Services

Web services are distributed application components that conform to standards that make them externally available. They solve the problem of integrating diverse computer applications that have been developed independently and run on a variety of software and hardware platforms.

The promise of web services architecture is to allow you to connect applications that were developed on different platforms and in different programming languages. This can only work if vendors can agree on common standards.

The following web service programming models are supported by the IDE:

SOAP Web Services (JAX-WS). SOAP is an XML protocol that can be used for messages to and from a web service. Java API for XML Web Services (JAX-WS) is the specification for SOAP web services that is supported by NetBeans IDE. For more details, see Section 18.3.1, "How to Create SOAP (JAX-WS) Web Services."

REpresentational State Transfer (REST). Central to REST is the concept of resources identified by universal resource identifiers (URIs). These resources can be manipulated using a standard interface, such as HTTP, and information is exchanged using representations of these resources. For more details, see Section 18.3.2, "How to Create RESTful Web Services."

In most cases you do not need to build the web service. The IDE builds the service automatically as part of the deployment process. However,

Right-click the project's node in the Projects window and choose Build.

Analyze the result and, if necessary, customize the related tool's features. For a JAX-WS web service that is created from a WSDL file, you can use the Web Service Attributes editor to customize XML to Java (JAXB) mappings, WS Security, or other WS* features.

18.3 Creating Web Services

18.3.1 How to Create SOAP (JAX-WS) Web Services

JAX-WS is a technology for building web services and clients that communicate using XML. JAX-WS allows developers to write both message-oriented and RPC-oriented web services. JAX-WS simplifies web services compared to the older JAX-RPC standard by using annotations, a Java EE 5 innovation.

A JAX-WS web service consists of an implementation class, which is a Java class that implements the service endpoint. The implementation class defines the service endpoint interface implicitly, by default.

The implementation class is annotated with @WebService or @WebServiceProvider. The web service's operations are defined in methods in the implementation class. These methods are annotated with @WebMethod.

In Java EE 6 and Java EE 7 the JAX-WS web service can be implemented as a stateless session bean. To use an EJB with a web service in EE 5, you have to create a separate EJB module and add that module to the web application's classpath. You can combine the web application and the EJB module in an Enterprise Application.

In JAX-WS, messages to and from the web service use the XML-based protocol known as "SOAP". The SOAP specification defines the envelope structure, encoding rules, and conventions for representing web service invocations and responses. These calls and responses are transmitted as SOAP messages (XML files) over HTTP.

JAX-WS depends on the following specifications:

SOAP (Simple Object Access Protocol). Defines the mechanism by which a web service is called and how data is returned. For detailed information, refer to the SOAP 1.2 Specification.

UDDI (Universal Discovery, Description, and Integration). Registries contain information about web services, including the location of WSDL files and the location of the running services. The IDE does not let you publish web services to or browse from a UDDI registry, although the WSDL files that you use can come from a variety of sources, including a UDDI registry.

Depending on the implementation form and EE version, create a web application project or create an EJB module project.

In the Projects window or Files window, right-click the project node and choose New > Web Service.

The New Web Service wizard opens.

Type the web service name and specify a package to house the web service.

Select the creation type:

Create an Empty Web Service. Use this when you have no existing code to expose.

Create Web Service From Existing Session Bean. Use this when you have a session bean in an EJB module. Click Browse to select the session bean to which you want to delegate.

Click Finish.

The IDE creates an implementation class. The implementation class is created with the required web service annotations and import statements.

Use the Source Editor to develop the web service.

To create a JAX-WS web service from a Java class:

Open a Java class.

Type @WebService above the class declaration.

Press Alt+Enter in the line, or click the light bulb in the left sidebar, and select javax.jws.WebService.

Press Alt+Enter in the class declaration, or click the light bulb in the left sidebar, and click Add new operation.

The Add Operation dialog box appears.

Add an operation and click OK to exit the Add Operation dialog box.

In the Projects window, expand the Web Services node and click on the new node, named after your Java class. For example, if your Java class is called Test.java, the new node in the Web Services node is called TestService. The web service opens in the Web Service Designer, where you can continue fine tuning your web service, visually.

To create a web service from a WSDL file:

When you and your business partners agree on a "contract" in the form of a WSDL file, you can use the IDE to implement it. The WSDL file is an agreement on the data and messages that will be exchanged as well as how these messages will be sent and received. In the IDE, you can use the WSDL file to implement the web service.

Business requirements may demand that you create a platform-independent description of a web service as a set of XML schema files and WSDL files. Based on this platform-independent description, you can use the steps that follow to generate the implementation files. The WSDL file that you use in the steps below can either be available on disk or via a URL.

Depending on the implementation form, create a web application project or an EJB module project.

In the Projects window or Files window, right-click the project node and choose New > Other. In the Web Services folder, choose Web Service from WSDL.

The New Web Service from WSDL wizard opens.

Type the web service name and specify a package to house the web service.

Browse to a WSDL file in your filesystem or type the URL to a WSDL file.

Select Use Provider if you want to bypass the XML <--> Java binding layer and have the service use raw XML when processing requests. Instead of XML <--> binding, the Provider interface is used. This is an advanced feature and is unselected by default.

Click Finish.

The IDE runs the wsimport tool, which reads the WSDL file and generates all the required artifacts for web service development, deployment, and invocation. Finally, the IDE generates the skeleton implementation class, which corresponds to the WSDL port selected in the wizard.

18.3.1.1 How to Add Operations to a JAX-WS Web Service

After you create a web service, you implement its operations in the implementation class. You can add operations manually in the Source Editor, by using the Web Service Designer, or by using the Add Operation dialog box. In the latter case, the IDE automatically declares the operation in the Service Endpoint Interface (the "interface"), if there is one (it is optional in the JAX-WS programming model) and adds a skeleton method in the implementation class.

Note:

You can also add operations to a web service created from a WSDL file. In this case, you can specify the XML schema types as parameters and return types.

To add a web service operation:

Open the Add Operation dialog box in one of three ways:

In the Projects window, expand the Web Services node, right-click the web service instance node, and choose Add Operation.

Open the web service's implementation class in the Source Editor. Right-click anywhere in the body of the class and choose Web Service > Add Operation.

In the implementation's Design view, click the Add Operation button.

Define the name, return type, parameters, and exceptions of the web service operation. For example, do the following if you want to create this operation:

public int add(int a, int b) throws MyException {
return a + b;
}

Type add in the Name text box and choose int from the Return Type drop-down.

Click Add.

Choose int from the Type drop-down and type a in the Name text box. Click OK.

Click Add.

Choose int from the Type drop-down and type b in the Name text box. Click OK.

It is not necessary to add the java.rmi.RemoteException exception, because the IDE does this for you.

Click OK to create the operation.

The IDE adds the skeleton of the operation to the implementation class and declares it in the interface.

In the Source Editor, implement the web service operation. For example, you could add return a + b; between the braces. Do this in the implementation class, not in the interface (if you have a separate interface class).

18.3.1.2 How to Use the JAX-WS Web Service Designer

The Web Service Designer is the primary workspace within which SOAP web service design takes place in the IDE. It unifies the two ways in which you can develop web services—from Java classes and from WSDL files. Tabs are provided for switching from the source view to the design view. The Web Service Designer enables you to lay out web services by visually adding operations and enabling features such as reliable message delivery. In particular, you can do the following in the design view:

Add web service operations

Delete web service operations

Change the web service operation name

Optimize binary data transfer (MTOM)

Set up the reliable messaging delivery

Set up the web service security

View what the SOAP requests and responses will look like on the wire

To open the Web Service Designer, create a SOAP web service, expand the Web Services node in the Projects window, and double-click on the node representing the web service.

18.3.2 How to Create RESTful Web Services

You can use NetBeans IDE to create a RESTful web service in a Java Web application. You can use the IDE to create either an "empty" service based on a pattern (singleton or item/container) or a service configured to communicate with an existing database. In addition, you can expose any suitable Java class as a RESTful web service by appending it appropriately.

Create a RESTful Web Service From Patterns:

Create a web application project.

In the Projects window or Files window, right-click the web application project node and choose New.

Then choose one of the following patterns:

Simple Root Resource. Creates a RESTful root resource class with GET and PUT methods. This pattern is useful for creating a simple HelloWorld service and wrapper services for invoking WSDL-based web services.

Container-Item. Creates a pair of RESTful resource classes, consisting of an item resource class and its container resource class. Item resources can be created and added to the container resource using the POST method on the container resource class.

Note:

The URI for the newly created item resource is determined by the container resource.

Client-Controlled Container-Item. Creates a pair of RESTful resource classes, consisting of an item resource class and its container resource class. This pattern is a slight variation of the Container-Item pattern. The difference is that there is no POST method on the container resource class for creating item resources. Instead, item resources are created using the PUT method on the item resource class. The reason this is called Client-Controlled Container-Item pattern is because the URI for the item resource is determined by the client and not the container resource.

Alternatively, you can choose the above templates by right-clicking the project node, choosing New > Other and then selecting them from the Web Services category.

You can use the IDE to create either an "empty" service based on a pattern (singleton or item/container) or a service configured to communicate with an existing database. In addition, you can expose any suitable Java class as a RESTful web service by appending it appropriately.

Create a web application project.

In the Projects window or Files window, right-click the web application project node and choose New.

Choose one of the following:

RESTful Web Service from Database. This wizard creates entity classes from a database and then creates RESTful web services from those entity classes.

Note:

If you do not have existing entity classes, it is safer and more convenient to use this wizard instead of the Entity Classes From Database wizard followed by the RESTful Web Services from Entity Classes wizard.

18.4 Configuring Web Services

You configure your web services at several different levels.

Project Contents and Classpath

Basic project settings like the web application or EJB module's source roots and classpath are set in the module's Project Properties dialog box. You open this dialog box by right-clicking the project node and choosing Properties.

For standard projects, you can add source roots in the Sources page of the Project Properties dialog box. You can quickly add to the compilation and test classpath by right-clicking the Libraries or Test Libraries node in the Projects window. To further configure the classpath, or to specify which items should be included in deployment, use the Libraries page of the Project Properties dialog box.

JAX-WS Service Compilation Settings

For JAX-WS web services, you can either use the Web Service Attributes editor or generate WSDL and Schema files and edit them manually.

To use the Web Service Attributes editor, go to the Projects window, find the project's Web Services node, right-click the web service and select Edit Web Service Attributes.

To generate WSDL and Schema files, go to the Projects window, find the project's Web Services node, right-click the web service and choose Generate and Copy WSDL. A wizard opens in which you select the location for the WSDL and schema files. After you generate the schema and WSDL, you can edit them manually. After editing these files, you need to add a wsdlLocation attribute to the service's @WebService annotation. The wsdlLocation attribute's value is the path to the generated WSDL.

If you copy and edit the WSDL and schema files, you must add the wsdlLocation to the web service. The IDE generates a WSDL file at build time, and if the wsdlLocation is not specified, the IDE uses the WSDL it generates itself instead of the one you generated.

RESTful Service Compilation Settings

The main decision you make when you create a RESTful service is how to register that service. When you create the service, the IDE opens a dialog where you choose whether to use the default web.xml deployment descriptor created by the IDE or to write the registration yourself. For EE services, you also have the choice of using an IDE-generated subclass of javax.ws.rs.core.Application. After you create the service, you can change how the service is registered by going to the Projects window, right-clicking the application's RESTful Web Services node, and choosing REST Resources Configuration.

You can also generate and edit a WADL for a web application. To generate the WADL, select New File > Web Services > WADL Document. To help you edit the WADL document, install the WADL Designer plugin.

Deployment Settings

There are several key steps to configuring deployment settings:

Setting the target server. You can set the target server instance for a project by doing any of the following:

Specifying the server in the New Project wizard when creating the project.

Going to a project's Project Properties dialog box and setting the target server in the Run page.

Adding the module that contains the web service to an enterprise application. The module is then deployed to the same server instance as the enterprise application.

Adding the project module to a Java EE Enterprise Application. You can add a web application or EJB module to an enterprise project by doing either of the following:

Specifying the enterprise application in the New Project wizard when creating the project.

Configuring web services via annotations. The IDE generates annotation snippets in the artifacts that it creates and lets you use code completion to fill out the annotation snippets.

Configuring web services via deployment descriptors. You can manually configure your deployment descriptors by opening the project's web.xml deployment descriptor. In the case of EE6 RESTful services, which by default do not have deployment descriptors, you can generate a deployment descriptor by adding New > Web > Standard deployment descriptor (web.xml).

Changes made to the web.xml deployment descriptor override configuration settings in annotations.

18.4.1 Using Annotations and Deployment Descriptors

Annotations play a critical role in JAX-WS web services. Annotations are used in mapping Java to WSDL and schema files. They are used at runtime to control how the JAX-WS runtime processes and responds to web service invocations. In the IDE, you can use code completion when working with annotations.

Deployment descriptors are XML-based text files whose elements describe how to assemble and deploy a module to a specific environment. The elements also contain behavioral information about components not included directly in code.

About Annotations

At the time of writing, the annotations utilized by JAX-WS are defined in separate JSRs:

Structural information describes the different components of the JAR (or EAR) file, their relationship with each other, and their external dependencies. Environment entries and resource requirements are part of the structural information.

Assembly information describes how contents of a JAR (or EAR) file can be composed into a deployable unit.

There are different types of deployment descriptors: EJB deployment descriptors described in the Enterprise JavaBeans specification, web deployment descriptors described in the Servlet specification, and application and application client deployment descriptors described in the Java EE specification. For each type of module or application, there are two deployment descriptors:

A general deployment descriptor that configures deployment settings on any Java EE-compliant implementation. The general deployment descriptor is named moduleType.xml (for example, ejb-jar.xml for EJB modules and web.xml for web application modules.)

A server-specific deployment descriptor that configures deployment settings for a specific server implementation. For example, the deployment descriptors for the GlassFish Server are named glassfish-moduleType.xml. The deployment descriptor for the Tomcat Web Server is named context.xml.

Deployment Descriptors in the IDE

The IDE generates a deployment descriptor from the settings for EJB modules, web application modules, and enterprise applications, when you create an empty enterprise project. Deployment descriptors are NOT created automatically for EE6 projects. See "Deployment Descriptors in EE 6 Projects." It also reads your existing deployment descriptors when you import existing enterprise beans, enterprise applications, and web applications into the IDE. The deployment descriptors are located in the conf folder of your project directory, and are displayed under the Configuration Files node in the Projects window.

As you work with your projects, the IDE updates the general deployment descriptors to reflect changes you have made, such as adding business methods to an enterprise bean or adding a web application module to an enterprise application.

The IDE also automatically updates your server-specific deployment descriptors if the target server is the Tomcat Web Server or the GlassFish Server. For all other application servers, you have to write the deployment descriptors yourself.

You can open a graphical editor for a deployment descriptor by double-clicking its node in the Projects window. You can edit the deployment descriptor's XML by right-clicking its node and choosing Edit.

The IDE also automatically registers the DTDs and schemas for all the Java EE deployment descriptors, as well as the Oracle Java System Application Server DTDs. You can therefore check and validate the XML in your deployment descriptors according to the DTDs and schemas. You can view the DTDs by choosing Tools > DTDs and XML Schemas from the main menu.

Deployment Descriptors in EE 6 Projects

By default, Java EE applications use annotations instead of deployment descriptors. However, in some cases a deployment descriptor is still necessary, such as when customizing the application. In these situations you can have the NetBeans IDE create a deployment descriptor. Right-click the project's node in the Project Manager and select New > Standard Deployment Descriptor.

18.4.2 How to Configure a Web Service With Annotations

Annotations serve two purposes. Firstly, they affect the WSDL file that will be generated for the service. Secondly, they provide deployments and runtime information to the container.

For example, you can use the @WebService annotation to specify the WSDL file's target namespace. You can also use the @SOAPBinding annotation to specify the style/use configuration of the service messages, for example, document/literal or rpc/literal.

Before there were annotations, web services were deployed with a standard deployment descriptor, accompanied by service-specific descriptors. This can now be replaced by annotations. For example, the location of the WSDL file in the deployed archive can now be specified through the wsdlLocation attribute of the @WebService annotation. Likewise, message handlers can be configured using annotations, instead of including them in the deployment descriptor.

18.4.3 How to Configure a Web Service With Its Deployment Descriptor

For JAX-WS web services, you usually use annotations instead of deployment descriptors, except when you want to override annotations by means of deployment descriptors.

Deployment descriptors are XML-based text files whose elements describe how to assemble and deploy a module to a specific environment. The elements also contain behavioral information about components not included directly in code.

For web services, the webservices.xml file configures web services, but you should seldom have a need for editing this file.

Note:

In most cases, there is no need to manually edit the deployment descriptors. The IDE's wizards normally take care of configuring deployment descriptors correctly. Normally, only if your deployment descriptor becomes corrupted for some reason, does it make sense to manually edit it.

To edit webservices.xml:

In the Projects window, expand the Configuration Files node for your project.

Double-click webservices.xml to open it in the Source Editor.

Edit the deployment descriptor as necessary.

Choose File > Save to save your changes.

Note:

If you introduce any XML syntax errors, the IDE automatically alerts you. To ensure your changes have not cause any errors, verify the web application.

To edit filename-config.xml:

In the Projects window, expand the Source Packages node for your project.

Double-click filename-config.xml to open it in the Source Editor.

Edit the configuration file as necessary.

Choose File > Save to save your changes.

Note:

If you enter any XML syntax errors the IDE automatically alerts you. To ensure your changes have not cause any errors, verify the web application.

18.5 Creating JAX-WS Web Service Clients

A web service client is created to consume (that is, use) a specific web service. The way in which a web service client consumes a web service depends on the way in which the provider makes the web service available:

The provider publishes the WSDL file of a running web service.

The provider distributes a WSDL file, which is available to you on your local filesystem.

The provider distributes a NetBeans project that defines the web service, for deployment to a test container.

18.5.1 How to Work with JAX-WS Web Service Clients

These steps summarize the JAX-WS client development process.

To create a JAX-WS web service client:

Create the web service client.

From the Projects window or Files window, right-click a node in the project and choose New > Other. The New File wizard appears. Under Categories, select Web Services. Under File Types, select Web Service Client. Click Next.

In the Projects window or Files window, double-click the files that you would like to edit.

Use the Source Editor to develop the web service client.

When you right-click in the Source Editor, you can use the IDE to generate skeleton code for calling a web service operation.

Build the web service client

Deploy the web service client

18.5.2 How to Set a Proxy for Web Services and Clients

If you want to access a remote web service, but your system is behind a firewall or you use a proxy server, you need to configure the IDE with your proxy settings. For working with remote web services, setting a proxy can be important in one or more of the following areas:

When retrieving the WSDL file in the Web Service Client wizard.

When using the IDE to test the web service.

When deploying to the Oracle GlassFish Open Source Edition Server.

When deploying to the Oracle WebLogic Server.

When deploying to the JBoss Server.

When deploying to the Tomcat Web Server.

When deploying a web service client in a Java application.

The proxy settings for each of the situations above are described below.

Setting a Proxy When Retrieving WSDL Files in the Web Service Client Wizard

Typically, an error such as the following is displayed in the Web Service Client wizard when the proxy settings for retrieving a WSDL file have not been set correctly:

Download failed. I/O exception: (Check the proxy settings.)

Do the following to check and set the proxy:

Click Proxy Settings in the Web Service Client wizard.

In the HTTP Proxy Settings window, set the proxy host and port number.

The changes take effect when you click OK.

Setting a Proxy When Testing a Web Service

Typically, an error such as the following is returned when the proxy settings for testing a web service from the IDE have not been set correctly:

Right-click the Java application project node in the Projects window and choose Properties.

In the Project Properties dialog box, click Run.

Add the following properties to the VM Options field:

-Dhttp.proxyHost=your.proxy.host-Dhttp.proxyPort=your.proxy.port

The changes take effect when you click OK.

For client deployment from Java applications, you must set the proxy for each project, because each Java application runs as a stand-alone JVM process and each can provide different JVM parameters. For web applications sharing the same instance of a server, you need set the proxy only once -- on the server itself, as described above.

18.5.3 How to Generate a JAX-WS Web Service Client

A web service can be consumed in a web application, a Java application, or a MIDP client (MIDlet). For information on consuming web services in a MIDlet, see the Java ME Mobility documentation.

For JAX-WS clients, all imported WSDL files and schemas are resolved automatically by the IDE. For JAX-RPC clients, before you begin, be aware that if the WSDL file that you want to use imports schemas, other WSDL files, or both, from the local file system, the web service client will only work if the imported schemas and WSDL files have already been copied into the WEB-INF/wsdl (or META-INF/wsdl) folder. If you do not do this, the wscompile tool will not be able to locate these imported files at the end of the procedure below.

To create a web service client:

Create the project to contain the web service client. Depending on how you want to consume the web service, create a web application project or a Java application project.

From the Projects window or Files window, right-click a node in the project and choose New > Other. The New File wizard appears. Under Categories, select Web Services. Under File Types, select Web Service Client. Click Next.

Access the WSDL file of the web service that the web service client is to consume. Depending on what the provider has distributed, do the following:

To generate a client from a project on your local filesystem, click Project and browse to a project's web service port icon.

To generate a client from a WSDL file on your local filesystem, click Local File and browse to the WSDL file on your local filesystem.

To generate a client from a running web service, click WSDL URL, then type or paste the web service's URL. If you are behind a corporate firewall, click Proxy Settings and set your proxy host and port number.

Note:

The WSDL file is downloaded when you finish the wizard.

Optionally, specify the package where the client files will be generated. When you complete the wizard, you can find the generated client files in the Projects window, in the Generated Sources node of the client project, or in the Files window, within the build folder.

If you do not specify a package name, the IDE generates the client files in the default package, which is based on the namespace in the WSDL. You can change this package name later in the WSDL Customization editor.

Specify whether to use JAX-WS or the older JAX-RPC client style. JAX-WS is selected by default. However, older services may require JAX-RPC clients. Install the JAX-RPC Web Services plugin to create JAX-RPC clients.

If you want to use raw XML messages when invoking the web service, select Generate Dispatch Code. The client code is generated using the java.xml.ws.Dispatch interface instead of the usual service endpoint interface. This is an advanced feature and is unselected by default.

Click Finish.

18.5.4 How to Call a Web Service Operation

A web service operation can be called from a web application, a Java application, or a MIDP client (MIDlet). For information on calling a web service operation from a MIDlet, see the Java ME Mobility documentation.

To call a web service operation:

Create a web service client.

If the web service client is deployed from a web application, you can call the web service from a servlet or from a JSP page. If the web service client is deployed from a Java application, use a Java source file instead. So, do one of the following:

Create a Java source file, such as a servlet.

Use the default index.jsp file that is created for you when you create a web application or a JSP file.

Open the file in the Source Editor and do one of the following:

Expand the Web Service References node and continue expanding subnodes until you get to the node representing the operation. Using your mouse, drag and drop the node to where you need it to be in the file.

Right-click in the method (for Java files) or anywhere in the Source Editor (for JSP file) from where you want to call the web service, and choose Insert Code > Call Web Service Operation. The Select Operation to Invoke dialog box appears. Expand the nodes and select a web service operation. Click OK.

The IDE adds the code required for calling the web service to the file.

18.5.5 How to Asynchronously Call a Web Service Operation

When a client calls a JAX-WS web service operation asynchronously, the client does not need to wait for the response to be received. When a client use this communication style, it consumes the web services either through the "polling" approach or the "callback" approach.

Polling. The client invokes a web service method and repeatedly asks for the result. Polling is a blocking operation because it blocks the calling thread, which is why you do not want to use it in a GUI application.

Callback. The client passes a callback handler during the web service method invocation. The handler's handleResponse() method is called when the result is available. This approach is suitable to GUI applications because you do not have to wait for the response. For example, you make a call from a GUI event handler and return control immediately, keeping the user interface responsive.

Note:

You can use the IDE to generate skeleton asynchronous methods, as explained below.

To call a web service operation asynchronously:

Create a web service client.

If the web service client is deployed from a web application, you can call the web service from a servlet or from a JSP page.

If the web service client is deployed from a Java application, use a Java source file instead. The source file can be:

A Java source file, such as a servlet, that you have created

The default index.jsp file that is created for you when you create a web application or a JSP file

In the Projects window, expand the Web Service References node, right-click the web service node (the first node within the Web Service References node), and choose Edit Web Service Attributes.

In the Edit Web Service Attributes editor, within the PortType Operations node, expand the node with the same name as the web service operation you want to invoke.

Select Enable Asynchronous Client. Click OK.

Open the file in the Source Editor and do one of the following:

Expand the Web Service References node and continue expanding subnodes until you get to the node representing the asynchronous operation. Using your mouse, drag and drop the node to where you need it to be in the file.

Right-click in the method (for Java files) or anywhere in the Source Editor (for JSP file) from where you want to call the web service, and choose Insert Code > Call Web Service Operation. The Select Operation to Invoke dialog box appears. Expand the nodes and select the asynchronous operation. Click OK.

The IDE adds the code required for asynchronously calling the web service to the file.

18.5.6 How to Deploy a Web Service Client

Right-click the project and choose one of the following:

Run. Only takes the minimal steps needed to run the project. For example, if you only changed one file, only that file is sent to the server.

Deploy. Undeploys and then deploys the complete module no matter what changes you made, even if none.

Note:

After the first time a web application is deployed, it is redeployed automatically whenever you save changes to that application.

For web applications, unless the project in which the web service client is implemented is designed to be deployed as a stand-alone application, you should always deploy it by deploying the enterprise application that contains it. If you run the Run or Deploy commands on an individual module that is part of an enterprise application, the IDE only deploys that module itself. Any changes you have made in the other modules in the project are not propagated to the server.

To deploy a client from within an enterprise application project:

In the Projects window, add the web application module to the enterprise application.

Right-click the enterprise application project and choose one of the following:

Run. Only takes the minimal steps needed to run the project. For example, if you only changed one file, only that file is sent to the server.

Deploy. Undeploys and then deploys the complete module no matter what changes you made, even if none.

18.6 Creating RESTful Web Service Clients

NetBeans IDE helps you create two kinds of clients for RESTful web services:

Java Clients. The IDE generates a Java client for a RESTful service based on the Jersey Client API. The client code can be generated in an existing Java class, or the IDE can generate a client class in a Java application, Web application, or NetBeans module. Java Client generation uses the Web Services Manager.

18.6.2 How to Generate RESTful Web Service Java Clients

NetBeans IDE can generate a Java client for a RESTful service based on the Jersey Client API. The client code can be generated in an existing Java class, or the IDE can generate a client class in a Java application, Web application, or NetBeans module. Java Client generation uses the Web Services Manager.

How To Generate a RESTful client In an Existing Java Class

Use the Insert Code feature to insert RESTful service client code into a Java class.

To insert RESTful client code:

In the Java editor, Press Alt+Insert, or right-click and select Insert Code from the context menu. A menu of code to insert opens.

Browse for either a NetBeans project or a service registered in the IDE's Web Services Manager. You can register a service in the Web Services Manager if you have the URL of the service's WSDL or WADL.

You might need to set the authentication and class name. In most cases, the authentication and class name are read from the WADL and set automatically. You can also select whether to authenticate over SSL.

Click OK. A dialog opens asking if you want to generate Java objects from the XML schema references in the WADL file. Click Yes.

The IDE generates the RESTful client code. You still need to put in any authentication keys and write additional implementation code.

How to Create a Client Class In an Application or Module

NetBeans IDE can generate a client class in a Java application, web application, or NetBeans module.

If you are generating a class in a NetBeans module, that module needs the RESTful Web Service Libraries and their dependencies on the module's classpath.

To create a client class:

In the Projects window, select the node of the Web application, Java application, or NetBeans module in which you want to create a RESTful client class.

Launch the New File wizard (Ctrl+N, or New File icon, or context menu of the node).

In the New File wizard, select the Web Services category and the RESTful Java Client file type. Click Next. The New RESTful Java Client panel opens.

Name the class and name the class package.

Browse for either a NetBeans project or a service registered in the IDE's Web Services Manager. You can register a service in the Manager if you have the URL of the service's WSDL or WADL.

You might need to set the authentication and class name. In most cases, the authentication and class name are read from the WADL and set automatically. You can also select whether to authenticate over SSL.

Click OK. A dialog opens asking if you want to generate Java objects from the XML schema references in the WADL file. Click Yes.

(NetBeans module only) If you need to add modules to the classpath, right-click the module's node and open its Project Properties. Go to the Libraries section, and add the modules with the Add Dependency button. This button opens a list of module dependencies to browse.

The IDE generates the RESTful client code. You still need to put in any authentication keys and write additional implementation code.

18.6.3 How to Generate RESTful Web Service JavaScript Clients

For a local project that contains REST resource you can generate a JavaScript client that makes it easy for client applications to access the RESTful service. You can use a wizard in the IDE to generate JavaScript clients in web applications and HTML5 applications. In the wizard you also have the option of specifying a table as the user interface.

Perform the following steps to generate a JavaScript client for a RESTful web service.

Specify a name and location for the generated HTML file. Click Finish.

When you click Finish the IDE generates the JavaScript file in the location that you specified in the wizard. If you selected Tablesorter as the UI for the client, the IDE generates the HTML file with the name and in the location that you specified.

18.6.4 How to Use the Web Services Manager

The Web Service Manager is an expanded set of functionality added to the Web Services node in the IDE's Services tab. The RESTful Java Client wizards use the Web Service Manager. In addition, you can drag and drop SaaS operations from the Manager into PHP code, to create PHP RESTful clients. You can register a web service from a local file or from the service's WSDL or WADL.

In the Add Web Service dialog box, browse for the local file or type the URL of the service's WSDL or WADL file.

If necessary, set the proxy for the service or manually set the package name. Click OK.

To add SaaS operations to a web application:

Go to the related homepage of the web service and obtain the required keys and codes, if necessary.

Open the web service class where you want to add the service in the editor.

Expand the Web Services node in the Services window and drag the resource from the tab into the editor.

Supply any required information in the dialog boxes

All the plumbing code for accessing the service is generated by the IDE when you finish the drag-and-drop action.

To access SaaS Service API documentation:

Right-click the resource node under the Web Services tab in the Services window and choose View API Documentation in the popup menu.

To open the service WSDL or WADL

Right-click the resource node under the Web Services tab in the Services window and choose View WSDL/WADL in the popup menu.

18.7 Deploying and Testing Web Services and Clients

This section describes how to test JAX-WS or RESTful web services.

18.7.1 How to Test a JAX-WS Web Service

For JAX-WS web services, depending on the container to which you deploy the web service, the IDE may provide you with functionality for testing the web service:

GlassFish Open Source Edition and Oracle WebLogic Application Servers. The GlassFish and WebLogic servers come with their own Tester applications. When you right-click a web service node in the Projects window and choose Test Web Service, the IDE's default browser opens at this location:

context_path/web_service_nameService?Tester

The form that opens lets you test your web service implementation.

Tomcat Web Server. When you test a web service deployed to the Tomcat Web Server, the browser opens and a web page is displayed, informing you that deployment has succeeded. To access this web page, right-click a web service node in the Projects window and choose Test Web Service. The IDE accesses this URL:

context_path/web_service_name?Tester

18.7.2 How to Test a RESTful Web Service

The IDE can generate a test client for RESTful web services.

Note:

For a full NetBeans tutorial that shows how to test RESTful web services, see the following document:

Right-click the RESTful Web Services node in the Projects window and choose Test RESTful Web Services in the popup menu.

The server is started, if it is not running already, and the web services are shown in a web page in the default browser. In the browser, you will find buttons and drop-down lists for testing the methods exposed by the web services made available by the project.

18.8 Creating Handlers

A handler is a Java class that provides a filtering mechanism for preprocessing and postprocessing the web service message, by intercepting it and acting on the request or response.

SOAP message handlers are user-written Java classes that can modify a SOAP message, which represents an RPC request or response. Handlers can be associated with a web service or web service client. A handler has access to the body and header blocks of a message, but not to the application code. Handlers are usually designed to work with the header blocks and to supplement the processing done by the application code.

Typical uses of handlers include:

Logging and auditing

Encryption and decryption

Caching of data

There are two types of handlers: message handlers and logical handlers.

18.8.1 How to Create a Handler

Follow these steps to create a handler.

Right-click the project node for a web application or an EJB module and choose New > Other.

Under Categories, select Web Services. Under File Types, choose one of the following, depending on your needs:

Message Handler. Creates a simple message handler. Message handlers intercept the message as it makes its way from the client to the service and vice-versa. The generated class performs simple logging of the message request.

Logical Handler. Allows access to the message payload (but not headers or other protocol-specific information).

Name the handler and select or define the package that will contain it.

In the Source Editor, modify the default handler to suit your requirements.

18.8.2 How to Configure Handlers

When you configure a handler, you register it in the application's general deployment descriptor. The IDE automates the configuration of message handlers, when you take the steps below.

To configure a message handler:

In the Projects window, do one of the following:

For web services, expand the Web Services node, right-click the node for the web service and choose Configure Handlers.

For web service clients, expand the Web Service References node, right-click the node for the web service and choose Configure Handlers.

18.8.3 Testing and Using Handlers

The server.log file is displayed. For example, a logging message similar to the following is included if you used the default message handler:

message: Wed Jan 12 16:56:48 CET 2012--sayHi String_1:John |#]

This is the logging message generated by the SOAP message handler.

18.9 Using JAXB for Java-XML Binding

The Java Architecture for XML Binding API (JAXB) makes it easy to access XML documents from applications written in the Java programming language. It is the standard API for this activity.

The IDE provides tooling support for JAXB, principally by means of a wizard that turns various types of XML documents into Java classes. (To use it, choose XML > JAXB Binding in the New File wizard.) In addition, code templates are provided for marshalling and unmarshalling Java code to XML and back.

18.9.1 How to Generate Java Classes from XML Schema

You can use the JAXB Wizard to generate Java classes from an XML schema file. Once you have the classes, you can use them in a variety of scenarios to traverse the elements and attributes of the XML schema file.

To generate Java classes from an XML schema document:

Make sure that you have installed the full distribution of the IDE, since the JAXB Wizard is only provided with the full distribution.

Create a project type to store the code that you will generate from the XML file. The JAXB Wizard can be used with the 'Java Application', 'Java Class Library', 'Web Application' and 'EJB Module' project types.

In the Projects window or Files window, right-click the project node and choose New > Other. In the New File wizard, choose JAXB Binding from the XML category. Click Next.

In the wizard, fill in the fields as described below:

Binding Name. Specifies the name of the new JAXB binding, which will be used to identify it.

Project. Displays the name of the current project.

Schema File. The file that you want to work with can either be available locally or on-line.

Schema Type. The following types of XML document are supported:

- XML Schema

- Relax NG

- Relax NG Compact

- XML DTD

- WSDL

Package Name. Specifies the package to which the Java objects will be generated.

Compiler Options. Many compiler options are available, as described here in the Java EE 5 Tutorial. However, in relation to the JAXB Wizard, only the following are relevant and you can set them using checkboxes in the wizard:

- nv. Do not perform strict validation of the input schemas. By default, strict validation of the source schema is performed before processing. This does not mean the binding compiler will not perform any validation; it simply means that it will perform less-strict validation.

- readOnly. Force the compiler to mark the generated Java sources read-only. By default, the compiler does not write-protect the Java source files it generates.

- npa. Suppress the generation of package level annotations into **/package-info.java. Using this switch causes the generated code to internalize those annotations into the other generated classes.

- Use Extension. By default, the compiler strictly enforces the rules outlined in the Compatibility chapter of the JAXB Specification. In the default (strict) mode, you are also limited to using only the binding customizations defined in the specification. By using this option, you will be allowed to use the JAXB Vendor Extensions.

Use Binding File. Lets you import and edit one or more JAXB binding customization files.

Use Catalog File. Lets you import and edit OASIS catalog files.

Click Finish.

Open the Files window, and notice that the Java classes have been generated in the build folder.

18.9.2 How to Marshall XML Elements From Java Classes

The Java Architecture for XML Binding API (JAXB) provides a client application the ability to convert Java classes into a hierarchy of XML elements. The IDE provides a code template that you can use to generate a code snippet as the basis for this task.

To marshall Java classes to XML elements:

Type jaxbm in the Source Editor for Java files and then press Tab. The snippet is created, as follows:

18.9.3 How to Unmarshall XML Elements to Java Classes

The Java Architecture for XML Binding API (JAXB) provides a client application the ability to convert XML data into a tree of Java classes. The IDE provides a code template that you can use to generate a code snippet as the basis for this task.

To unmarshall XML elements to Java classes:

Type jaxbu in the Source Editor for Java files and then press Tab. The snippet is created, as follows:

Message optimization. Ensures that Web services messages are transmitted over the Internet in the most efficient manner. Message optimization is achieved in Web services communication by encoding messages prior to transmission and then de-encoding them when they reach their final destination.

Reliable messaging. Measured by a system's ability to deliver messages from point A to point B without error.

18.10.1 How to Configure Quality of Service

The Quality of Service tab in the Web Service Attributes Editor is for configuring components that enable interoperability between Java web services and .Net web services.

To access the Quality of Service tab:

In the Projects window, expand the project node for the project where your web service or client is defined.

For web services, expand the Web Services node, for web service clients, expand the Web Service Clients node. Right-click the node for your web service or client and choose Edit Web Service Attributes from the pop-up menu.

The Web Service Attributes Editor opens with the Quality of Service tab open.

On the service side, you can now use the Service Port Binding subsection, the Operation subsection, the Input Message subsection, and the Output Message subsection. On the client side, you can use the Transport subsection, the Security subsection, and the Advanced Configuration subsection.

18.10.2 How to Set Port Binding

In the Quality of Service tab's Port Binding section, on the service side, you can configure MTOM, reliable messaging, and interoperable security policy.

To set port binding options:

Right-click the web service that you want to edit in the Projects window and choose Edit Web Service Attributes in the popup menu.

Click the Quality of Service tab and expand the Port Binding node (if not already expanded).

Specify the Version Compatibility option.

You can select the .NET/METRO version compatibility from the drop-down list. To enable more recent versions of .NET, you must add the latest METRO library to your project classpath.

Select any other options that you want to enable.

The port binding options in the Quality of Service tab are disabled by default.

Click OK.

To add a METRO library to the classpath:

Right-click your project's node in the Projects window.

Select Properties. The Properties dialog opens.

In the Properties dialog, select the Libraries category.

Leave the Compile tab selected and click the Add Libraries button. A list of available libraries opens.

18.11 Securing an Operation

In the Operation section of the Quality of Service tab, on the service side, you can add Quality of Service security to a specific web service operation.

At times, you may need to configure different operations with different supporting tokens. You may wish to configuring security at the operation level, for example, in the situation where only one operation requires a UsernameToken to be passed and the rest of the operations do not require this, or in the situation where only one operation needs to be endorsed by a special token and the others do not.

In the Operation section of the Quality of Service configuration editor, you can select the following options for securing a web service operation:

Transaction. Select an option from the Transactions list to specify a level at which transactions will be secured. For this release, transactions will only use SSL for security.

Secure This Operation. Select this option to secure the web service operation. This option will be grayed out if Secure All Service Operations (in the PortBinding section) is selected because it would be redundant. Once selected, the list of security mechanisms is enabled.

Security Mechanism. Select a security mechanism from the list. The security mechanisms are fully functional as selected.

18.11.1 How to Secure an Operation's Input Messages

In the Input Message section you can specify the parts of the incoming message that require integrity protection (digital signature) and/or confidentiality (encryption). When you do this, the specified part of the message, outside of security headers, requires signature and/ or encryption. For example, a message producer might submit an order that contains an orderID header. The producer signs and/or encrypts the orderID header (the SOAP message header) and the body of the request (the SOAP message body). Parts that can be signed and/or encrypted include the body, the header, the local name of the SOAP header, and the namespace of the SOAP header.

You can also specify arbitrary elements in the message that require integrity protection and/or confidentiality. Because of the mutability of some SOAP headers, a message producer may decide not to sign and/or encrypt the SOAP message header or body as a whole, but instead sign and/or encrypt elements within the header and body. Elements that can be signed and/or encrypted include an XPath expression or a URI which indicates the version of XPath to use.

How to secure an operation's input message:

Right-click the web service that you want to edit in the Projects window and choose Edit Web Service Attributes in the popup menu.

Click the Quality of Service tab and expand the Operation node.

Expand the Input Message node.

The options that are available under the Input Message node depend upon the Security Mechanism of the service.

Select the security options for the message.

If available for your security mechanism, you can click Message Parts to specify which parts of the message need to be encrypted, signed, and/or required.

Click OK.

18.11.2 How to Secure a Message

You can use the Message Security Bindings dialog box to specify the message security bindings for a web service endpoint or port. You can create and modify the security bindings by opening the deployment descriptor XML file in the visual editor. You can edit the XML file manually or use the dialog boxes in the visual editor to help you edit the bindings.

To edit message security bindings:

Expand the Configuration Files node in the Projects window and double-click the XML file to open the file in the visual editor.

Click the Web Services tab in the visual editor.

Expand the node for the Service Reference.

Expand the Port Information node.

Click Edit Bindings to open the Message Security Bindings dialog box.

In the Message Security Bindings dialog box the Authorization Layer specifies the message layer at which authentication is performed. The value must be SOAP.

Specify or edit the Provider ID.

The Provider ID specifies the authentication provider used to satisfy application-specific message security requirements. If not specified, a default provider is used, if it is defined for the message layer. If no default provider is defined, authentication requirements defined in the message-security-binding are not enforced.

Click New to create a Message Security Entry or select an entry and click Edit to open the Message Security dialog box.

Enter a Java Method Name and select the authorization values from the drop-down list. Click OK.

18.11.3 How to Secure an Operation's Output Messages

In the Output section you can specify the parts of an outgoing message that require integrity protection (digital signature) and/or confidentiality (encryption). When you do this, the specified part of the message, outside of security headers, requires signature and/ or encryption. For example, a message producer might submit an order that contains an orderID header. The producer signs and/or encrypts the orderID header (the SOAP message header) and the body of the request (the SOAP message body). Parts that can be signed and/or encrypted include the body, the header, the local name of the SOAP header, and the namespace of the SOAP header.

You can also specify arbitrary elements in the message that require integrity protection and/or confidentiality. Because of the mutability of some SOAP headers, a message producer may decide not to sign and/or encrypt the SOAP message header or body as a whole, but instead sign and/or encrypt elements within the header and body. Elements that can be signed and/or encrypted include an XPath expression or a URI which indicates the version of XPath to use.

How to secure an output message:

Right-click the web service that you want to edit in the Projects window and choose Edit Web Service Attributes in the popup menu.

Click the Quality of Service tab and expand the Operation node.

Expand the Output Message node.

The options that are available under the Input Message node depend upon the Security Mechanism of the service.

Select the security options for the message.

If available for your security mechanism, you can click Message Parts to specify which parts of the message need to be encrypted, signed, and/or required.

Click OK.

18.11.4 How to Set Transport Options

In the Quality of Service tab's Transport section, on the client side, you can select optimal encoding or optimal transport for web service clients interoperating with web services.

How to set transport options (client side):

Right-click the web service that you want to edit in the Projects window and choose Edit Web Service Attributes in the popup menu.

Click the Quality of Service tab and expand the Transport node.

Select the transport options for the client.

Click OK.

18.11.5 How to Set Client Security

In the Quality of Service tab's Security section, on the client side, you may configure a user name and password for some of the security mechanisms. For this purpose, you can use the default Username and Password Callback Handlers (when deploying to the Application Server), specify the default SAML Callback Handler, specify a default user name and password for development purposes, or create and specify your own Callback Handlers if the container you are using does not provide defaults.

How to set client security (client side):

Right-click the web service that you want to edit in the Projects window and choose Edit Web Service Attributes in the popup menu.