bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Tour of the WebLogic Platform Sample Application

Web Services Tour

The sample application includes two Web services that we created in WebLogic Workshop. If you took the tour through the business-to-consumer (B2C) sample portal for Avitek Digital Imaging — section 02 from the sample's Introduction page — you probably saw the results returned by the Web services. One performs the product rating look-up that is displayed in the site's Product Evaluator portlet. The other Web service performs the credit card payment authorization.

This portion of the WebLogic Platform sample takes you behind the scenes to learn how BEA WebLogic Workshop was used during the development cycle to create the Web services. In addition, we show you how the Portlet Wizard can be used to reference the product rating Web service's WSDL and generate code for a portlet.

Note: The information that is presented in this section is also available by clicking the "BEGIN Web Services Tech Tour" button on the sample application's Introduction page.

This Web services tour contains the following sections:

- Starting WebLogic Workshop

- Defining Web Services with WebLogic Workshop — An Overview

- Defining the Product Evaluator Web Service

- Defining the Payment Authorization Web Service

Starting WebLogic Workshop

The first step is to start the WebLogic Workshop visual development environment. This section explains how to do that on supported Microsoft Windows and UNIX platforms.

For supported platforms information, please refer to the Supported Platforms page on the BEA e-docs Web site.

To start WebLogic Workshop from the Microsoft Windows Start menu, choose:

Programs —> BEA WebLogic Platform 7.0 —> WebLogic Workshop —> WebLogic Workshop

To start WebLogic Workshop on UNIX, follow these steps:

1. Open a file system browser or shell.

2. Locate the Workshop.sh file in the BEA_HOME directory structure. For example:

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

3. CD to the directory and type the following command:

   >     sh Workshop.sh

4. Or, from a file system browser, double-click Workshop.sh.

About the Project Locations

For this tour, we are going to look at two Web services that were defined in WebLogic Workshop for the WebLogic Platform Sample Application. The project files that comprise these Web services were installed into the following locations under your BEA_HOME directory:

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eWebServicesApp\workshop\productEvalWSC

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eWebServicesApp\workshop\paymentWS

The easiest way to view and test these Web services is to copy these two folders, shown above in bold, to the following folder:

>     weblogic700\samples\workshop\applications\samples

After the copy operation, the folder hierarchy is as follows:

Then in WebLogic Workshop, use the Open Project menu option to navigate to the JWS file for each Web service. When you start WebLogic Workshop for the first time after installation, it prompts you to create a new project, or open a new one. We suggest that you:

1. Click File —> Open Project from the top-level menu.

2. Select the samples project, as shown in the following figure.

3. Click the Open button.

Because you copied the productEvalWSC and paymentWS folders into the WebLogic Workshop samples project's folder, you will see them in the project tree, as shown in the following figure.

Note: Each WebLogic Workshop project corresponds to a J2EE Web application, as evidenced by the WEB-INF folder in the samples folder.

For example, you can expand the productEvalWSC folder in the project tree and then double-click the EvalProduct.jws file. The WebLogic Workshop visual development environment displays a screen that is similar to the following:

Notice that a WebLogic Server instance is not running. See the next section for information about server startup options.

Server Startup Options

If you are interested in simply viewing the definitions of the Web services, you will not need to start a WebLogic Server instance in the WebLogic Workshop visual development environment. However, if you want to run and test the Web services as part of this tour, follow these steps. Although a server instance is already running for the e2eDomain, in this tour we will start a separate server instance to run and test the Web services located under:

>     weblogic700\samples\workshop\applications\samples

This assumes that you have already copied the paymentWS and productEvalWSC folders from the Platform samples area to the Workshop samples area, as described in the previous section, About the Project Locations.

To run and test the Web services, follow these steps:

1. From the WebLogic Workshop visual development environment's top-level menu, click Tools —> Preferences.

2. Click the Paths tab.

3. In the information about the server instance to be started, the default information should be correct. Confirm that the domain is "Workshop".

4. Check that the browser path is correct. If it is not correct, browse to the correct location for your browser's executable.

   The following screen shows sample values.

5. On the Preferences screen, click OK.

6. From the top-level menu, click Tools —> Start WebLogic Server.

When the server startup has completed, WebLogic Workshop displays a Server Running status near the bottom of the screen.

Note: You can test already deployed Web services that were created in WebLogic Workshop in a domain other than cgDomain. For example, the e2eDomain is installed with the paymentWS and productEvalWSC Web services deployed under:

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eWebServicesApp\workshop\*

With the server instance for the e2eDomain running, you could test these Web services, without having to open the WebLogic Workshop visual development environment, by pointing your browser to:

>     http://localhost:7501/workshop/productEvalWSC/EvalProduct.jws
>     http://localhost:7501/workshop/paymentWS/Payment.jws

Whether you invoke the test pages from within WebLogic Workshop or not, the product provides these very useful pages to test your Web services.

The next section presents an overview of WebLogic Workshop features and outlines the process for defining a Web service.

Defining Web Services with WebLogic Workshop — An Overview

Before we examine the Product Evaluator and Payment Web services that were created for the WebLogic Platform sample application, let's look at the basic steps for defining Web services in WebLogic Workshop. We will cover some introductory topics for this exciting new product, and also provide links to its online documentation for more details.

WebLogic Workshop is a new visual development environment that makes it easy for application developers and J2EE experts alike to build and deploy enterprise-class Web services. The product is comprised of two major components:

- A design-time tool that lets developers write Java code to implement Web services.

- A run-time framework that provides the Web services infrastructure, testing, debugging, and deployment environment for applications.

The WebLogic Workshop Visual Development Environment

The WebLogic Workshop visual development environment provides a complete environment for developing a Web service application. Standard features such as project management, syntax highlighting, code completion, and integrated debugging are all included. Also, WebLogic Workshop provides a useful visual approach to Web services. For example, the following shows a sample Design View screen.

The Payment Web service under development appears at the center of the screen. The design view lets users graphically create new methods, set properties on controls, and specify the overall structure of a Web service and its relationship to the outside world. The goal is to enable developers to focus on writing business logic — the code that is executed in response to each incoming method — not the machinery of typical Java programming. WebLogic Workshop supports two-way editing so any changes made through the graphical environment are reflected immediately in code, and vice versa.

The WebLogic Workshop Source View screen provides all the standard Java IDE editing features and exposes the Java Web Service (JWS) annotations. For example:

WebLogic Workshop Controls

WebLogic Workshop controls are a key innovation that ease the use of enterprise resources and J2EE APIs. WebLogic Workshop simplifies the complexity of these APIs and reduces the amount of object-oriented programming needed to access external resources. For example, WebLogic Workshop has a database control that simplifies the JDBC API. Database administrators can create a reusable database control that links SQL statements with Java methods in a simple declarative fashion. Developers can then use these components to access database resources with a simple function call.

For example, for the productEvalWSC Web service, we used WebLogic Workshop to define a database control named ProductEvalDBControl. One of the four methods in the database control is findRatingData:

>          /**
>           * @jws:sql statement="SELECT RELIABILITY_RATING,
>                 VALUE_RATING, OVERALL_RATING,
>                 COMMENTS FROM E2E_PRODUCT_EVAL
>                 WHERE SKU = {productId}"
>           */

>          public Evaluation findRatingData(String productId)
>                  throws SQLException, ControlException;

Notice how a special WebLogic Workshop Javadoc annotation associates an SQL statement with a Java method. Once a method is on a control this way, users of the control can simply call the function to execute the SQL command.

Java Web Service Files and Control Files

The meeting place between the design-time tool and the run-time framework is the Java Web Service (JWS) file and associated control (CTRL) files.

JWS files are standard Java files with annotations (using the Javadoc syntax) to express additional functionality. Annotations are used to display the Web service and its properties graphically. And the annotations are used by the framework to generate the EJB and J2EE code to execute the Web service. By moving code generation out of the tool and into the framework, developers never have to manage and maintain code that they didn't write.

Files with the extension CTRL are WebLogic Workshop controls. They typically include a collection of method definitions that allow you to easily access a resource such as a database or another Web service. CTRL files can represent the following types of controls:

- Service Control: used to communicate with another Web service from your service.

- Database Control: used to access a database from your Web service.

- EJB Control: used to access an existing Enterprise Java Bean (EJB) from your Web service.

- JMS Control: used to access an existing Java Message Service (JMS) queue or topic from your Web service.

The WebLogic Workshop Framework

Once a JWS file containing all the business logic for a Web service has been created, the WebLogic Workshop framework is responsible for generating the standard EJB code needed to implement it. The framework exposes, through annotations, functionality specifically designed to support building enterprise-class Web services. The WebLogic Workshop framework does the following:

- Managing asynchronous communication with a conversational metaphor

The WebLogic Workshop framework automatically manages asynchronous message correlation and state management across messages in a conversation. What does that mean? Users can simply mark methods as starting, finishing, or continuing a conversation, and the framework takes care of the details. A unique ID is automatically generated to identify the conversation, and any state (class member variables) defined in the Web service is managed persistently with entity Java beans.

- Enabling loose coupling with XML maps and XML scripts

The WebLogic Workshop framework uses simple, declarative XML maps to map between internal Java code and XML messages that are exchanged between Web services. Users indicate the structure of the desired method and associate XML fields with Java variables.

- Enabling availability with JMS queues

To ensure availability under high load, Web services take advantage of message buffers. Users mark a method as requiring a buffer, and the WebLogic Workshop framework handles creating a queue and wiring it to the Web service. This feature enables one-click access to sophisticated J2EE functionality.

- Supporting the control architecture

The WebLogic Workshop framework instantiates the implementation of any control used by the JWS. The framework also hooks up any asynchronous callbacks using a simple naming convention.

Outline of the Web Service Development Process

This section of the tour outlines the basic steps to building a Web service. You can find more information about each of these steps in the WebLogic Workshop online documentation. A good starting point is the tutorial. It is available within the visual development environment by clicking from the top-level menu: Help —> Tutorial. Or you can read the tutorial by starting on the BEA e-docs Web site's pages for WebLogic Workshop. Look for the topic titled: "Tutorial: Your First Web Service."

1. Start WebLogic Workshop and begin defining the methods, events, controls... then test what you have created so far.

   - Start WebLogic Workshop.

   - For your first Web server, open the Samples project that comes with WebLogic Workshop.

   - In this project, create a subdirectory for the Web service. In the dialog box window, indicate that you are creating a Web service, and name it.

   - Start a WebLogic Server instance.

   - In the graphical Design View, add one or more methods and events for your Web service. 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.

   - Select the Source View tab to see the results of your work done in Design View. You can add business logic. If you add a member variable to source code in Source View, your new variable will appear in Design View, and vice versa.

   - In Design View, add one or more parameters and return values for methods. Add code for returning a value.

   - Build, test, and deploy your Web service. Use the WebLogic Workshop Test View, a browser-based tool through which you can call the Web service's methods. (Sample screens are shown in the modules for the paymentWS and productEvalWSC Web services in this tour.)

2. Add support for asynchronous communication, if needed by the application.

   In asynchronous communication, the client communicates with the Web service in such a way that it is not forced to halt its processes while the Web service produces a response. You also add a callback to be informed, for example, when a stock price reaches a particular value.

3. Add a database control.

   In this step you add a database control to your Web service. The database control provides your Web service access to a database. Controls act as interfaces between your Web service and other data resources, such as databases, other Web services, Java Message Services, and so on.

4. Add a service control, if needed by the application.

   You can add a service control to your Web service that enables it to invoke another external Web service.

5. Add other controls, such as JMS and EJB controls, as needed.

   You can access components that are available via the Java Message Service (JMS) using the JMSControl. Through this control, you can send and receive messages of various types, including XML. You also can access Enterprise Java Beans (EJBs) through the EJBControl. The EJBControl simplifies your use of an EJB by providing a single component representing the EJB's interface in your Web service design.

6. Add a script file for mapping, as needed.

   When you need to handle or control the specific shape of XML messages your Web service exchanges with other components, you can use XML maps. XML maps customize the WebLogic Server translation of XML to Java, and vice versa.

7. Add Support for Cancellation and Exception Handling.

   With the TimerControl, you can add timer functionality to your Web service. In this way, you can limit the time-specific operations that are allowed to execute, or force something to happen at regular intervals. You also can use the onException callback to handle exceptions thrown from your Web service's operations. When prompted by this callback, your code can perform any necessary clean-up and send a message to the client.

8. Modify the Web Service to Support a Polling Interface, if needed.

   As you build your Web service, WebLogic Workshop generates classes that can be used by client software. Through these proxy classes, a client can invoke your service's methods. You can download the proxy classes from Test View.

9. Configure security settings and deploy the Web services as part of a Webapp.

   You can make your Web service more secure by ensuring that it is exposed via the HTTPS protocol rather than HTTP. To do this, you edit the configuration file associated with your Web service's project. Using the JwsCompile command, you can then package your Web service for deployment to a production server.

This covers the basic steps. The next section will discuss the productEvalWSC Web service that we created in WebLogic Workshop for the WebLogic Platform sample application.

Defining the Product Evaluator Web Service

In the business-to-consumer (B2C) portal Web site for the fictitious company, Avitek Digital Imaging, we provided a Product Evaluator portlet for users who are browsing the product catalog:

This portlet used a Web service that we created in WebLogic Workshop to return product rating information about the selected catalog item. This section of the tour describes that Web service, productEvalWSC. This section also describes the steps taken in the Portlet Wizard to create the Product Evaluator portlet.

Viewing the Existing productEvalWSC Web Service

In the WebLogic Workshop project tree window, double-click on the productEvalWSC folder that you copied to:

>     weblogic700\samples\workshop\applications\samples\productEvalWSC

If you skipped this step in a prior tour page, see the section About the Project Locations. Then return to this page.

In the expanded project folder for productEvalWSC, double-click on the Java Web Service file named EvalProduct.jws. The following screen shows the Design View display for this Web service.

We used WebLogic Workshop to define the ProductEvalDBControl and its methods:

- createProductEvalTable

- dropProductEvalTable

- findRatingData

- insertEvaluationRecord

We then used WebLogic Workshop to define the following methods for the JWS:

- getEvaluation

- getComments

- getOverallRating

- getReliabilityRating

- getValueRating

- endEvaluation

In the Design View display, notice the small (s), (c), and (f) notations for the JWS methods. These notations indicate which method starts the Web service's conversation (getEvaluation), which method(s) continue the conversation (getComments through getValueRating), and which method finishes the conversation (endEvaluation).

Note: For a production Web service, we would not make separate calls to return the product evaluation's comments, overall rating, reliability rating, and value rating. Instead, we would create a complex object in the Web service and get all the ratings in a single call. Using a complex object and avoiding the separate calls should provide better performance.

Defining a database control and its methods in the WebLogic Workshop visual development environment is easy. This tour does not show the steps taken to create the control and methods. These steps are documented in the WebLogic Workshop documentation, which is available from within the visual development environment, or on the BEA e-docs Web site's pages for WebLogic Workshop.

However, here is a brief explanation about the purpose of the ProductEvalDBControl database control and its methods. During development, before the application's database schema is finalized for the enterprise application being placed into production, it is helpful to define database control methods that create or drop (as needed) the metadata, for testing purposes. As a convenience to our development process, we started by defining the createProductEvaluatorTable and dropProductEvaluatorTable methods. In WebLogic Workshop, you can double-click on the arrow for each method to see the SQL statements that we provided. For example, createProductEvaluatorTable defines:

We then defined the insertEvaluationRecord and findRatingData methods (please see the SQL statements in the WebLogic Workshop visual development environment).

With those database control methods available, we defined the JWS methods that use the database control methods. For example, the getEvaluation method starts the Web service conversation and uses the findRatingData method from the database control. In WebLogic Workshop, you can view the code for the JWS by either selecting the Source View tab, or by clicking the getEvaluation method's underlined link, which brings up the Source View near the line that starts the selected method. For example:

>     * @jws:operation
>     * @jws:conversation phase="start"
>     */

>     public String getEvaluation(String productId)
>     {
>        try
>        {
>          evaluation = productEvalDB.findRatingData(productId);
>             }
>             catch (java.sql.SQLException e)
>             {
>                 // will be interpreted as productId not found
>             }
>             if( evaluation != null )
>             {
>                 return "SUCCESS";
>             }
>             else

>          {
>                 return("NOT FOUND");
>          }
>      }

You can read the code in WebLogic Workshop for the methods that we defined for EvalProduct.jws, the JWS for productEvalWSC. If you need more information about defining methods in the visual development environment, please see the WebLogic Workshop documentation. It is available from within the visual development environment, or on the BEA e-docs Web site's pages for WebLogic Workshop.

Building and Testing the productEvalWSC Web Service

If the WebLogic Server instance for the cgDomain is not already running, start it. If you skipped this step in a prior tour page, see the section Server Startup Options. Then return to this section.

When the server is running, you will notice the following status icon near the bottom of the WebLogic Workshop visual development environment:

With the server running, click Debug —> Build. When the build completes for this already defined Web service, WebLogic Workshop will have placed compiled JWS classes in the following location:

>     weblogic700\samples\workshop\cgServer\.jwscompile\_jwsdir_samples
>      \classes\productEvalWSC\*.class

With the server running, click Debug —> Start

The test pages are browser-based. The initial tabbed page is the Test Form. For now, select the Overview tab. The following screen shows the Overview page with the server running on a remote machine named blues.

Select the Test Form tab. You can test the productEvalWSC Web service by entering sample data. Because you are testing the Web service in the cgDomain (the default server used with WebLogic Workshop), you must first run the CreateProductEvaluatorTable method on the following initial Test Form page, before trying the getEvaluation method. (We use the CreateProductEvaluatorTable method to conveniently create the database table and populate it, for testing purposes only while using the visual development environment. In production, the Web service will use a production database.)

The Web service method should return a Created message. For example:

Next, click the Start operations link on the Test Form. On the refreshed page, start the test of the Web service's getEvaluation method. For example, enter pix1000 in the productId field, as shown below. Then click the getEvaluation button.

The Web service conversation is invoked, and the WebLogic Workshop run-time engine returns a SUCCESS status, as shown in the following screen.

To continue the test, click the Continue this conversation link on the page. WebLogic Workshop returns a list of subsequent methods defined for the productEvalWSC Web service as shown in the following screen.

Click one of the methods to see the Web service return a product rating for this pix1000 camera. For example, when we clicked the getReliabilityRating method test, WebLogic Workshop returned:

Notice the Web service response is the integer 2. On the Product Evaluator portlet, this results in displaying two out of five possible stars. For example:

On the Test Form, you can try other methods in the conversation. As noted earlier, for a production Web service we would not make separate calls to return the product evaluation's comments, overall rating, reliability rating, and value rating. Instead, we would create a complex object in the Web service and get all the ratings in a single call.

After we used WebLogic Workshop to create and test a Java Web Service (JWS) file for productEvalWSC, we used the Portlet Wizard to generate a draft version of the portlet (minus final presentation coding, graphics, Webflow, and packaging changes). The Portlet Wizard tool is part of the E-Business Control Center, a graphical tool provided by WebLogic Portal. Portlet Wizard was used to generate the Web services interfaces code for the portlet. We also used WebLogic Server to generate the client proxy.

Note that when you first accessed the Web service, WebLogic Workshop automatically generated for you all the EJBs, with no action or work required by the developer. In our example, the first access resulted in the productEvalWSC.EvalProductEJB.jar file creation in:

>     weblogic700\samples\workshop\cgServer\.jwscompile\_jwsdir_samples\EJB

The Web service class files were created in:

>     weblogic700\samples\workshop\cgServer\.jwscompile\_jwsdir_samples\classes\productEvalWSC\*.class

Save the Web Service's WSDL

At any time in the development process, the Web Service Description Language (WSDL) file describing your Web service is available from WebLogic Server. WSDL is a standard XML document type controlled by the World Wide Web Consortium (W3C, see http://www.w3.org for more information).

WSDL files describe all the methods a Web service exposes (in the form of XML messages it can accept and send), as well as the protocols over which the Web service is available. The WSDL file provides all the information a client application needs to use the Web service.

There are several ways to obtain the WSDL file corresponding to a JWS file:

- In the visual development environment's Project tree, browse to the JWS file for which you would like to generate a WSDL file. In our example, browse to EvalProduct.jws. Right-click on the JWS file in the Project tree and select Generate WSDL from JWS. A file with the name EvalProductContract.wsdl will be created in the same directory. By default, the WSDL file is linked to the JWS file from which it was generated, meaning it will be regenerated whenever the JWS file is changed. For this reason, this is the recommended method of generating the WSDL.

- In a browser, browse to the URL of the Web service with ?WSDL appended. For example, if the Web service is running on the default server on a machine named blues:

>     http://blues:7001/samples/productEvalWSC/EvalProduct.jws?WSDL

Use your browser's File —> Save As function to save the WSDL file to your local machine. Note that some browsers will include HTML tags at the top and bottom of the saved file. You must remove these tags to produce a valid WSDL file. Be sure to designate the .wsdl file type; we recommend that you follow the naming convention of <WebServiceName>Contract.wsdl. For example, name it EvalProductContract.wsdl.

- In the WebLogic Workshop visual development environment, you can view the WSDL by clicking the Complete WSDL link on the Overview page while testing your Web service. You can then use the browser's Save As function to write the Web service's file into the same directory as the JWS file. (Again, follow the naming convention shown above, and remember that some browsers will include HTML tags that you must remove from the top and bottom of the saved file.)

Use Portlet Wizard to Generate Initial Code for the Product Evaluator Portlet

The E-Business Control Center (EBCC) is a Java client-based tool suite. It provides graphical interfaces that simplify complex tasks such as rule definitions, Webflow editing, and portal creation and management. As users of the E-Business Control Center work with its point-and-click interface, it generates XML files that are synchronized with the server.

One of the features in the EBCC is the Portlet Wizard. You can use it to reference WSDL for a Web service, and generate the code needed by a portlet. The following list outlines the general steps in the Portlet Wizard. When you work with the Portlet Wizard, be careful that you do not overwrite the existing evaluator portlet's files.

Note: The packaging and the variables used in the installed evaluator.jsp portlet are different from the content.jsp file created by Portlet Wizard in the following steps. The purpose of this section is to explain what could be created initially by Portlet Wizard.

To start the EBCC, for example on a Windows system, click the following in the Start menu:

1. Programs —> BEA WebLogic Platform 7.0 —> WebLOgic Portal 7.0 —> E-Business Control Center.

2. From the EBCC top-level menu, click File —> Open Project. Navigate to the following folder under your BEA_HOME:

   >     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp-project

3. Select the e2eApp-project.eaprj file in that folder, and click the Open button.

4. Then from the EBCC top-level menu, click File —> New —> Presentation —> Portlet.

5. On the initial New Portlet screen, with the following option set, click the OK button:

6. On the Portlet Name screen, give a unique name to the portlet, such as evaluatortest. In the Portal pull-down menu, select b2cPortal. Then click the Next button.

7. On the Portlet Pages screen, select the Products page from the list of available pages in the b2cPortal. Then click the Next button.

8. On the Portlet Components screen, select any components you want in your portlet, or leave these options unchecked. Then click the Next button.

9. On the Content Types screen, select the Web service(s) option. Then click the Next button.

10. On the Server Location screen, indicate where WebLogic Server is installed. Then click the Next button.

11. On the Generated Code Types screen, select Web services(s) Interfaces from the Output Options pull-down menu. The Product Evaluator portlet is conversational and requires the Web services(s) Interfaces options. The Form and Call Generation options are intended for simpler portlets. After making your selection, click the Next button.

12. On the Web Service(s) screen, if you are using Portlet Wizard for the first time and there are no Web services in the current list, click the Add Web Services... button. If Web services are listed, but not the EvalProduct one created by WebLogic Workshop, click the Edit List button. Portlet Wizard displays the Web services(s) List screen. Enter the WSDL URL, such as:

    >     http://localhost:7501/workshop/productEvalWSC/EvalProduct.jws?WSDL

    Note that the URL is case sensitive. In the following example, we used the WSDL URL for the e2eDomain application (note: localhost:7501). After entering the WSDL URL in the input box, click the Add URL button. Portlet Wizard checks the URL and, if valid, adds it to the Web service(s) list. Then click the Close button on the Web service(s) List screen.

    Back on the Web Service(s) screen, click the EvalProduct Web service in the list. Portlet Wizard connects with the WSDL URL and retrieves the operations we defined for the self-describing Web service. A progress screen is displayed during this step. After you see the Operations retrieved status message on the screen, click the Next button.

13. The Code Preview screen shows you what the Portlet Wizard will generate. You can, optionally, edit the code in the Portlet Wizard (which includes your changes, but does not validate them), or copy it to the clipboard for later pasting into your favorite editor. In either event, after previewing the Web service interfaces code that will be created for you, click the Next button.

14. On the Resource Files Location screen, Portlet Wizard indicates that it will create a directory using the name of your portlet under the portlets directory of the associated Web application, as shown in the following example.

    After indicating the location for the portlet JSP file that will be created, click the Next button.

15. On the Summary screen, Portlet Wizard lists the files that will be created or modified, as shown in the following screen.

    In this example, the following files will be created under weblogic700\samples\platform\e2eDomain\beaApps:

    - \e2eApp-project\application-sync\evaluatortest.portlet

    - \e2eApp\b2cPortal\portlets\evaluatortest\content.jsp

    - \e2eApp\b2cPortal\portlets\evaluatortest\evaluatortest_include.jsp

    - \e2eApp\b2cPortal\portlets\evaluatortest\images\pt_image.gif

    - \e2eApp\b2cPortal\WEB-INF\lib\sdl_wsdl_evalproduct.jar

    In addition, Portlet Wizard will update the following XML file that lists the available portlets (but not yet enabled on a Products page) for the b2cPortal Web application:

    - \e2eApp-project\application-sync\webapps\b2cPortal\b2cPortal.portal

    If you want to proceed, click the Create button. Or click the Cancel button if you simply wanted to see the process in the Portlet Wizard.

    Behind the scenes, Portlet Wizard executes the following build command to generate the Web service interfaces for you:

    >     weblogic700\server\bin\ant.bat -f buildfile client-gen.xml

    This command creates a JAR file containing .class, .WSDL, and other files that comprise the Web service's interfaces that can be used by the portlet. Also included in the JAR are the .java source files.

On the final Next Steps screen, you can uncheck the edit options and click the Close button if you are satisfied with the settings for the initial portlet. Note that you would need to make important enhancements to the portlet's JSP code and associated files before using the EBCC to synchronize the project (placing the portal definitions on the server) and before making the draft portlet visible and available on the Product page. The next section highlights the packaging differences. For information about EBCC server synchronization and making portlets available and visible to a portal page, see the WebLogic Portal Administration Guide.

Next Step

Now that you understand the general process of using the Portlet Wizard screens to generate the initial portlet's JSP and the interfaces (including .class, .wsdl, .java files in a JAR), we should note again: the packaging and the variables used in the installed Product Evaluator portlet and the EvalProd Web service are different from what you may have just created using Portlet Wizard. When we created the JAR file, we extracted the Java sources, significantly modified the portlet JSP (and added two include JSP files), and deployed the resulting files as follows. Note: the Java sources did not require any modifications; we extracted them simply to provide them with the installed sample directories.

Product Evaluator Portlet JSP files

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp\b2cPortal \portlets\evaluator\*.jsp

In the main evaluator.jsp portlet file and the included step1.jsp and step2.jsp files, we enhanced the presentation graphics that comprised the portlet, and added scriptlets to work with the Webflow for the portlet and the b2cPortal.

Web service client interfaces, CLASS files, used by WebLogic Workshop runtime

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp\b2cPortal\WEB-INF\classes\productEvalWSC\*.class

Web service client interfaces, JAVA files

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp\b2cPortal\WEB-INF\src\productEvalWSC\*.java

Server-side implementation

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eWebServicesApp\workshop\productEvalWSC\*

These files include the deployed EvalProduct.jws and ProductEvalDBControl.ctrl copied from the WebLogic Workshop area and deployed as part of the workshop Web application, which was deployed as part of the e2eWebServicesApp enterprise application. Of course, the workshop Web application has a WEB-INF subdirectory that contains the configuration settings in *.xml files.

SOAP Conversation, JAVA files, generated by the client-gen task

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp\b2cPortal\WEB-INF\src\org\openuri\www\x2002\x04\soap\conversation

For information about the Payment Web service that is used in the b2cPortal, refer to the next section.

Defining the Payment Authorization Web Service

The B2C portal for Avitek Digital Imaging includes an Order Submission page as part of the checkout process.

When the user clicks the Submit Order button, the credit card payment authorization processing is handled by a pipeline component named CajunBasedPaymentPC, which calls a Java proxy that lets the pipeline component call the Payment Web service. We created the Web service in WebLogic Workshop.

The Payment Web service uses the conversational aspect of WebLogic Workshop framework. The first call is to authorize the credit card; we pass in the credit card number and the amount to be authorized as arguments. After the credit card authorization is complete, a call is made to capture an amount. Eventually a request is made to settle the amount.

The codes returned by the Payment Web service to the CajunBasedPaymentPC are as follows:

- -1 = Error (Bad argument passed)

- -2 = Error (When amount to capture is more than the amount the credit is authorized for)

- -3 = Error (When amount to settle is more than the amount for which the credit card was captured for)

- > 0 = Success

Note: The Payment Web service always sends payment information through without any errors, as if it were connected to and approved by a third-party payment service. The processing of payment via the Payment is not designed for production use. You must integrate with your third-party vendor's payment service to process payment correctly. Note, however, that the code shown in the sample pipeline component is set up to appropriately handle error conditions.

The Role of the CajunBasedPaymentPC Pipeline Component

Before we look at the definition of the Payment Web service in WebLogic Workshop, let's examine portions of the CajunBasedPaymentPC.java pipeline component. You can find the source file in the following directory under your BEA_HOME:

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp\src\examples\e2e\b2c\payment\pipeline

The sample pipeline component contains many import statements, including:

>     import paymentWS.Payment_Impl;
>     import paymentWS.PaymentSoap;
>     import examples.e2e.b2c.util.B2CPortalConstants;

>     import com.bea.p13n.util.debug.Debug;
>     import org.openuri.www.*;
>     import org.openuri.www.x2002.x04.soap.conversation.*;

>     import com.beasys.commerce.axiom.units.Money;
>     import com.beasys.commerce.ebusiness.shoppingcart.ShoppingCart;

These statements import packages for the Payment proxy, the generated SOAP interfaces, and a set of sample constant values (such as the payment type) to simplify the application. Also imported is a ShoppingCart EJB that processes shopping cart data for commerce applications.

Part of the CajunBasedPaymentPC pipeline component's work in the b2cPortal application is to get the current shopping cart data from the pipeline session.

>     CreditCard cc = (CreditCard) getSessionAttribute(PipelineSessionConstants.PAYMENT_CREDIT_CARD, namespace, pipelineSession);

>     ShoppingCart sc = (ShoppingCart) getSessionAttribute(PipelineSessionConstants.SHOPPING_CART, namespace, pipelineSession);

>     Money amt = (Money) sc.getTotal();

We instantiate the proxy for the Web service:

>     try {
>            proxy = new Payment_Impl(connectString +
>               "/workshop/paymentWS/Payment.jws?WSDL");
>            if (DEBUG.ON) {
>                DEBUG.out("proxy instantiated");
>            }

After setting up header objects in preparation for the conversation with the Web service, we start the conversation by first getting the credit card number and value (amount of the purchase) from the pipeline session. Then we pass authorize data to the Payment Web service, which returns a result. This entry point simply reserves credit on the supplied card for the amount specified.

>     Authorize auth = new Authorize(cc.getNumber(), amt.getValue());
>     long result = proxySoap.authorize(auth, startHeader).getAuthorizeResult() ;

If no errors are returned in the authorization method, we continue with capture data. In payment transactions, the word "capture" refers to the amount of the credit card holder's remaining available credit. The total amount to settle must be less than the capture amount.

>     Capture capture = new Capture(amt.getValue());
>     result = proxySoap.capture(capture, continueHeader).getCaptureResult();

After getting the capture result from the Web service, we finish the conversation with the settlement data.

>     Settle settle = new Settle(amt.getValue());
>     result = proxySoap.settle(settle, continueHeader).getSettleResult();

See the CajunBasedPaymentPC.java source file for a closer look at the error handling. Again, the file is provided in:

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp\src
>      \examples\e2e\b2c\payment\pipeline

Viewing the Existing paymentWS Web Service

In the WebLogic Workshop project tree window, double-click on the paymentWS folder that you copied to:

>     weblogic700\samples\workshop\applications\samples\paymentWS

If you skipped this step in a prior tour page, see the section titled "About the Project Locations." Then return to this section.

In the expanded project folder for paymentWS, double-click on Java Web Service file named Payment.jws. The following screen shows the Design View display for this Web service:

We used the WebLogic Workshop to define the following methods for the Web service:

- Authorize

- AuthorizeAndCapture

- Capture

- Settle

In the Design View display, notice the small (s), (c), and (f) notations for the JWS methods. These notations indicate which methods can start the Web service's conversation (Authorize or AuthorizeAndCapture), which method(s) continue the conversation (Capture), and which method finishes the conversation (Settle).

If successful, the Web service methods return a unique transactionID, calculated in this sample as the time that the transaction occurred, in milliseconds. Returning an ID this way is typical for credit card authorization applications.

Defining methods in the WebLogic Workshop is simple. This tour does not show the steps taken to create the control and methods. These steps are documented in the WebLogic Workshop documentation, which is available from within the visual development environment, or on the BEA e-docs Web site's pages for WebLogic Workshop.

In the workshop, you can switch to Source View to see the definitions for the Web service's methods. After we added these four methods, and of course before we added the business logic you see in the visual development environment, we added member variables that we would need in the Web service. To do this, we right-clicked the Payment heading in the visual development environment and selected Add Member Variable from the pull-down menu:

The members variables defined for the Payment.jws are as follows. The underscore suffix is used to indicate instance variables.

- openToBuy_

- amountToCapture_

- transactionID_

- ERR_CODE_BAD_ARGUMENT

- ERR_CODE_AMT_TO_CAPTURE_MORE_THAN_AUTH

- ERR_CODE_AMT_TO_SETTLE_MORE_THAN_CAPTURE

Payment Models and the Methods Defined

In credit card transactions, there are two types of payment models: terminal-based and host-based. The difference between these payment models is where the transaction batch is stored. For a host-based model, the transaction batch is stored on the host network rather than on the local system at the merchant's site. Settlement typically occurs sometime at the end of the day, and the merchant is not required to do anything to initiate the settlement process.

For a terminal-based model, the transaction batch is stored as data files on the local system at the merchant's site. Merchants must initiate the settlement process at the end of each day in order for the funds to be transferred to the merchant's bank account.

The following list describes each of the terminal-based payment models that may be assigned by the financial institution.

- AUTO_MARK_AUTO_SETTLE

This payment model is used for soft goods. Settlement occurs as soon as authorization is complete, because it is assumed that soft goods are shipped at the time of purchase.

- AUTO_MARK_MANUAL_SETTLE

This payment model is used in cases where goods have been shipped at authorization but the merchant requests that funds should be transferred at a later date.

- MANUAL_MARK_AUTO_SETTLE

This payment model allows merchants to indicate that the goods have been shipped, at which point settlement is done automatically.

- MANUAL_MARK_MANUAL_SETTLE

This is the most flexible payment model in that it allows merchants to specify when goods are shipped and when funds should be transferred. The mark process allows the merchant to specify that the goods have been shipped. The settlement process allows the merchant to indicate that funds may be transferred.

This next list describes each of the host-based payment models that may be assigned:

- HOST_AUTH_CAPTURE

This payment model is used for services, sale of digital goods, or physical goods shipped within 24 hours of when the order is placed. In this case, the merchant only needs to get an authorization for the purchase amount. The capture of the authorization into the batch and the settlement of the transaction are done for the merchant by the processor at the time of authorization.

- HOST_POST_AUTH_CAPTURE

When the merchant fulfills orders more than one day after receiving them, the merchant must authorize and capture transactions separately. In this payment model, authorization is performed at the time the consumer wants to make the purchase. Capture is performed when the merchant ships the order. The processor handles settlement of the batched transactions at certain times of the day.

Again, the Authorize method is used for terminal-based payment models. This entry point validates the credit card number and reserves credit on the supplied card for the amount specified. When validated, it creates a new entry in a database table that records the incident and sets the state based on the payment model. The amount of the transaction is deducted from the openToBuy field in the customer's credit balance. However, the funds are not transferred to the merchant until settling.

Note: Merchants who are using a terminal-based processor must perform a capture and settlement procedure before the funds from the sale are transferred to their account. This is accomplished by a subsequent call to Capture and/or Settle, depending on the "Auto Mark/Auto Settle" processor configuration.

The AuthorizeAndCapture method is used for host-based payment models. This entry point validates the credit card number and reserves credit on the supplied card for the amount specified. When validated, it creates a new entry in a database table that records the incident and sets the state based on the payment model. The amount of the transaction is deducted from the openToBuy field in the customer's credit balance. However, the funds are not transferred to the merchant until settling.

Note: Merchants who are using a host-based post-authorization capture processor must perform a capture and settlement procedure before the funds from the sale are transferred to their account.

The Capture method in the Payment Web service determines the amount of the credit card holder's remaining available credit. The total amount to settle must be less than the capture amount, as checked in the Settle method:

>     * @jws:operation
>     * @jws:conversation phase="finish"
>     */

>     public long Settle(Double amountToSettle)
>     {

>     if ((amountToSettle == null) ||
>     (amountToSettle.compareTo(new Double(0)) < 0))
>     return ERR_CODE_BAD_ARGUMENT;

>     if (amountToSettle.compareTo(amountToCapture_) > 0)
>     return ERR_CODE_AMT_TO_SETTLE_MORE_THAN_CAPTURE;

>     return transactionID_;

>     }

If you need more information about defining methods in the visual development environment, please see the WebLogic Workshop documentation. It is available from within the visual development environment, or on the BEA e-docs Web site's pages for WebLogic Workshop.

Building and Testing the Payment Web Service

If the WebLogic Server instance for the cgDomain is not already running, start it. If you skipped this step in a prior tour page, see the section Server Startup Options. Then return to this section.

With the server running, click Debug —> Build. Notice the Build Started message in the lower left corner of the visual development environment's screen. When the build completes for this already defined Web service, WebLogic Workshop will have placed compiled JWS classes in the following location:

>     weblogic700\samples\workshop\cgServer
>      \.jwscompile\_jwsdir_samples\classes\paymentWS\*.class

With the server running, click Debug —> Start

The test pages are browser-based. The initial tabbed page is the Test Form. For now, select the Overview tab. The following screen shows the Overview page with the server running on a remote machine named blues.

Select the Test Form tab. You can test the Payment Web service by entering sample data. For example, you can enter any set of numbers for the credit card, such as 0099-8877-6655-4433 (with or without hyphens) and an openToBuy authorization amount such as 10000. For this test, we used the Authorize method:

To start the conversation, click the Authorize button. This Web service method, if successful, returns a unique transactionID, computed as the time the transaction occurred in milliseconds, as shown in this example.

To continue the test, click the Continue this conversation link on the page. WebLogic Workshop returns a list of subsequent methods defined for the Payment Web service. In the amountToCapture variable for the Capture method, enter 1000. Then click the Capture button. If the amount to capture is less than the authorize amount (success), the Web service returns a unique transactionID:

Next, click the Continue this conversation link again. In the amountToSettle variable for the Settle method, enter a value such as 999.95. Then click the Settle button. If the amount to settle is less than the capture amount (success), the Web service returns a unique transactionID:

On the Test Form, you can try other values in the conversation to confirm the error handling.

Note that when you built the Web service in WebLogic Workshop, it automatically generated for you all the EJBs, with no action or work required by the developer. In our example, the first access resulted in the paymentWS.PaymentEJB.jar file creation in:

>     weblogic700\samples\workshop\cgServer
>      \.jwscompile\_jwsdir_samples\EJB

The Web service class file was created in:

>     weblogic700\samples\workshop\cgServer
>      \.jwscompile\_jwsdir_samples\classes\paymentWS\Payment.class

Save the Web Service's WSDL

At any time in the development process, the Web Service Description Language (WSDL) file describing your Web service is available from WebLogic Server. WSDL is a standard XML document type controlled by the World Wide Web Consortium (W3C, see http://www.w3.org for more information).

WSDL files describe all the methods a Web service exposes (in the form of XML messages it can accept and send), as well as the protocols over which the Web service is available. The WSDL file provides all the information a client application needs to use the web service.

There are several ways to obtain the WSDL file corresponding to a JWS file:

- In the WebLogic Workshop's Project tree, browse to the JWS file for which you would like to generate a WSDL file. In our example, browse to Payment.jws. Right-click on the JWS file in the Project tree and select Generate WSDL from JWS. A file with the name PaymentContract.wsdl will be created in the same directory. By default, the WSDL file is linked to the JWS file from which it was generated, meaning it will be regenerated whenever the JWS file is changed. For this reason, this is the recommended method of generating the WSDL.

- In a browser, browse to the URL of the Web service with ?WSDL appended. For example, if the Web service is running on the default server on a machine named blues:

>     http://blues:7001/samples/paymentWS/Payment.jws?WSDL

Use your browser's File —> Save As function to save the WSDL file to your local machine. Note that some browsers will include HTML tags at the top and bottom of the saved file. You must remove these tags to produce a valid WSDL file. Be sure to designate the .wsdl file type; we recommend that you follow the naming convention of <WebServiceName>Contract.wsdl. For example, name it PaymentContract.wsdl.

- In the WebLogic Workshop, you can view the WSDL by clicking the Complete WSDL link on the Overview page while testing your Web service. You can then use the browser's Save As function to write the Web service's file into the same directory as the JWS file. (Again, follow the naming convention shown above, and remember that some browsers will include HTML tags that you must remove from the top and bottom of the saved file.)

Packaging of PaymentWS Web Service for Use in e2eDomain

We packaged the files that comprise the Payment Web service for the installed e2eDomain as follows:

Web service client interfaces, CLASS files, used by WebLogic Workshop runtime

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp
>      \b2cPortal\WEB-INF\classes\paymentWS\*.class

Web service client interfaces, JAVA files

>     weblogic700\samples\platform\e2eDomain\beaApps\e2eApp
>      \src\paymentWS\*.java

Server-side implementation

>     weblogic700\samples\platform\e2eDomain\beaApps
>      \e2eWebServicesApp\workshop\paymentWS\Payment.jws

This is the Payment.jws file copied from the WebLogic Workshop area and deployed as part of the workshop Web application, which was deployed as part of the e2eWebServicesApp enterprise application. Of course, the workshop Web application has a WEB-INF subdirectory that contains the configuration settings in *.xml files.

JAR file of the EJBs used by the paymentWS Web service

>     weblogic700\samples\platform\e2eDomain\e2eServer
>      \.jwscompile\_jwsdir_workshop\EJB\paymentWS.PaymentEJB.jar

Webflow Input Processors, CLASS files, for Payment processing

>     weblogic700\samples\platform\e2eDomain\beaApps
>      \e2eApp\b2cPortal\WEB-INF\classes\examples\e2e
>      \b2c\payment\webflow\*IP.class

Final Step for the Web Services Tour

This concludes the Web Services Tour. In the online tour, please click the Back to Introduction button to return to the sample's Introduction page.