Book Reviews

Subscribe to Book Reviews: eMailAlertsEmail Alerts newslettersWeekly Newsletters
Get Book Reviews: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

Book Reviews Authors: Kenrick Freemen, Tad Anderson, Sharon Drew Morgen, Holocaust Research Project, Stewart McKie

Related Topics: Java EE Journal, Apache Web Server Journal

J2EE Journal: Article

Building SOAP Web Services with WebLogic 6.1

Building SOAP Web Services with WebLogic 6.1

Web Services have made quite an impact since the concept and technology were introduced. Just about every major vendor is putting considerable effort into making their products capable of developing and using Web services.

This article will illustrate how a Web service can be developed and deployed with the Web services capabilities found in WebLogic 6.1. A sample application that illustrates how to use SOAP and Web services to make an application deployable anywhere and accessible from any technology will also be reviewed.

Web services has been getting a tremendous amount of attention over the past year - and in my opinion, justly so. The concept of a Web service is simple, but opens up tremendous opportunities for companies that use the Internet to provide or use business services. For example, a company that sells heavy machinery needs the services of a shipping company to deliver their products. A Web service allows the heavy machinery company to make an HTTP call over the Internet to the shipping company to send the shipping address and weight. The Web service then determines the cost and allows the heavy machinery company to book the shipping service and pay for it.

Interestingly enough, the heavy machinery company can use this shipping Web service on all their orders, regardless of how the order comes in. The success or failure of this Web services model is not dependent on how consumers make their purchases. Web services are a server-to-server and business-to-business model. Some of the key goals of the Web services business model are to reduce costs, increase customer service, and increase sales by making their services more easily accessible.

Web services are pure back-end business components that are built for computer access - not human access. There is no concern for "look and feel" when you develop Web services The "usability" and the success of the service revolve around robustness of the methods and properties of the service.

The technologies used in Web services are based on the industry standards of XML and HTTP. This allows collaboration among businesses providing and utilizing Web services across any technology. The heavy machinery company's system can be built completely in Microsoft technology that invokes services on the shipping company's Enterprise Java Beans server.

Fundamentally, as long as Web services are built so that they can transmit and receive data in XML format and are accessible via HTTP, anyone should be able to use those services regardless of their technology. But relying only on those technologies leaves many of the components required for building truly useful Web services to be developed by the service providers and consumers. This can lead to incompatibilities between service providers and consumers and a lot of reinvention of the same core services.

Some additional technologies that are an extension to the basics of XML and HTTP have been developed that define in more detail how Web services can operate. These technologies are SOAP (Simple Object Access Protocol), WSDL (Web Services Description Language), and UDDI (Universal Description, Discovery, and Integration). These further standardize and enhance the ability of Web service providers and consumers to interact.

SOAP is the specification for the actual documents (requests and responses) that contain the data sent and received in the Web service transactions. WSDL provides information about the Web service, such as the available methods and their arguments. UDDI is essentially a directory mechanism for broadcasting and searching for available Web services on the Internet.

SOAP is a protocol for exchanging information between Web service providers and consumers. The protocol is based on XML and HTTP, which makes using SOAP very easy when you make calls across distributed heterogeneous computing environments. SOAP enables the use of Web services based on a shared and open Web infrastructure and takes the idea of Web services beyond the initial idea of simply passing XML back and forth between Web systems. It allows developers to perform RPC calls on methods that have been discovered through WSDL.

SOAP is a step beyond other RPC technologies, such as COM or CORBA, because it does not require a particular vendor's product or technology to make it work. CORBA requires a particular ORB that the client and server must adhere to; COM requires specific technologies on both sides to make it work. SOAP is an open standard that can be used with any technology that supports those standards. The SOAP Protocol has the following components:

  • The SOAP Message is an XML document that is passed between the Web Service Requestor and the Web Service Provider. This message is made up of a SOAP Envelope, a SOAP Header, a SOAP Body, and a SOAP Fault. The SOAP Envelope is required for all SOAP messages and contains the SOAP Body and SOAP Header. It also can contain encoding styles and, possibly, versioning information. The SOAP Header is optional in a SOAP Message. It is used to provide user authentication or transaction management. The SOAP Body contains the data being sent in the message. The SOAP Fault element is a predefined child of the SOAP Body and contains error status information. It is used only in SOAP Responses.
  • A set of SOAP Encoding Rules and binding conventions that process the SOAP Request and Response messages and make them useful for the server and the client. These encoding and decoding processes are implemented by each of the languages that support SOAP, similar to the way that vendors have developed XML serializers and deserializers. These libraries automatically handle encoding and decoding the SOAP Messages so that from a SOAP Client, the developer just needs to instantiate a SOAP Object, connect to the remote SOAP Web service, and then invoke the methods on that SOAP Server.

    The Web Services Description Language is an XML-based specification schema that describes a Web service's methods and interfaces. A Web services client would use WSDL to collect information about the Web service's methods and properties. Most SOAP Client implementations will automatically build bindings to the service's methods and properties automatically so the developer doesn't have to do it explicitly.

    In the following example, a Microsoft ASP application is invoking an EJB.

    set soapclient = CreateObject("MSSOAP.SoapClient")
    call soapclient.mssoapinit
    set Contacts = soapclient.getAllContacts()
    The initial call to "mssoapinit" loads the Web service's WSDL into the client object of "soapclient" so that subsequent method calls, "soapclient.getAll-Contacts()", can be checked against the supported methods within the Web service. If a call is made to an invalid method name, an error will be generated.

    WSDL Documents contain the following elements to define a Web service:


  • The Types element, shown in Listing 1, describes the data type definitions of the Web service.
  • The Message element defines the data being communicated via the Web service, including data inputs and outputs, in effect, the messages supported by each of the methods. Listing 2 is an example from our sample Web service. Each method supported in our Web service contains a corresponding Request and Response message in the WSDL.
  • The Operation defines an action that a Web service can perform.
  • The Port Type describes the set of operations one or more ports support. In the example below, the port type describes the input and output messages supported by each Operation (method).

    - <portType name="ContactListingEJBPortType">
    - <operation name="getContactsMatching">
    <input message="tns:getContactsMatchingRequest"/>
    <output message="tns:getContactsMatchingResponse"/>


  • The Binding describes the protocol and data format for the port type. As Listing 3 shows, the Binding describes the encodingStyle and other elements for the data format.
  • The Port is the endpoint location of the service defined by a binding and a network address.
  • The service describes a group of related ports. The following is an example of the service and port elements of the WSDL used in our sample Web service application. The location element defines the exact location of the actual Web service.

    - <service name="ContactListingEJB">
    - <port name="ContactListingEJBPort"
    <soap:address location=

    As you can see, there is a lot involved in the inner details of SOAP and WSDL. WebLogic creates the WSDL and all the SOAP Protocol communications for you automatically so you can focus your efforts on building the actual EJBs and business logic that provide the service functionality.

    Another protocol that is a key part of Web services development, UDDI, is used to advertise the existence of a Web service. UDDI services are used to create or find a UDDI registry in either a private or public directory. The UDDI registry itself is an XML packet that contains information about how to access specific Web services and the corresponding information about the organization that provides it. Essentially, it is a way to find WSDLs. Figure 1 illustrates the process that a requestor of a Web service would go through. First it identifies the service that is available via UDDI. Its search will yield a WSDL that contains all the necessary data that allows the requestor to access and use the Web service via SOAP.

    WebLogic does not currently have direct support for UDDI, but it is planned for the near future. Our sample Web service application does not include the ability to create a registry for our Web service; however, an overview of UDDI and how it works is described below. The main components of UDDI include:


  • A businessEntity element that describes information on the business providing the Web service
  • A businessservice element that contains links to more specific information about the services provided.
  • A bindingTemplate element that contains information about what the service can do and where to access the service.
  • A tModel element that describes the data for the service and how to access it.

    All of the components of creating and registering into UDDI registries will become automated processes. From a developer's perspective, UDDI can be viewed simply as a repository containing specific and associated Web services information, like a Java Naming and Directory Interface. Developers would use these tools to access a UDDI registry to locate services information, prepare systems for Web services compatibility, and to describe their own Web services.

    Web Service Support
    WebLogic 6.1 supports the ability to create Web services and clients. Specifically, support for all of the following is now available:

    SOAP server support

  • WLS 6.1 provides a servlet-based SOAP implementation that integrates with stateless session beans and JMS.
  • SOAP invocations can be mapped to a stateless session bean method or cause a JMS message to be produced for consumption by a JMS listener, such as a message driven bean.
  • These components can interact with the rest of the WebLogic Server J2EE application environment.
  • The SOAP implementation supports SOAP 1.1 (with attachments) over HTTP; however, attachments are currently ignored ( webServices/overview.html#1037109)

    SOAP Java client included in 6.1

  • WLS 6.1 provides a thin Java client for Web services. No Weblogic.jar is required unless a WSDL is not provided by the service to be consumed, then certain WebLogic classes are needed ( webServices/advanced.html#1001373)
  • Thin client downloadable from URL.
  • Interface and proxy automatically generated from WSDL.

    WSDL Support

  • WLS 6.1 automatically generates WSDL for stateless EJBs and JMS.
  • WLS WSDL is accessible and downloadable from user-defined URLs to support publishing and retrieval of Web services.

    UDDI Support

  • A UDDI client will be available on the BEA Developer center to support publishing and retrieval of Web services in a UDDI registry.


  • WebLogic's Web services implementation of SOAP is interoperable with other vendors' implementations. We will demonstrate Microsoft SOAP Client, a Perl SOAP Client, an Apache SOAP Client, and a BEA SOAP Client accessing our WebLogic SOAP Server later in this article.


  • Supports security and transactions via standard J2EE mechanisms.
  • HTTP-authenticated identity can be passed to EJBs. WLS 6.1 Web services supports J2EE roles via Web application and EJB deployment descriptors.

    Contact Management Application Example
    To illustrate the process of building and deploying a Web service with WebLogic 6.1, we took an existing J2EE application and exposed it as a SOAP Web service. The application is a Contact Management Application that returns a list of matching contacts via a last name or company name that is entered by the user. The application was built as a multi-channel Model - View - Controller application with the ability to dynamically render both the input form and the results in WML or HTML through XSLT. Accessing the same URL via either the Web or an Internet phone invokes the same back-end EJB that performs the search and returns the results. The WML and HTML interfaces access a servlet that formats the data through an appropriate XSL and returns it.

    Figures 2 and 3 are examples of an Internet phone and Web browser both invoking the same URL We also wanted to add to the existing architecture a way for other servers to access our EJB so that they could use the services in ways that are incorporated into business processes in new and different ways.

    By taking our business logic of retrieving and returning Contacts that are contained in an EJB and exposing it as a Web service, we allow any SOAP client to access that service. Figure 4 is an example of a Visual Basic application that invokes the service, passing it a partial last name and having the EJB, through SOAP, return that data!

    The architecture of the SOAP component is illustrated by the diagram in Figure 5. The SOAP Client first invokes a session on the SOAP Server by accessing the WSDL. This returns information about the SOAP service back to the client so that it knows how to call the methods contained in the service. The method calls are then made via a Servlet that provides XML Parsing and SOAP encoding/decoding that interfaces with our EJB.

    Regardless of the API used to fetch the service proxy and invoke the service operations, the proxy or some delegated object is responsible for marshalling the arguments to XML fragments using the SOAP encoding rules (or some other custom encoding format). The proxy or some delegated object is also responsible for constructing the SOAP document and transmitting the same using a configured transport.

    The transport infrastructure delivers the message to the SOAP processor on the J2EE server. The processor maps the request to a stateless EJB, converts the message arguments to Java types using the SOAP decoding rules (or custom decoders provided by the application), and invokes the EJB. The SOAP processor formulates a SOAP message response using the returned result and relays it back to the client as an HTTP response.

    WebLogic SOAP Server
    When you build a WebLogic Web service several decisions must be made. First, you must decide whether the service will be Message-style or RPC-style. Message-style services are asynchronous in nature and usually data driven. Think of it as posting some data to a service without requiring an immediate response. In WebLogic, these services are implemented as JMS listeners with a publish/subscribe messaging model. RPC-style services use a more interactive model, with clients directly invoking process-oriented methods and getting an immediate response. In WebLogic, these services are implemented as stateless session EJBs. Our example uses an RPC-style service.

    The process of implementing and deploying a SOAP service on WebLogic Server is rather simple. First you implement a stateless session EJB that exposes the methods that you want to make accessible via SOAP. Remember to stick to data types that WebLogic's SOAP implementation supports for parameters and return types of the EJB's methods (see webServices/develop.html#1038901 for details).

    A key design constraint to consider is to have a single deployment that allows clients to access the EJB directly and as a SOAP Web service. The direct EJB call will be accessed by internal clients and the SOAP service will be accessed by external clients. This creates a best-of-both-worlds scenario for WebLogic development - a single set of EJB source code with a single deployment that gives high performance direct-EJB access and open SOAP XML access at the same time!

    To build contracts.ear, the Ant utility ( must be invoked with the projects build file. After you have created the EJBs and are ready for deployment, you may compile it in several different ways. The simplest method is to utilize the Jakarta project's build tool Ant and the custom tasks provided with WebLogic server for compiling and packaging EJBs in a suitable way for the WebLogic environment. There is also a helpful task provided for creating the J2EE application EAR file to represent the SOAP service.

    To build contacts.ear, Ant must be invoked with the project's build file. This will cause the EJBs to be compiled (if necessary), packaged, compiled into a JAR usable by WebLogic, then added into an enterprise application to be invoked as a SOAP service. The wsgen task handles a number of steps that are required to assemble the EAR file. Among them is the generation of the WSDL for this service based on the EJB's class definition through the use of WebLogic utility classes. It is possible to assemble the application by hand, too. For more information about this, see webServices/package.html#1001373.

    The example application also incorporates a Web application front-end that allows other clients to utilize the EJB. This part of the application can currently respond to HTML and WML clients, and can have other types of clients added fairly easily because the output from the JSPs is driven by XSL. The requested JSP determines which XSLT file to use based upon what it can determine about the client making the request. The default response is to return HTML, but if the page senses that the client is a WML browser, the output is WML. This is implemented using the WebLogic XSL custom tag that utilizes the Apache Project's Xalan XSL Transformation engine. The instructions found at docs61/xml/xml_apps.html#1079383 were followed to utilize the custom tag. The build process also uses WebLogic's JSP compiler from within Ant to make certain that the JSP files will compile correctly in the WebLogic environment, saving time by allowing for the correction of JSP errors prior to deployment time.

    The process of integrating this portion of the application with the Web service contacts.ear file may be automated in the Ant build process. The basic idea is to expand contacts.ear and web-services.war, which is created when contacts.ear is expanded. Copy any Web applictaion resources except for web.xml into the directory where web-services.xml was expanded. Next, patch the web.xml file that is created from expanding web-services.xml with what is required for this portion of the application, namely JNDI information for looking up the EJB. Create a Web application based upon this new directory structure and create a new contacts.ear file that includes this Web application and the EJB jar file.

    Creating and using the patch file requires the standard Unix development tools diff and patch. Windows does not have these tools, so see to install them. To create the patch file, make a minimum web.xml file (only has empty web-app tag) and use diff to display the differences between the application's web.xml and the blank one. The command should be similar to <diff -C 2 blank-web.xml web.xml > web.xml.patch to create the patch file. This patch file is then used from within build.xml to patch the web.xml file created by wsgen, preserving all of the elements in the wsgen Web.xml and adding the elements that are necessary for the rest of the Web application.

    Deploy the application as you would any enterprise application into WebLogic server. If all goes well, the application should be accessible at the URI/contacts. From there, the client.jar file can be downloaded for use in creating a WebLogic SOAP client to access the service. Now a client can be built to access this service. The JSP-based client should be accessible at /contacts/list from HTML and WML clients.

    The SOAP Clients
    To illustrate how various clients can interface with our SOAP Server, we have provided examples of four different clients and descriptions of how each accesses the SOAP Server.

    Apache SOAP Implementation
    There are currently two versions of Apache SOAP in development: the current stable version, Apache SOAP 2.2, and the next generation of Apache SOAP, known as Axis, now in alpha. Neither of these clients are WSDL aware, so using them to access SOAP services in a WebLogic server requires some finesse.

    The first step is to locate the actual URI of the service. This can be found by looking for the service element in the WSDL and getting the value for the location attribute of the nested soap:address element. This value is the endpoint to use in the client. Since the Apache clients do not recognize WSDL, they see the WebLogic SOAP service as an untyped server, meaning no xsi:type attribute is provided in the returned XML. You must tell the client what data type to expect from the method call so that it may return the correct data type in the code. Doing this in the Axis client is slightly easier than in the version 2.2 client. Finally, any JavaBeans or other complex data types need to have serializers and deserializers registered for them, depending upon whether the complex type is a parameter or a return type. In the example application, you must register the JavaBean and java.lang.Array deserializers provided with the client classes. At this point, the request can successfully be made to the SOAP service to execute the desired method. Information about the Apache SOAP implementations can be found at

    BEA Java Client
    WebLogic includes a client-side SOAP API that can be used to develop SOAP Clients that can access SOAP Servers of any type - Microsoft, Apache, etc. The WebLogic SOAP Client supports the calling of Web services that contain a WSDL as well as those that do not support the use of a WSDL.

    Accessing a SOAP service with a BEA SOAP client using WSDL is a lot like accessing an EJB. The client uses a javax.naming.InitialContext object with a particular java.util.Properties object to get an instance of an object that represents the service. In the case of the sample application, the object is an instance of the EJB object. Then you may call whatever method the SOAP service exposes.

    When you invoke a Web service via the WebLogic SOAP Client, you can use either a static approach or a dynamic approach. The static method accesses the EJB interface directly and is, therefore, the most type-safe approach. This is the approach we used in our example.

    First, we set up an INITIAL_CONTEXT_FACTORY that allows us to load the service-specific information into the listing object, which is then used to make the direct method calls against the SOAP service which invokes the EJB (see Listing 4).

    The dynamic approach is very similar, except that the client does not explicitly reference the EJB interface in its calls. Instead, it goes through a WebserviceProxy.

    WSDL files make Web services easier and better to use; however, there are occasions where Web services that you need to call do not support the WSDL interface. In these cases, you will need to access the service without a WSDL. The process of invoking non-WSDL Web services includes:

    • Creating a factory for SOAP encoding
    • Connecting to the Web service
    • Getting the send method of the service
    • Sending the SOAP message
    • Processing the SOAP response (if any)
    WebLogic provides all of the relevant Java classes to enable SOAP Clients to carry on SOAP Interactions with non-WSDL Web services.

    Perl implementation
    The Perl client implemented in the example application uses the SOAP::Lite module found at This implementation treats complex data types such as JavaBeans as associative arrays for ease of use. The array of objects returned in Java code is seen as an array of associative arrays using the SOAP::Lite module. The only information that needs to be extrapolated from the WSDL is the namespace attribute of the soap:body elements nested in the input and output elements of the operation elements used to represent the methods in the service. That value must be supplied to the SOAP::Lite client as the URI to use to access the service.

    Microsoft implementation
    The Microsoft Implementation uses the Microsoft SOAP Toolkit 2.0, which can be downloaded from default.asp?url=/nhp/Default.asp?contentid=28000523. The SOAP Toolkit is a set of libraries that allow you to create a connection to any SOAP server and invoke methods contained there.

    To create a Microsoft VB SOAP Client, you first need to include the "Microsoft SOAP Type Library" and the "Microsoft XML, v3.0" libraries in your project. These are both part of Microsoft SOAP Toolkit 2.0. The actual code required to use SOAP Objects is quite small. The first thing you must do is instantiate a SOAP Client Object.

    set soapclient = CreateObject("MSSOAP.SoapClient")
    The next step is to connect that SOAP Client object to a SOAP WSDL. In this case, we are connecting to the BEA WebLogic-generated WSDL.JSP.

    call soapclient.mssoapinit("http://ets_lnx1:7001/contactlistingws/wsdl.jsp")
    The final step is to invoke methods on the SOAP Server. Because we connected to the WSDL, the compiler is able to check for syntax errors if nonexistent methods are called, or are called with the wrong arguments.

    set Contacts = Soapclient.getMatchingContacts( "Elisii")
    In our example, the data being returned from the call is a complex data type; it is an array of objects. In order to handle this properly from VB, we must declare the return type as IXMLDOMNodeList. This allows us to manipulate the nodes of the objects returned as follows:

    Dim Node1 As IXMLDOMNodeList
    Set Node1 = Contacts(0)
    output.Caption = Node1(6).Text 'firstName
    Web services can greatly enhance a business's ability to create a more efficient way for suppliers and customers to access their products and services and to extend their reach to a much wider range of potential customers. Web services allow a customer using any type of technology to reach a business's Web services through HTTP and XML. SOAP and its related technologies, WSDL and UDDI, allow for a more robust way to create and invoke Web services. The SOAP protocols allow clients to make structured Remote Procedure Calls against a server; WSDL allows for the discovery of the SOAP Server details; and UDDI allows for the creation and promotion of the Web service on private or public registries.

    Web Logic 6.1 provides a great platform for deploying existing or new EJBs as SOAP Servers. It is compliant with the industry-standard SOAP implementation, which allows it to be called from any client, including Microsoft's SOAP Client.

  • More Stories By Paul Elisii

    Paul J. Elisii is the founder and CTO of eTech Solutions, Inc., a Philadelphia-based e-business development company and a BEA partner. He is active in developing and researching emerging technologies for eTech Solutions.

    More Stories By Larry Zappaterrini

    Larry Zappaterrini is an XML and Java developer with
    e-Tech Solutions, Inc. He was extremely helpful in
    performing research and in developing the sample
    applications for this article.

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.