RESTful WebService

From IntelliJ-Wiki

Jump to: navigation, search

Contents

Introduction

IntelliJ IDEA provides rich coding assistance and support for developing WebServices based on the Apache Axis framework. This tutorial will walk you step by step through creating and deploying the server and the client sides of a simple WebService of this type.

In this tutorial you will:

  • Install a Tomcat application server and integrate it with IntelliJ IDEA.
  • Create an IntelliJ IDEA project for the server-side of an Apache Axis WebService.
  • Experience advanced IntelliJ IDEA coding assistance and code generation features.
  • Deploy the server-side of the application.
  • Create a project for the client-side of a JAX WS WebService.
  • Generate the client code stub based on the WSDL file.
  • Access the WebService from IntelliJ IDEA using the client.

Prerequisites

  • You are working with IntelliJ IDEA Ultimate Edition 10.5 or higher. You can get it from http://www.jetbrains.com/idea.
  • Java SDK (JDK) is installed on your computer.
  • Tomcat 6 server is installed on your machine and integrated with IntelliJ IDEA. Let us configure this integration in the next section.

Integrating Tomcat Server with IntelliJ IDEA

Before we start working on an application, let’s download the Tomcat server and and integrate it with IntelliJIDEA using the application server configuration. This can be done even without an open project, because application server settings belong to the level of your workspace.

To do that, press Ctrl+Alt+S, and then under the IDE Settings (Figure 1), click Application Servers (1). On the Application Servers page, click File:add.png (2), and select Tomcat Server (3).

Figure 1. Application Servers page.

In the Tomcat Server dialog box, that opens (Figure 2), click the Download Tomcat link (1).

Figure 2. Downloading Tomcat.

On the Apache Tomcat page, that opens, choose the Tomcat version to use, click the Download button, download the relevant distribution, and extract the archive, if necessary. This tutorial is based on Apache 7.0.22. After that, return to the Tomcat Server dialog box (Figure 3) and specify two things:

  • Tomcat home (1) – the directory where you have stored the downloaded Tomcat server. Click the Browse button (3) and choose the installation location (4) in the Tomcat Home Directory dialog box, that opens.
  • Tomcat base directory (2) - the directory where Tomcat config files are located (by default the Tomcat installation directory is used).
Figure 3. Configuring the Tomcat installation.

Having defined the paths for your local Tomcat server, click OK and return to the Application Servers page (Figure 4), where IntelliJ IDEA has already assigned the Tomcat 7 name (1) to the new server configuration.

If you so need, you can extend the configuration with the various additional libraries, but for our example they are not required.

Figure 4. New Tomcat server configuration added to the Application Servers page.

That is all; your local Tomcat server is ready for running applications from IntelliJ IDEA.

Developing the Server Side

Creating a Project

Let's start from the very beginning and create a project for our application.

Choose File | New Project on the main menu or click the Create New Project icon on the Welcome screen (Figure 5).

Figure 5. Welcome Screen. Create New Project.

On the first page of the New Project wizard (Figure 6), make sure that the option Create project from scratch is selected.

Figure 6. Create project from scratch.

On the second page of the wizard (Figure 7), choose the parent folder (1) to create the project in and specify the name of the project (2). As you type the project name, IntelliJ IDEA updates the path to the location of the project files accordingly. Select the Create module check box (3) and choose Java Module (4) as the module type. By default, the module will have the same name (5) as the project. The name of our project and module will be jax_ws_server.

Figure 7. Creating a Java module.

On the third page of the wizard (Figure 8), choose the Create source directory option (1) and accept the default name src (2) for it. IntelliJ IDEA displays the full path to the src folder (3) for your information.

Image 8. Creating the source folder.

Now, we need to tell IntelliJ IDEA which technology our application will be based on. According to this information, IntelliJ IDEA will automatically supply all the necessary libraries and set up the module structure so it complies with the specification of the application basic technology. On the fourth page of the wizard (Figure 9), select WebServices (1) from the list of technologies. As you can see, IntelliJ IDEA selects the Web Application node (2) automatically. Next, we need to tell which exactly type of WebServices we are going to develop. To do that, choose Glassfish/JAX-WS/... (3) from the Version drop-down list. Finally, we will need framework-specific libraries, which by default are missing on our computer. Luckily, IntelliJ IDEA can download the necessary ones for you, just choose the Download option (4). IntelliJ IDEA tells you that a set of jar archives will be downloaded and that they will be arranged in a project library. This means that they will be available in the entire project, both in the current module and in any other one created. However, they will be invisible for other projects.

Figure 9. Specifying the technology to use: WebServices.

When you click Finish (5), IntelliJ IDEA creates a project and generates the skeleton of our application. We will look deeper into its structure in the section Exploring a JAX-WS WebService Application.

Enabling Support of Additional JAX-WS Implementations

By default, IntelliJ IDEA enables support for development of WebServices using the most popular JAX_WS implementations, such as:

  • Glassfish
  • JAX-WS 2.X RI
  • Metro 1.X
  • JWSDP 2.0

However, you can use other implementations, for example, Apache CXF. You just need to download the required libraries manually and tell IntelliJ IDEA where they are stored. To do that, open the Settings dialog box (Figure 10) by pressing Ctrl+Alt+S. Then under the IDE Settings (1) , click WebServices (2).

Figure 10. Enabling support of an additional WS implementation.

In the Path to XFire/CXF text box (3), specify the folder where the CXF implementation libraries are stored. Type the path manually or click the Browse button File:browseButton.png next to the text box (4) and choose the libraries location in the Select Folder dialog box that opens.

Exploring a JAX-WS WebService Application

To explore our application, we’ll use the Project tool window (Figure 11) that shows the following files and folders:

The .idea (1) folder contains a number of subfolders, mainly with internal IntelliJ IDEA information.

The src (2) folder contains the HelloWorld.java (3) file with the source code that implements the functionality of the sample application. The file belongs to the example package (4).

The WEB-INF folder contains the sun-jaxws.xml (5) JAX-WS RI deployment descriptor. This file describes the internals of a WebService, that is, what components it contains and how these component interacts with each other.

Figure 11. Examining the skeleton of the WebService project.

Let's now look closer at the generated example (Figure 12). The file HelloWorld.java (1) contains one class HelloWorld (2). Its code (3) is generated automatically and implements concatenation of a given string with Hello, world, from and sending it back to the client along with printing to the server console.

Figure 12. Generated code in HelloWorld.java and the service description in the sun-jaxws.xml.

The Web Service icon File:gutter_icon_web_service.png (6) in the gutter area indicates that IntelliJ IDEA has already exposed the HelloWorld class as Web Service. Accordingly, the definition of this Web Service (5) has been added to the sun-jaxws.xml file (4) as an endpoint tag (6) with the following attributes:

  1. The name (8) attribute defines the WebService name.
  2. The implementation (9) attribute shows the of the class that implements the WebService.
  3. The url-pattern (10) attribute shows the URL address to access the WebService relative to the server root URL.

You may also notice, that IntelliJ IDEA has inserted two annotations (7): @WebService and @WebMethod. They will be used during the generation of a WSDL contract file.

Exposing and Unexposing WebServices

Note: This section is not mandatory.

As we have just seen, IntelliJ IDEA has exposed the sample class as WebService so you do not need to do it yourself. Although it is quite sufficient for the purposes of this tutorial, still it may be helpful to learn how IntelliJ IDEA can expose and unexpose classes and methods as WebServices under your control.

Unexposing a Class as WebService

First, let's "spoil" our application by changing the WebService status of the HelloWorld class (Figure 13). Select the class name in the editor (1), then choose Web Services (2) and Unexpose Class as WebService (3) on the context menu.

Figure 13. Unexposing a class as WebService.

In the Remove WebService dialog box that opens (Figure 14), IntelliJ IDEA has already filled in the WebService name (1) and the module that implements it (2). You only need to specify the current WebService implementation type: from the Service Platform drop-down list, choose Glassfish/JAX-WS 2.X RI... (3) and click OK.

Figure 14. Unexposing a WebService: Remove WebService dialog box.

If you now take a look at the editor (Figure 15), you will notice that in HelloWorld.java (1) the Web Service icon File:gutter_icon_web_service.png is missing in the gutter area (2). Accordingly, the definition of the WebService (4) has been removed from the sun-jaxws.xml file (3).

Figure 15. WebService removed.

Finally, re-compile the application by pressing Ctrl+Shift+F9.

Exposing a Class as WebService

Now, let's "repair" our application and return it the WebService status (Figure 16). To do that, select the HelloWorld class name in the editor (1), then choose Web Services (2) and Expose Class as WebService (3) on the context menu.

Figure 16. Exposing a class as WebService.

In the Expose Class as WebService dialog box, that opens (Figure 17), IntelliJ IDEA has already filled in the name of the class (1) and the module (2) that implement the WebService. Accept the values by clicking OK.

Figue 17. Expose class as WebService dialog.

As you can see (Figure 18), the Web Service' icon File:gutter_icon_web_service.png (1) and the WebService definition (2) are back!

Figure 18. WebService repaired.

Press Ctrl+Shift+F9 to re-compile the application after fix.

Deploying a WebService

Now let's finally deploy our WebService to make sure everything works as expected. For that, we need to pack the application data to deploy and create an application server run configuration.

Packing the Application Data to Deploy

To tell the Tomcat server what to process and where to find the application data, you need to define an artifact. An artifact can be an archive (war) or an exploded directory. In our case, when the project output is stored and processed locally, it is enough to submit the data in the exploded form.

During the project setup, IntelliJ IDEA has created a default artifact jax_ws_server:war exploded.

Let’s examine the contents of this artifact more closely.

Press Ctrl+Alt+Shift+S and click Artifacts. In the Artifacts page (Figure 19), select the Show contents of elements check box (1).

Figure 10. Artifact to be deployed.
According to this artifact definition, the following will be submitted to the server:
  • The result of compiling the jax_ws_server module (2): the compiled class example.HelloWorld.
  • The contents of the web folder (3): the sun-jaxws.xml deployment descriptor.
The location of the application data to be processed by the Tomcat server is defined in the Output directory field (4).

This artifact definition is enough to have our WebService successfully deployed. You do not need to change anything here, provided that all the required static content resources are stored in the web folder root.

Creating a Run Configuration

1. On the main menu (Figure 20), choose Run (1) and then choose Edit Configurations (2):

Figure 20. Opening the Run Configurations dialog box.

2. In the Run/Debug Configurations dialog box (Figure 21), that opens, click the Add button File:Add.png (1). As we have already mentioned, we’re using a local Tomcat server, so select Tomcat Server (2) and then select Local (3) on the context menu:

Figure 21. Creating a new Local Tomcat Server configuration.

The Run/Debug Configuration: Tomcat dialog box (Figure 22] opens. As you can see, IntelliJ IDEA has already filled in some fields in the Server tab (1) based on the Tomcat server integration settings:

  • The server configuration name Tomcat 7 is selected from the Application Server drop-down list (3). You can change the configuration by clicking the Configure (4) button.
  • The default name of the run configuration Tomcat 7 is specified in the Name (2) text box.

The HTTP port text box (9) shows the default port 8080 for the Tomcat server according to the Tomcat server native configuration file, and it is strongly recommended that you do not change this setting.

Technically, our application is intended for accessing from a client and we do not need to view its internals in the browser. However, it may be helpful to view the deployment details in the browser and thus make sure the WebService has been deployed correctly. In the Open browser (5) area, select the Start browser check box (6) and specify the URL address of the page to open upon the server start up (10). This URL address is composed of the server root URL with the default port http://localhost:8080 and the value of the url-pattern attribute of the endpoint element as it is specified in the JAX-WS RI deployment descriptor.

Finally, we need to tell the run configuration what to deploy. As you can see, IntelliJ IDEA has noticed that this information is missing and warns (7) us about this discrepancy.

Figure 22. Tomcat run configuration: Server tab.

Luckily, the IDE "knows" that we have configured an artifact and suggests a solution for the problem. Click the Fix (8) button: the Deployment tab (Figure 23) opens:

Figure 23. Tomcat run configuration, Deployment tab: artifact detected.

As you can see, the jax_ws_server:war exploded artifact (1) is already detected and added to the Deploy on the server start-uplist (2). Moreover, IntelliJ IDEA suggests to build this artifact automatically. Accept this suggestion by leaving the Build artifact check box (3) selected.

Finally, IntelliJ IDEA has already specified the application context root in the Application context (4) drop-down list. For the sake of simplicity, let's have the application deployed to the server root, so just accept the default setting / (5), and then click OK (6) to save the run configuration.

Running the WebService on a Local Tomcat Server

Now everything is ready to run, so just make sure (Figure 24) the configuration is selected (1) on the toolbar and click the Run button File:run.png (2) or press SHIFT+F10.

Figure 24. Starting the application.

IntelliJ IDEA starts the server (Figure 25), compiles, deploys, and runs the application.

Figure 25. Tomcat server running.

As you probably remember, when creating a run configuration we told IntelliJ IDEA to open the browser. The application start-up page, that opens (Figure 26), shows WebService details (1), among them the URL address of the WSDL contract file (2). This file describes how the WebService can be accessed from a client, which input data it requires and which output data it returns. The file is generated on-the-fly during deployment and is vitally important because the client side can be generated correctly only on the basis of the data stored in it.

Figure 26. WebService start-up page.

Now we are sure that uur WebService is now running and we’re ready to move forward.

Developing a WebService Client

Obviously, a WebService itself is worth nothing unless it can be requested from a client. In the second part of the tutorial, we will develop a client for our WebService and run it right from IntelliJ IDEA.

Creating a Project

We need to create another project, jax_ws_client, for the client side. It’s essentially the same procedure as we used when developing the server side in the beginning of this tutorial. The only difference is that we have another selection of supported technologies (Figure 27). Namely, select the WebServices Client check box (1), and then choose Glassfish/JAX-WS... from the Version drop-down list (2).

Figure 27. Specifying the technology to use: WebServices Client.

When you click Finish (3), IntelliJ IDEA asks you whether you want to open new project in a new window or in the current one. Click New Frame, because you will need to reference the server-side project.

Generating Client Stub

After the project is created, the Generate Java Code from Wsdl or Wadl dialog box opens (Figure 28).

IntelliJ IDEA has already filled in the output path <project_root>/src(1) and the default package prefix example(2) for us. All we need to do here is specify the location of the WSDL contract file to be used as the base for generating the stub code for the Client. The WSDL file is generated on-the-fly when the server side of a WebService is being deployed.

Normally, the URL address of the WSDL file is provided by the customer. In our case, we have just developed and deployed a WebService ourselves. Moreover, IntelliJ IDEA has opened the WebService start-up page that shows - among other WebService information - the URL address of the WSDL file. Copy this URL and paste it in the WebService wsdl URFL field (3).

Figure 28. Generating Client stub from Wsdl.

Click OK (4) to complete project creation. IntelliJ IDEA generates the required Client project structure (Figure 29). The src folder (3) contains an example subfolder (1) with a number of generated classes and interfaces, among them the HelloWorldClient main class (2) which is automatically opened in the editor.

Note: You can open Generate Java Code from Wsdl or Wadl dialog box by choosing Tools | WebServices | Generate Java Code from Wsdl or Wadl and re-generate the contents of the example subfolder at any time. However, the HelloWorldClient class is generated automatically only during project creation.

Figure 29. Client project structure generated.

As you can see, the HelloWorldClient is underlined red, which means that it contains some errors. That is correct, because actually it is just a stub. IntelliJ IDEA has already opened it in the editor (Figure 30), so we can examine and complete it, as required.

Figure 30. HelloWorldClient stub generated.

Completing the Client Stub

Let's now complete the stub step by step using the code assistance provided by IntelliJ IDEA.

Generating Code by Completing a Live Template

As you can see from Figure 31, the generated stub contains a Live Template where incomplete code is displayed red. To fix the problem, we will move from one template element to another by pressing the Tab keyboard button and complete the code using coding assistance provided by IntelliJ IDEA.

The first element of the live template example.HelloWorld (1) is shown in a red frame. Position the cursor at this element and press Tab until the focus (red frame) moves to HelloWorldService() (2). IntelliJ IDEA shows a pop-up where suggests example.HelloWorldService (3) for inserting in the template.

Figure 31. Completing the stub: Step 1.

Accept the suggestion by pressing Enter. As you can see from Figure 32, IntelliJ IDEA replaces the template element in focus (1) with the accepted suggestion (2).

Figure 32. Completing the stub: Step 2.

Besides that, the cursor moves to the next "gap" in the code (3), and a pop-up suggestion list is immediately displayed where the most relevant candidate for completion getHelloWorldPort (4) comes first. Accept the suggestion by pressing Enter. Figure 33 illustrates the result.

Figure 33. Completing the stub: Step 3.

Writing the WebService Invocation

The only thing we still do not have is invocation of our WebService. However, from Figure 34 you can see that there is a code fragment service.(); (1), which actually is a part of it.

Figure 34. Completing the stub: Step 4, writing the WebService invocation.


Let's complete the method invocation as follows (2):

String response = service.sayHelloWorldFrom("John");

And add one line (3) to have the method output printed in the Client console. At any time, press Ctrl+Space to have IntelliJ IDEA display suggestion lists and provide coding assistance.

System.out.println(response);

That's all, now our code should look as follows:

package example;

public class HelloWorldClient {
  public static void main(String[] argv) {
      example.HelloWorld service = new example.HelloWorldService().getHelloWorldPort();
      //invoke business method
      String response = service.sayHelloWorldFrom("John");
      System.out.println(response);
  }
}

Running the Client

Now we can request our WebService right from IntelliJ IDEA using our client application. We only need to create a run configuration and launch the client using it.

Creating a Run Configuration

1. On the main menu (Figure 35), choose Run (1) and then choose Edit Configurations (2):

Figure 35. Opening the Run Configurations dialog box.

2. In the Run/Debug Configurations dialog box (Figure 36), that opens, click the Add button File:Add.png (1). We need just a simple configuration for running Java applications, so select Applicationon the context menu:

Figure 36. Creating a run configuration of the type Application.

The Run/Debug Configuration: Application dialog box (Figure 37) opens. First of all, we need to give it a name (1), for example, JaxWSHelloWorldClient. As you can see, IntelliJ IDEA has already specified the classpath to use (2) and the working directory (3).

Figure 37. Creating an Application run configuration: no main class specified.

All we need to do is specify the class that contains the main method (4). To do that, click the Browse button (5) next to the Main class text box. In the Choose Main Class dialog box (Figure 38), that opens, switch to the Project tab (1) and select the HelloWorldClient class (2) from the example package (3) under the src folder (4).

Figure 38. Specifying the main class.

When you click OK, you return to the Run/Debug Configuration: Application dialog box (Figure 39) where the Main class text box (1) shows the fully qualified name of the selected class example.HelloWorldClient.

Figure 39. Creating an Application run configuration: main class specified.

Click OK (2) to save the configuration.

Launching the Client

  1. Switch to the jax_ws_server project window and make sure that the Tomcat server is running].
  2. In the the jax_ws_client project window (Figure 40), choose ApacheAxisHelloWorldClient (1) on the toolbar,

and then click the Run button File:run.png (2) or press SHIFT+F10.

Figure 40. Starting the client.

The client requests the server and prints the WebService output to the console (Figure 41):

Figure 41. WebService output: Client console.

In the meantime, we can examine the server console (Figure 42) to see that the same string has been printed there.

Figure 42. WebService output: Server console.

That’s all for now. Of course, this tutorial only covers the essential topics you will need to build an JAX-WS Web Service application with IntelliJ IDEA. There’s a lot more of things to explore and features that can help you enhance your application: integration with Hibernate, Spring, support for EJB, JSP, AJAX, integration with many popular application servers, and a whole lot more. Check out http://www.jetbrains.com/idea for additional details.

Related Articles


RESTful WS

Creating Web Service: RESTful Web Services Server

We’ve already created sample projects using Apache Axis and JAX-WS. Now, it’s time to try RESTful Web Services.

1. Run IntelliJ IDEA and start creating new project. On the technologies page of the New Project Wizard select Web Application | WebServices | RESTful Web Services.

File:restful_server_project.png

The project structure is already familiar to you, but the HelloWorld class looks a bit different.

File:restful_server_hw_code.png

In contrast to previous examples, we can run our web service right at this step, i.e. we do not need Tomcat configuration, the service can be launched using light-weight HTTP server.

Just right-click anywhere in the HelloWold class code and select Run “HelloWorld.main()”from editor popup menu, or press Ctrl+Shift+F10. IntelliJ IDEA creates temporary run\debug configuration that you can save, if you want, and runs the service.

File:restful_server_hw_run.png

Note: IntelliJ IDEA provides convenient tool window for testing RESTful web services with GET, POST, DELETE, PUT, HEAD and OPTIONS requests. Start debugging your service (right-click anywhere in the HelloWold class code and select Debug “HelloWorld.main()”), then select Tools | WebServices | RESTful Web Services | Test RESTful Web Service from the main menu to open the REST Client tool window, where you can easily browse the results of GET, POST, DELETE, PUT, HEAD and OPTIONS requests.

Creating WADL Descriptor

Before we pass on to creating RESTful client, we need to get WADL descriptor, and here is another trick. We have two ways of generating WADL:

1. The first one is similar to generating WSDL. Right-click the class name in the editor and select WebServices | RESTful Web Services | Generate WADL From Java Code. Specify Base URI and click OK.

File:restful_wadl.png

2. For the second one we’ll need REST Client tool window. While the service is running, right-click anywhere in the HelloWorld class in the editor, and select WebServices | RESTful Web Services | Test RESTful Web Service to access the tool window. Select GET from the HTTP method drop-down. Leave the Deployment end-point field as is, in the Path to resource drop-down select /application. wadl, then click Submit request button (right arrow). IntelliJ IDEA generates WADL descriptor, and displays it in the Response tab.

File:rest_tool_window.png

Creating Web Service: RESTful Web Services Client

The client part creation is also extremely similar to the ones created in this tutorial

1. Create new project. On the technologies page, select Web Services Client | RESTful Web Services. Click Finish.

2. In the dialog that appears specify the url to the generated WADL, or the path to the locally stored WADL. Client code is generated automatically:

File:restful_client_code.png

That’s all for now. Of course, this tutorial only covers the essential topics you will need to build a Web Service application with IntelliJ IDEA. There’s a lot more of things to explore and features that can help you enhance your application: integration with Hibernate, Spring, support for EJB, JSP, AJAX, integration with many popular application servers, and a whole lot more. Check out http://www.jetbrains.com/idea for additional details.

Personal tools