Step 1: Begin the Investigate Web Service

In this step, you will learn to start WebLogic Workshop and use it to begin a new web service. WebLogic Workshop is the graphical tool you use to create, implement, test, and debug web services. When working in WebLogic Workshop, you use projects to group files associated with a web service or related web services.

With WebLogic Workshop, you can also start and stop WebLogic Server. WebLogic Server provides functionality that supports web services you build with WebLogic Workshop, and so must be running while you are building a web service.

In this tutorial, you will learn how:

- To start WebLogic Workshop on Microsoft Windows

- To start WebLogic Workshop on Linux

- To open the samples project

- To start WebLogic Server

- To create a new web service

- To add a method

- To add a parameter and return value

- To add code for returning a value

- To launch Test View

- To test the requestCreditReport method

# Starting WebLogic Workshop

The first step in any process is to start the program. These sections explain how to do that on Microsoft Windows, Linux, and UNIX platforms.

To Start WebLogic Workshop on Microsoft Windows

- From the Start menu, choose Programs-->WebLogic Platform 7.0-->WebLogic Workshop.

To Start WebLogic Workshop on Linux

1. Open a file system browser or shell.

2. Locate the Workshop.sh file at the following address:

    $HOME/bea/weblogic700/workshop/Workshop.sh

3. In the command line, type the following command:

    sh Workshop.sh

When you start WebLogic Workshop for the first time after installing it, it opens to display the samples project. This project contains sample web services included with WebLogic Workshop. After it has been used for the first time, WebLogic Workshop displays the project last opened.

For this tutorial, you will use the samples project.

To Open the Samples Project

1. Choose File-->Open Project. The Open Project dialog appears.

2. In the Projects on your development server box, select samples.

3. Click Open.

Once you have opened the samples project, you must ensure that WebLogic Server is running while you build your service. All of the web services you create using WebLogic Workshop run on WebLogic Server on your development machine until you deploy them. When your web service is called by other components, WebLogic Server is responsible for invoking it.

You can confirm whether WebLogic Server is running by looking at the indicator in the status bar at the bottom of WebLogic Workshop. If WebLogic Server is running, there is a green ball as pictured here:

If instead you see the a red ball, as in the following picture, then you must start WebLogic Server before proceeding:

To Start WebLogic Server

In WebLogic Workshop, choose Tools-->Start WebLogic Server.

# Creating a New Web Service

Once WebLogic Workshop and WebLogic Server are running, you can create a new web service. When you create a new web service, you also create a new JWS file. A JWS file is very much like a JAVA file in that it contains code for a Java class. However, because a file with a JWS extension contains the implementation code intended specifically for a web service class, the extension gives it special meaning in the context of WebLogic Server.

To Create a New Web Service

1. In the Project Tree, right-click Project 'samples' and select New Folder The Create New Folder dialog appears.

Note:The Project Tree is located at the left side of the screen.

2. In the Enter a new folder name box, type financialservices , as shown here:

3. Click OK. The financialservices folder appears in the project tree.

4. Right-click the financialservices file and select New File. The Create New File dialog appears.

5. Confirm that the Web service radio button is selected, as shown in the following picture.

Note: The Java, JavaScript, and Text options provide a way for you to add those kinds of files to your project. For now, however, leave Web service selected.

5. In the File name field, type Investigate. This will be the name of your web service class.

6. Click OK.

Once you create a new service project, WebLogic Workshop displays your new JWS file, entitled Investigate.jws, in Design View. The following screen shot provides a quick tour of your project in Design View.

# Graphical Design of Services

In Design View you can design your service in a graphical manner. You create what is effectively a drawing of your service and its interactions with clients and other resources. As you design your service, WebLogic Workshop generates source code that you can edit in the Source View. Through this source code you can add logic behind your design. This enables you to create web services by focusing on application logic rather than on code for infrastructure.

While designing your service, you can add methods and events. You can add controls to represent resources such as other services, databases, and Enterprise Java Beans. You can also specify support for powerful features of the underlying server by setting properties for items in your design.

Note: A good way to get a sense of the design tasks you can perform is to click an item in your design, then view the tasks listed in the Tasks pane in the lower right corner of Design View.

One of the key features of WebLogic Workshop is tight integration between tasks you do while designing your web service and the changes you make to source code. For example, if you add a member variable to source code in Source View, your new variable will appear in Design View, and vice versa. This integration is also reflected in the Structure Pane. There you can find a list of items in your service's design, including methods, events, variables, and so on. You do not need to save or refresh the file to cause changes in one view to appear in other views.

For more complete information about projects and the files they contain, see WebLogic Workshop Projects.

# Adding the requestCreditReport Method

Web services expose their functionality through methods, which clients invoke to make requests. In this case, clients will use a method you create to request credit reports. The service you are building will eventually collect credit information from other sources. But for now, to keep things simple, you will provide a method that returns a simple report immediately. This web service will provide clients with credit ratings for loan or credit applications. So your web service will need to provide the client with a way to make the initial request. You can do this by adding a requestCreditReport method to the Investigate web service.

To Add a New Method

1. If it is not selected already, click the Design View tab to ensure that you are viewing the design for the Investigate web service.

Note: It is not necessary to be in Design View while adding methods, but it is helpful to see how changes update the design of your service.

2. From the Add Operation drop-down list, select Add Method.

3. In the space provided, replace method1 with requestCreditReport and press Enter.

Note: If you switched from WebLogic Workshop after adding the method (for example, to read this topic), the method name may no longer be available for editing. To re-open it for editing, right click its name, click Rename, then type requestCreditReport. Then press Enter.

Your design of the Investigate web service should now resemble the following illustration:

# Adding a Parameter and Logic

When making a request, the client needs to supply information about the applicant in order for the Investigate file to do its work. For this scenario, the client provides a taxpayer ID. For simplicity, you will enable this method to receive the number as a string. You will also add a return value so that the method can send back to the client the requested results.

To Add a Parameter and Return Value

1. In Design View, double-click the arrow corresponding to the requestCreditReport method.

The Edit Maps and Interface dialog appears.

2. In the Java pane in the lower section of the dialog, edit the text so that it appears as follows:

    public String requestCreditReport(String taxID)

This text is known as the method's declaration. The first occurrence of "String" is the return data type; the text "String taxID" is the parameter data type and parameter name.

3. When you have finished editing the method declaration, click OK.

Now you can add a little code to make the method do something. The code you add here will return a string value every time the requestCreditReport method is called. Obviously, this is not very useful, but you will add more intelligent functionality later.

You change a method's functionality by editing its source code.

To Add Code for Returning a Value

1. In Design View, click the name of the method, as shown in the following illustration.

The following source code appears:

    /**
     * @jws:operation
     */
    public String requestCreditReport(String taxID)
    {
    }

WebLogic Workshop added this source code while you worked in Design View.

2. Edit the requestCreditReport method code so that it returns a String. The returned code resembles the following:

    /**
     * @jws:operation
     */
    public String requestCreditReport(String taxID)
    {
        return "applicant: " + taxID + " is approved.";
    }

3. Press Ctrl+S to save your work.

As it is now written, the code for the requestCreditReport method returns a string containing the taxpayer ID the client sent with the method call and a note that the applicant was approved. Remember to press Ctrl+S to save your changes to the web service.

Notice that a comment precedes the method that contains an @jws:operation tag. This is a Javadoc comment (Javadoc comments always begin with /** and end with */). Briefly, Javadoc is a simple system for including program structure-related information in comments, indicated by tags, that may be automatically extracted to produce documentation or other material related to structure of a Java class. Its original use was to specify inline documentation that could be extracted to HTML. WebLogic Workshop uses a variety of Javadoc tags to indicate how web service code should be treated by WebLogic Server.

The @jws:operation tag indicates that the method to which it is attached should be exposed as a web service method that clients can call. The term operation refers to the actions web services expose to clients, such as the requestCreditReport method you have added here. For more information on Javadoc, please refer to the Javadoc pages at java.sun.com.

# Launching a Browser to Test the Service

The best way to test a web service while you're writing and debugging code is to use the Test View, a browser-based tool through which you can call methods of your web service. In this tutorial, you will be using two buttons in WebLogic Workshop to control display of the Test View.

To Launch Test View

- Click the Start button, which looks like the following illustration:

Note: If you want to stop Test View, click the Stop button shown here:

Clicking the Start button prompts WebLogic Workshop to build your project, checking for errors along the way. WebLogic Workshop then launches your web browser to display a page through which you can test the service method with possible values. The following illustration shows the Test Form page that appears after you click the Start button.

As you can see, this page provides tabs for access to other pages of the Test View. Test Form and Test XML provide alternative ways to specify the content of the call to your service's methods. Overview and Console include additional information and commands useful for debugging a service. The Warnings tab provides feedback about your service. These tabs are described later in this topic. First, here is a little more information about what you are seeing.

# Exploring the Test Form Tab

The Test Form tab provides a place for you to test a service with values. You can enter values for the parameters of your methods. For the Investigate service, there is one method with one parameter; as a result, the page provides a box into which you can enter a value for the taxID parameter. When you click the requestCreditReport button, WebLogic Workshop invokes the requestCreditReport method, passing the contents of the text box as a parameter to the method.

To Test the requestCreditReport Method

1. If it is not already selected, click the Test Form tab.

2. In the string taxID field, enter a value. This value can be any string value, but for the sake of the test it should be something that at least looks like a taxpayer ID, such as 123456789.

3. Click requestCreditReport.

The Test Form page refreshes to display a summary of your request parameters and your service's response, as shown here:

Under Service Request, the summary displays the essence of what was sent by the client (you) when the method was called. It shows the parameter values passed with the method call, as in the following example:

taxID = 123456789

Under Service Response, the summary displays what was returned by the Investigate service. The response is formatted as a fragment of Extensible Markup Language (XML), as communications with web services are formatted as XML messages. You can see that the method returned the correct result for the code you provided, as shown here:

    <string xmlns="http://www.openuri.org/">applicant: 123456789 is approved.</string>

To the left of the request and response is the Message Log area. This area lists a separate entry for each test call to the service method. Entries in the Message Log correspond to your service's methods, updating with a new entry for each test you make.

To try this out, click the Test operations link to return to the original Test Form page, then enter a new value in the string taxID box and click requestCreditReport. When the page refreshes, request and response data corresponding to your second test is displayed as a second entry in the Message Log. You can click each log entry to view the data for the corresponding test. Click Clear Log to empty the list of log entries and start fresh.

That's it for the test! With this simple test, you have pretty well exercised this service's abilities — so far.

But before you move on, take a look at the other information available from Test View. For example, the URL at the upper right corner of the page next to the Warnings tab should appear something like this:

http://localhost:7001/samples/financialservices/Investigate.jws

This is the URL used to call the web service. Each portion of the URL has a specific meaning. The following list explains each portion:

- http://locahost:7001/ — This means that your browser's request—that is, the call to the service—will be intercepted by WebLogic Server, which is listening on port 7001 of your local machine. In your case, the term "localhost" is probably replaced by the name of your computer.

- samples/financialservices/ — "samples" refers to the web application of which the service is a part. When you create a project in WebLogic Workshop, you are also creating a WebLogic Server "web application." The project name becomes part of the URL for all web services in that project. You will want to keep that in mind when naming new projects so that the resulting web service URLs are meaningful and appropriate.

- Investigate.jws — This is the name of the web service’s JWS file. WebLogic Server is configured to recognize the JWS extension and respond appropriately by serving the request as a web service rather than, for example, an HTML page or a Java servlet.

# Exploring the Overview Page

The Overview page deserves special attention because it provides access to all of the files you and your service's clients will need to use your web service. As you update your service's design and source code, you will be able to easily get current versions of these files. As a result, you may find the Overview page to be an invaluable resource as you begin testing and using it in a deployed application.

The following list describes some of the prominent features you will find on the Overview page:

Web Service Description Language files — Web Service Definition Language (WSDL) files describe your service's interface, giving potential clients what they need to know in order to use your service's functionality.

Web Service Clients — The following list provides brief descriptions of these links. They will be covered in more detail later in this tutorial.

- The Workshop Control link displays the contents of a CTRL file. A CTRL (or "control") file provides your service's interface in a format specific to WebLogic Workshop.

- The Java Proxy link downloads a JAR file containing code a Java client can use to call the Investigate service.

- The Proxy Support Jar link downloads a JAR file containing supporting classes for clients written in Java.

Service Description — A list of the methods and callbacks (if any) that are exposed by the web service. This is for verification purposes. If you don't see all of the methods you expected in this list, it indicated a problem with the source code for the web service. Here, you can see that the Investigate web service currently has only the requestCreditReport method and no callbacks.

Useful Links — A link to a topic on building client proxies, as well as links to the specifications behind the standards for the following languages:

- WSDL, a language (based on the rules of Extensible Markup Language, or XML) for describing a service's interface.

- Simple Object Access Protocol (SOAP), a protocol for formatting the XML-based messages that web services use to communicate.

- XML namespaces, a means to prevent conflicts among XML element and attribute names (but ensuring that names are unique within a given scope of use).

- URIs, strings used to identify a resource, including XML namespaces and schemas.

# Exploring the Console Page

The Console page provides information and commands related to the instance of WebLogic Server running on your computer. Through the settings and buttons on this page, you can control aspects of your local instance of WebLogic Server while you are testing your service.

# Exploring the Test XML Page

When your web service is deployed and receiving requests from clients, those requests will come in the form of XML messages carrying request-specific information. The Test XML page provides a place for you to test your service with something like the body of an XML message that might be sent to your service. You can try it out now by replacing the placeholder value with the Taxpayer ID you tested with earlier, then clicking requestCreditReport.

    <requestCreditReport xmlns="http://www.openuri.org/">
      <taxID>
        111111111
      </taxID>
    </requestCreditReport>

You have successfully added code to a web service’s method and tested the method for correct operation. In the next step, Step 2: Add Support for Asynchronous Communication, you will revise your service's design to solve a problem inherent in communications across the Internet — latency.

Related Topics

WebLogic Workshop Projects

Design View

Test View

Click one of the following arrows to navigate through the tutorial.