NetBeans IDE 5.0 Quick Start Guide for Web Services
Feedback
Sample Projects |
Just want to play with some web services?
In the IDE, choose File > New Project, then expand
Samples folder. The IDE includes samples from the Java
BluePrints Solution Catalogue. |
Web services are distributed application
components that conform to standards that make them externally available. The proliferation
of distributed environments has created a need for an enterprise to be able to expose all
or part of the functionality of an application to other applications over an open network.
Web services solve
the problem of integrating applications that have been developed
independently and run on a variety of software and hardware platforms.
NetBeans IDE 5.0 comes bundled with web service support based on JSR-109,
which is a development paradigm that is suited for J2EE development, based on JAX-RPC (JSR-101).
Web service functionality in NetBeans IDE 5.0 is part of an
end-to-end set of J2EE features. Also, NetBeans IDE 5.0 provides wizards to create web services
and web service clients.
In this tutorial, you implement one of the following scenarios:
- A web service exposed by a servlet.
- A web service exposed by a session bean.
Note that you must choose which of these two scenarios you want to implement.
This tutorial covers the following topics:
After you have installed and set everything up, this tutorial can be completed in 30 minutes.
Setting Up Your Environment
Before you start writing code, you have to make sure you
have all of the necessary software and that your server is set up correctly.
Installing the Software
Before you begin, you need to have the following software installed on your computer:
- NetBeans IDE 5.0 (download).
- Sun Java System Application Server Platform Edition 8 2005Q1 (download)
- Java Standard Development Kit (JDKTM) version
1.4.2 (download)
or 5.0 (download)
Registering the Server
Before you can work with web services, you have to register an instance
of the Sun Java System Application Server. If you installed the NetBeans IDE 5.0/Sun Java System Application
Server bundle, the local Sun Java System Application Server is registered automatically.
- Choose Tools > Server Manager from the main window.
- Click Add Server. Select the server and give
a name to the instance. Then click Next.
- Specify the installation directory of the application server (for example,
C:\Sun\Appserver).
- Leave the Register Local Default Domain radio button selected and
select a domain.
- Optionally, click Next and enter your administrator username and password.
If you do not want to store the username and password in your IDE user directory,
you can leave these fields blank. The IDE will prompt you every time it
needs the information.
Note: The default admin password for the Sun Java System Application Server is adminadmin.
- Click Finish.
- Click the Runtime window and expand the Servers node. The new server instance is listed.
- Right-click the application server's node and choose Start Server.
Developing the Web Service
Coding web services is easy. The IDE takes care of all the implementation
details for you, so you can concentrate on coding the business logic of your web service.
Create the Project
- Decide whether you want to expose the web service from a web application
or from a session bean.
- Choose File > New Project (Ctrl-Shift-N) and, depending on your decision in the previous step, do one of the following:
- Under Categories, select Web. Under Projects, select Web Application. Click Next.
- Under Categories, select Enterprise. Under Projects, select EJB Module. Click Next.
- Name the project HiWS, change the Project Folder to any folder on your computer, and
make sure that the server of your choice is selected in the Server drop-down list. Note that only servers that have
been registered with the IDE are available in the Server drop-down list.
- Click Finish.
Create the Web Service
- Right-click the project node and choose New > Web Service.
Name the web service HiWS, type org.me.hi in the
Package field, and click Finish.
Wait a few seconds while the web service is created and compiled. An implementation class called HiWSImpl.java (in
web applications) or a session bean called HiWSBean.java (in EJB modules)
opens in the Source Editor.
- In the Projects window, expand the Web Services node, right-click
the HiWS web service node, and choose Add Operation. Type sayHi
in the Name field and type String in the Type drop-down list.
Click Add and define a parameter named s of type java.lang.String.
Click OK.
- Click OK in the Add Operation dialog box to create the operation skeleton.
Expand the Source Packages node and the org.me.hi node. Double-click the HiWSSEI.java node
and notice that the operation has been declared in the interface class and that the java.rmi.RemoteException exception is
thrown.
- In the Source Editor, fill out the operation skeleton in the implementation class or session bean. This class is
either HiWSImpl.java (in
web applications) or HiWSBean.java (in EJB modules).
Do this by replacing "return null;" with the following code in the body of the sayHi operation:
return "Hi " + s + "!";
The new sayHi method should now look as follows:
public java.lang.String sayHi(java.lang.String s) throws java.rmi.RemoteException {
return "Hi " + s + "!";
}
Generate and Configure a SOAP Message Handler for Logging
Optionally, you can enrich the web service with functionality provided by SOAP message handlers. In this
optional section you create a logger.
- Right-click the project node and choose New > File/Folder. Under Categories,
choose Web Services. Under File Types, choose Message Handler. Click Next.
- Name the message handler HiWSLogger, select org.me.hi
in the Package drop-down list, and click Finish.
An implementation class called HiWSLogger.java is created
and opens in the Source Editor. Without adding or changing any code,
you now have a logger, because the default code provided by the IDE's message handler template provides
complete logger functionality.
- In the Projects window, expand the Web Services node, right-click the HiWS node
and choose Configure Handlers. In the Configure SOAP Message
Handlers dialog box, click Add and browse to the HiWSLogger class. Click OK.
The message handler class is listed in the dialog box.
- Click OK to complete the configuration of the SOAP message handler.
Expand the Configuration Files node.
Double-click the webservices.xml node and notice that the handler has been declared.
Exposing the Web Service
When you expose the web service, you make it available for consumption by clients.
You can use the IDE as a client, so that you can test it after deployment.
Deploy the Web Service
Depending on how you have implemented the web service, do one of the following:
- For web services implemented as web applications, do the following:
- Choose Tools > Options and select your browser from
the Web Browser drop-down list. Click OK.
- Right-click the HiWS project node in the Projects window and choose Properties. In the
Project Properties dialog box, select the Run pane. Type /HiWS?WSDL in
the Relative URL text box. The Relative URL text box specifies the URL relative to the context path to run
as entry point to the application.
Click OK.
- If you are behind a corporate firewall and you need to set the
proxy host and port number, see Troubleshooting.
- Right-click the HiWS project node in the Projects window and choose Run Project.
The
server is started and the web service is deployed. You should see the web service's WSDL file
displayed in your browser. The WSDL file publishes the endpoints of your web service, so that the
developer responsible for creating the web service client can know what kind of functionality the web
service can provide.
- For web services implemented as session beans, right-click the HiWS project in
the Projects window and choose Deploy Project. The
server is started and the web service is deployed. Note that session beans do not display
in a browser.
The web service
must remain deployed for you to be able to create the web service client in the "Consuming the Web Service" section.
Register and Test the Web Service
- In the Projects window, expand the Web Services node,
right-click the HiWS web service node, and choose Add to Registry.
You might receive an error message that looks similar to the following:
Unable to add web service to registry. Make sure it has been deployed,
the server is running, and the correct WSDL URL was entered.
If you receive this error message, make sure that the web service is deployed
and then choose Add to Registry again.
A dialog box appears with a suggested URL to be used to register the web service.
- Make a note of the URL because you will need it later when you create the web service client.
Click OK.
- In the Runtime window (Ctrl-5), expand the Web Services node and keep expanding the
nodes until you reach the sayHi node. Right-click the sayHi node and choose
Test Operation. In the Test Web Service Operation dialog box, type "John" in the
Value text box and click Submit. The result "Hi John!" is displayed at the bottom of the
dialog box. Click Close.
- View the server log to see the log message generated by the message handler.
For example, if you use the Sun Java System Application Server, expand the Servers node in the Runtime window, right-click the
server's node, and
choose View Server Log. The server.log file is displayed
and a message similar to the following is included at the end:
|Log message: Wed Sep 07 10:47:45 CEST 2005--sayHi String_1:John |#]
This is the logging message generated by the SOAP message handler
that you created in the previous section.
Now that you have tested the operation, and are satisfied that the web service works and is potentially useful
to others, you can leave it deployed so that it can be consumed by clients that need it.
Consuming the Web Service
Consuming a web service is what a client does when it uses a web service. It is easy to use the IDE
to set up a client so that it consumes a web service. You use a wizard to import the WSDL
file that describes the web service's interface. Then you integrate it within the client
so that the web service does something useful for you.
Note: A web service can be consumed
in a web application or a Java application. In the example that follows, you will only consume the web service
in a web application. For more information on web service clients, whether implemented in web applications or
Java applications, see the NetBeans IDE 5.0 Quick Start Guide for Web Service Clients.
Create the Web Application Project
- Choose File > New Project (Ctrl-Shift-N). Under Categories,
select Web. Under Projects, select Web Application. Click Next.
Name the project HiWSClient, change the Project Folder
to any folder on your computer, and make sure that the server
of your choice is selected in the Server drop-down list. Click
Finish.
Discover Information About the Web Service
- Right-click the HiWSClient project node and choose New > Web Service Client.
Copy and paste the URL of the running web service in the WSDL URL text box. For example,
the URL might be as follows:
http://localhost:8080/HiWS/HiWS?WSDL
- Click Retrieve WSDL. When the Local Filename text box is filled with the WSDL file's name,
the WSDL file has been correctly retrieved. Type org.me.hi in the
Package field.
- Depending on the server, do the following:
- For the Sun Java System Application Server, choose J2EE Container-generated static stub.
- For other servers, such as the JBoss Application Server or the Tomcat Web Server, you may have to choose IDE-generated static stub.
- Click Finish.
- Expand the Web Service References node and keep expanding the nodes until
you reach the sayHi node. Right-click the sayHi node and choose Test Operation.
In the Test Web Service Operation dialog box, type "John" in the Value text box
and click Submit. The result "Hi John!" is displayed at the bottom of the dialog box.
Now that you have tested the operation, and are satisfied that the exposed web service
is useful to you, you are ready to develop a client-side application to interact with it.
Develop the Web Service Client
- Right-click the HiWSClient project node and choose New >
Servlet. Name the web service HiServlet, type org.me.hi
in the Package drop-down list, click Next and then click Finish.
The servlet HiServlet.java opens in the Source Editor.
- In the Source Editor, right-click within the processRequest operation in the HiServlet class. Choose
Web Service Client Resources > Call Web Service Operation, select the sayHi operation, and click OK.
- Now fill out the generated skeleton code so that it looks as follows:
try {
out.println(getHiWSSEIPort().sayHi("John"));
} catch(java.rmi.RemoteException ex) {
out.println("<p>Caught an exception <p>" + ex);
}
- Rearrange the code snippet so that it is placed between the processRequest method's <body> tags:
protected void processRequest(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
response.setContentType("text/html;charset=UTF-8");
PrintWriter out = response.getWriter();
out.println("<html>");
out.println("<head>");
out.println("<title>Servlet HiServlet</title>");
out.println("</head>");
out.println("<body>");
try {
out.println(getHiWSSEIPort().sayHi("John"));
} catch(java.rmi.RemoteException ex) {
out.println("<p>Caught an exception <p>" + ex);
}
out.println("</body>");
out.println("</html>");
out.close();
}
- Next, to enable the user to interact with the web service, add a form to the servlet
and pass the user's input to the web service (only the code in red below is different to the
code above):
protected void processRequest(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
response.setContentType("text/html;charset=UTF-8");
PrintWriter out = response.getWriter();
out.println("<html>");
out.println("<head>");
out.println("<title>Servlet HiServlet</title>");
out.println("</head>");
out.println("<body>");
out.println("<p>Enter your name:</p>");
out.println("<form method=\"get\">");
out.println("<input type=\"text\" name=\"name\" size=\"25\">");
out.println("<br>");
out.println("<p>");
out.println("<input type=\"submit\" value=\"Submit\">");
out.println("</form>");
String name = request.getParameter("name");
if ( name != null ) {
try {
out.println(getHiWSSEIPort().sayHi(name));
} catch(java.rmi.RemoteException ex) {
out.println("<p>Caught an exception <p>" + ex);
}
}
out.println("</body>");
out.println("</html>");
out.close();
}
Don't forget to change the String "John" to the variable name, as shown in the code above!
Deploy the Web Service Client
- Right-click the HiWSClient project node in the Projects window and choose Properties. In the
Project Properties dialog box, select the Run pane. Do the following:
- Select the server in the Server drop-down list.
- Type /HiServlet in the Relative URL textbox.
- Click OK.
- Right-click the HiWSClient project in the Projects window and choose Run Project.
The
web service client is deployed. You should see something similar to the following
displayed in the IDE's default browser:
- Type "John" and click Submit. You should now see the following:
Troubleshooting
Since the IDE provides most of the code you need for communicating with the web service,
the only problems you should encounter are errors in your own code. In addition, though, you
might encounter a few problems if you are behind a firewall. The troubleshooting tips that follow
attempt to resolve this problem.
- Deploying to the Sun Java System Application Server. If you deploy the application without setting your proxy host and port
correctly, you will see something similar to this in your browser:
To fix this problem, do the following:
- In the Runtime window, make sure that the Sun Java System Application Server is running.
If it is running, a green arrow is shown to the left of the server's name.
- Expand the Sun Java System Application Server node, right-click the JVMs node and choose Properties.
- Click the ellipsis to the right of the JVMOptions property.
- Add the following two properties to the list:
- -Dhttp.proxyHost=my.host
- -Dhttp.proxyPort=my.port.number
Make sure that the values you set for these properties are appropriate to your environment.
- Testing in the IDE. If you test the application in the IDE without setting your proxy host and port
correctly, this error will be displayed in the IDE:
To fix this problem, do the following:
- Choose Tools > Options.
- In the Options window, set the proxy host and port number.
Next Steps
For more information about using NetBeans IDE 5.0, see the following resources:
To send comments and suggestions, get support, and keep informed on the latest
developments on the NetBeans IDE J2EE development features, join
the nbj2ee@netbeans.org mailing list.
|