Developing Web Services with Borland JBuilder Enterprise and BEA WebLogic Server

Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

At the present, most of the corporate world is either entertaining an idea of Web service infrastructure or is actively developing it. Honestly, it is not that difficult to leverage previously written business logic and expose it as a Web service. Web service standards have gained a lot of momentum in the past years and now have come to the point where they are reliable and robust; even different development toolkits will produce standardized results across different platforms.

There are several advantages to adding a Web service infrastructure to any business process. First, an existing source code (PC or mainframe based) and all the investment that went into its development will not vanish, but in fact will continue to serve its purpose from behind a new Web interface. Second, new business transactions will be easy to conduct over the Web and they will interact with any new or legacy system that is also exposed as a standard Web service. Third, business transactions become meaningful, thanks in part to the SOAP and XML standards. Fourth, if a Web service is well designed, process control should become minimized. Fifth, the session is done over HTTP connection and therefore potentially may not be limited by firewalls. There are of course other benefits for implementing Web services and they are therefore a very good ROI for any corporation.

In this article, I will explain how to create a simple Web service from an existing Java application using enterprise-level tools, such as JBuilder X or JBuilder 2005 Enterprise and BEA WebLogic Application Server. I will describe the structure, standards, and logic of a Web service and the platforms involved. To demonstrate a Web service in action, a project with a server and a client will be created. The client will initiate a real Web service session to the server. I will also briefly describe how to accomplish the same, by using freely available tools such as Eclipse IDE and Axis Toolkit.

Hosting Environment

To have a working Web service, an Application Server capable of hosting it to the world is required. A,Web service also may be optionally registered with any public UDDI (Universal Description, Discovery, and Integration) registry or with a local UDDI registry hosted on an application server. The UDDI provides address book functionality to the potential business clients; it allows the client to locate a particular service and describes what kind of APIs are available. Without the UDDI registry, business clients can (and often will) go directly to a Web service URL and request a WSDL (Web Service Definition Language) document that also will contain a detailed description of what APIs are provided. The WSDL is an XML document that is hosted by the Application Server.

In a true business environment, WSDL should define not only all methods that are available but also a schema for all transactions. WSDL is designed to be understood by Web Service programs to help them create object stubs with methods to call on the client-side; a WSDL file is therefore auto generated by the toolkit that will be used to create a Web service.

A Web Service will be hosted as a Web application, inside of a web service container on an Application Server. Any interested client will initiate a regular HTTP session to interact with it. To set up Web service, Bea WebLogic Application server will be used, which is one of the industry leading platforms. It is available for free for development purposes, but for a production environment it will require a license. As an alternative, a free Tomcat application server and Axis toolkit or Jetty application server and Axis toolkit can be used. There are other Application Servers, notably JBoss, SunOne from Sun Microsystems, and WebSphere from IBM, but they are beyond the scope of this article. Any of these Web platforms are capable of hosting a Web application and services. For the development side, JBuilder X or 2005 Enterprise provides tremendous flexibility and ease in creating Web services. I also highly recommend the free Eclipse IDE with WebSphere or IBM WSAD tool for creating Web services hosted on WebSphere application server, but they are beyond the scope of this article.

Installation of BEA Weblogic is very straightforward, but JBuilder needs to be configured to hook into the Application server. Directions are as follows: In JBuilder, under the Tools menu, click Configure Servers to set up an application server setting.

Figure 1: Set up Custom parameters for the server.

Figure 2

Creating a Legacy Project

Create a new project in JBuilder. Create a new “beanexport” package in that project and add one class called Bean1. Another class called Tuple (see Listing 1, at the end of this article) can be created as well. The tuple class holds a pair of strings and is used to demonstrate a more complex object sent via a Web service. It is completely optional and does not need to be used.

Exposing Code as a Web Service

For the demonstration purposes of wrapping existing “legacy” APIs and turning them into a fully functional Web service, consider an extremely simple Java class called Bean1 that has only three methods. One method always returns a random number, another a “Hello” string, and another a more complex object.

The class exposes a public API of just three methods, but a real-world application will contain a much more complex API. An enterprise application can have hundreds of methods returning values from databases, EJBs, or Mainframe call wrappers. Some methods will be taking parameters, others initiating a business transaction dialogue. But, it will be just as easy to convert any complex API into a Web Service API, as it is this sample class.

package beanexport;
import java.io.Serializable;

public class Bean1 implements Serializable {
   public double getDouble(){
      return Math.random();
   }

   public String getText(){
      return "Hello";
   }

   public Tuple getHeader(){
      Tuple t = new Tuple("Vlad","Kofman");
      return t;
   }

}

Please see Listing 1 for the Tuple object source.

Creating a Web Service

Assuming that the Bean1 Java project in JBuilder is set up and can be compiled successfully, and BEA Weblogic Server is up and running, the Bean1 class can now be exposed as a Web service. JBuilder truly simplifies the creation and deployment of any Web service. With the Bean1 project opened, follow these steps:

1. Click Project -> Project Properties -> Server.
2. Weblogic should be listed as one of the choices; choose it.

Note: Web services can also be developed with JBuilder for deployment on a free Tomcat server; it appears here as a choice also.

3. Additional configuration of services: A project will host on the chosen allocation server such as EJB. Servlets and JSPs can be selected as well, but for now, click OK.



Figure 3

4. Click File -> New -> Web Services.
5. Click New Web Service Configuration (JBuilder X).
6. Choose Weblogic as toolkit, default is Axis (used with Tomcat server).
7. Choose server and client modules.
8. Create new Web Module; accept all defaults for now.
9. Create new application module; also take all default values.



Figure 4

10. In the next screen, name the server Bean1Server and save.

JBuilder automatically creates all necessary J2EE (Java 2 Enterprise Edition) standard folders and files structures. It should open a Web Services Designer view after the initial configuration is saved.

Now, for the easy part. The Bean1 project should have the following structure (left panel):

• Package “beanexport”
• ApplicationModule1 module
• Web-services module
• Web-services designers

Take the Bean1 class and drag-and-drop it on to the Web-services designers Area. Or, click the Create Service drop-down and choose Java Service.

Re-build the Bean1 project; more files should be auto-created in the different subfolder of the project. That is it; the Web service is done. All that remains is to deploy it!

Any Web service communicates over a HTTP (or HTTPS) protocol, The Client sends a SOAP—Simple Object Access Protocol—request and waits for the SOAP response. SOAP is basically XML in a special format that describes the communication. Behind the scenes, both server and client have XML parsers and encoders communicating over an HTTP socket. After the request is received, it is decoded into the specific method to call, with what parameters, and after that method is invoked, its return value (if any) is enclosed into XML-SOAP envelope and pushed back.

According to the J2EE specification, a very specific application structure must exist to be used as a Web application. WAR—Web ARchive—files contain deployment descriptors and code and are packed in to EAR—Enterprise ARchive—files for final installation on the application server. Because this specification is the same for all platforms, any code in WAR and EAR packages developed with any toolkit should work on any application server; however, most application server vendors will probably be different in their deployment descriptor files.

Thankfully, JBuilder takes the complexity out of making Web applications, but a standalone Axis Java2WSDL tool can always be used and manual packaging of code into an EAR file is possible. Please see the reference section for more Axis documentation.

Sample Server

Figure 7

JBuilder will indicate something like this:

Initiated Task: [0] [Deployer:149026]Deploy application
                ApplicationModule1 on myserver.
Task 0 running: [Deployer:149026]Deploy application
                ApplicationModule1 on myserver.
Deployment completed on Server myserver

That is it! Your new Web service is now hosted and ready to be used by the world!

It also can be undeployed and redeployed in the same way. All current deployments also can be listed from the same menu.

To test, either open JBuilder -> Tools-> Web Services Console or point your Web browser to http://localhost:7001/web-services/Bean1.

A Web-based test client provided by Weblogic of the new service should appear, invoking SOAP communication behind the scenes to call Bean1’s methods. It can even show the XML being sent around.

For example, clicking on the getText() method will result in the following:

Request sent to the server:

<!--REQUEST.................-->
<env:Envelope xmlns_env="http://schemas.xmlsoap.org/soap/envelope/"
              xmlns_xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns_soapenc="http://schemas.xmlsoap.org/soap/encoding/"
              xmlns_xsd="http://www.w3.org/2001/XMLSchema">
   <env:Body env_encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <m:getText xmlns_m="http://beanws">
   </m:getText>
   </env:Body>
</env:Envelope>

Response from the server:

<!--RESPONSE.................-->
<env:Envelope xmlns_env="http://schemas.xmlsoap.org/soap/envelope/"
              xmlns_xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns_soapenc="http://schemas.xmlsoap.org/soap/encoding/"
              xmlns_xsd="http://www.w3.org/2001/XMLSchema">
   <env:Body env_encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <m:getTextResponse xmlns_m="http://beanws">
         <result xsi_type="xsd:string">Hello</result>
      </m:getTextResponse>
   </env:Body>
</env:Envelope>

The whole WSDL file can be viewed by appending “?WSDL” to the URL:

http://localhost:7001/web-services/Bean1?WSDL

The production server deployment would be of course not with JBuilder, but its equally easy-to-use, Web-based administration Console, usually running on same port as the Weblogic server, for example http://localhost:7001/console, to deploy EAR files.

Please read the Weblogic documentation on how to use their server administration; the ApplicationModule.EAR file can be found in the JBuilder project directory.

Simple Client

The Weblogic test client is not very useful for business; other clients will want to use this Web service with their own implementations. The general mechanism for creating a client is to point the Web service toolkit to the WSDL file and have it generate the client object stubs. The stubs then will be used to open a port to the server and call its methods. They also hide all the complexity of marshaling and un-marshaling of SOAP that is occurring behind the scenes. But, because the client module was added to the project, JBuilder intuitively added a GeneratedWebServicesClient folder to the project and created Bean1_client.jar.

The jar contains all the necessary files to make a fully functional client for the Bean1 service.

Here is how to create a simple test client:

Create a new package called “test”, and add the new Test class.

Then, import package beanexport.generated.*; it should already be in the class path because it is in the project.

Create a connection to the service via gerenated stubs:

String wsdlUrl = "http://localhost:7001/web-services/Bean1?WSDL";
Bean1 service = new Bean1_Impl(wsdlUrl);    //bind to service
Bean1Port port = service.getBean1Port();    //get port

And call any method. Here is the complete listing:

package test;

import beanexport.generated.*;

public class Test {
   public static void main(String[] args) {
      try {
         String wsdlUrl = "http://localhost:9501/web-services/Bean1?WSDL";
         Bean1 service = new Bean1_Impl(wsdlUrl);
         Bean1Port port = service.getBean1Port();

         int result = port.getInt();
         System.out.println("Int is: " + result);

         Tuple[] tuple = port.getHeader();

         System.out.println("1st tuple: " + tuple[0]);
         System.out.println("2nd tuple: " + tuple[1]);

         }
         catch (Exception e) {
         e.printStackTrace();
      }

   }
}

The result would be an executable program that uses a Web service for communication with the server, calling APIs that were just legacy Java methods, but are now Web service calls.

Conclusion

This article has covered the basics of Web services. It created a simple Java class and turned it into a fully functional Web service. Also, this article discussed how to produce a client to talk to the server and invoke SOAP communication.

Packaging “legacy” code as a Web service mostly involved an understanding of the tools at hand. By hiding all the “plumbing” and complexities of marshaling SOAP and XML parsing, current application servers and toolkits make it very easy to create new or expose existing code as new Web services. This also lets developers concentrate on the business transactions and logic instead of dealing with low-level protocols and communications.

Listing 1

Tuple Class

package beanexport;

import java.io.Serializable;

public class Tuple
   implements Serializable {
      private String key;
      private String value;

      public Tuple() {
      }

   public Tuple(String key, String value) {
      this.key = key;
      this.value = value;
   }

   public Tuple(Object key, Object value) {
      this.key = key.toString();
      this.value = value.toString();
   }

   public String getValue() {
      return value;
   }

   public String getKey() {
      return key;
   }

   public String toString() {
      return key + " : " + value;
   }

   public void setKey(String key) {
      this.key = key;
   }

   public void setValue(String value) {
      this.value = value;
   }
}

About the Author

Vlad Kofman is a system architect working on projects under government defense contracts. He has also been involved with enterprise-level projects for major Wall Street firms and the U.S. government. His main interests are object-oriented programming methodologies and design patterns.

Sources

Download the accompanying source code here.

Online Reference Materials and Books

http://www.uddi.org/

The Universal Description, Discovery, and Integration (UDDI) protocol is one of the major building blocks required for successful Web services. UDDI creates a standard interoperable platform that enables companies and applications to quickly, easily, and dynamically find and use Web services over the Internet. UDDI also allows operational registries to be maintained for different purposes in different contexts. UDDI is a cross-industry effort driven by major platform and software providers, as well as marketplace operators and e-business leaders within the OASIS standards consortium. http://www.uddi.org/.

www.w3.org/TR/wsdl

WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate, however, the only bindings described in this document describe how to use WSDL in conjunction with SOAP 1.1, HTTP GET/POST, and MIME.

Borland Software Corporation

http://info.borland.com/techpubs/jbuilder/

Developing Web Services with JBuilder X Enterprise

Developing Web Services with JBuilder 2005 Enterprise

http://info.borland.com/techpubs/jbuilder/jbuilder2005/websvcs/contents.html