Creating Web services using GLUE: an easy development framework

Creating Web services using GLUE: an easy development framework – GLUE

Shannon Ma

GLUE, by The Mind Electric, is a framework for developing and publishing Web services. It is simple, easy, and fast to create Web services. GLUE supports SOAP1.2, WSDL1.1, and UDDI v2. It comes in two editions: GLUE standard is free, and GLUE Professional has more advanced features. The Mind Electric hosts a Yahoo group for developers to post questions and share knowledge.

This article provides an introduction to how to use GLUE, including publishing and invoking Web services, working on SOAP messages, using SOAP over JMS, publishing EJBs as Web services, and publishing and inquiry using UDDI.

A Simple Web Service

Let’s start by creating a simple Web service. Assume that we have an online bookstore service that provides searching for books by keywords. Here is the Java interface, which has one method that takes a string of keywords and returns a list of books matching the keywords.

public interface OnlineBookStore

{

public List keywordSearch(String keywords);

}

Suppose we have a class, OnlineBook StoreImpl, that implements the interface. For simplicity, the implementation will return three books if the keywords are “java web service” (see Listing 1; the code for this article is online at www.sys-con.com/webservices/ sourcec.cfm).

Now we want to publish this class as a Web service. Using GLUE, we only need two lines. First, we start up an HTTP Web server on local host using port 8000, and give an application name “book”. Second, we publish an instance of the class as a web service with the name “Online BookStore”.

electric.server.http.HTTP.startup(

“http://localhost:8000/book” );

electric.registry.Registry.publish(

“OnlineBookStore”, new

OnlineBookStoreImpl( ));

GLUE will generate the WSDL (Web Service Description Language) file automatically and you can access it from http:// localhost:8000/book/OnlineBookStore.wsdl. The WSDL file for our service is in Listing 2.

Invoking a Web service is equally simple. First, get the URL of the WSDL of the service and bind to the service by passing the WSDL and the interface class. Then, invoke the method just like a normal method invocation.

String wsdl =

“http://localhost:8000/book/OnlineBookSt

ore.wsdl”;

OnlineBookStore service =

(OnlineBookStore)

electric.registry.Registry.bind( wsdl,

OnlineBookStore.class );

List list = service.keywordSearch(“java

web services”);

Working with SOAP Messages

The underlying structure for transporting XML documents is SOAP (Simple Object Access Protocol), a standard packaging mechanism. In our last example, the SOAP message is encapsulated from GLUE. Sometimes you need to work on low-level SOAP messages directly. GLUE provides SOAP-level APIs for you to create, send, and parse SOAP messages. After going through the following exercise, you’ll have some idea of how to use SOAP messages.

This time we’ll perform a keyword search on books using Amazon.com’s Web services. Amazon.comWeb services offer applications that range from retrieving information about a set of products to adding an item to a shopping cart. The WSDL file of the Amazon.com Web services can be found at http://soap.amazon.com/schemas2/Ama zonWebServices.wsdl.

1.Make a SOAP connection: We can get the endpoint of the Web services from the WSDL file and create a logic connection to the endpoint. In our example, the endpoint is http://soap.amazon. com/onca/soap.

String endpoint = “http://soap.amazon.

com/onca/soap”;

electric.soap.SOAPConnection connection

= new electric.soap.SOAPConnection(endpoint);

2. Create a SOAP message, and add a “SOAPAction” to the HTTP header: The value of the SOAP action is also read from WSDL.

electric.soap.SOAPMessage request =

new electric.soap.SOAPMessage();

request.addMIMEHeader(“SOAPAction”,

“http://soap.amazon.com”);

3. Create a SOAP envelope and set some general namespaces.

electric.xml.Element envelope =

request.addEnvelope();

envelope.setNamespace(“soapenc”,

“http://schemas.xmlsoap.org/soap/encoding/”);

envelope.setNamespace(“soap”,

“http://schemas.xmlsoap.org/soap/envelope/”);

envelope.setNamespace(“xsi”,

“http://www.w3.org/2001/XMLSchemainstance”);

envelope.setNamespace(“xsd”,

“http://www.w3.org/2001/XMLSchema”);

4. Create a SOAP body: Set the message name (KeywordSerarchRequest), SOAP encoding style, and namespace.

electric.xml.Element body =

request.addBody();

electric.xml.Element

method = body.addElement();

method.setAttribute(“soap:encodingStyle”

,

“http://schemas.xmlsoap.org/soap/encoding/”);

method.setName(“namesp1:KeywordSearchReq

uest”);

method.setNamespace(“namesp1”,

“urn:PI/DevCentral/SoapService”);

5. Put the keyword search parameters into the message: Under the “KeywordRequest” element, specify the following:

–Keyword is “java web services”.

–Page number is “1”, which means return the first page of the result.

–Product mode is “books”.

–Tag is “webservices-20” (Amazon Web services 2.0)

–Document type is “lite”

–Developer tag is “D11EFJ3ULGUTHN”. (you need to obtain a tag from Amazon.com before you can use the Web services.)

–Version is “1.0” (see Listing 3).

6. Invoke the Web service by calling invoke on the SOAPConnection: Pass the SOAP message we just created and get a list of books matching the keyword “java web services”.

electric.soap.SOAPMessage response =

connection.invoke(request);

Listing 4 is the generated “Keyword-SearchRequest” SOAP request message. The complete code for the SOAP message is in Listing 5.

SOAP over JMS

JMS (Java Message Service) provides reliable and guaranteed delivery messaging. GLUE provides a mechanism for sending and receiving SOAP messages over JMS. Built-in adapters are included for MQSeries (IBM), SonicMQ (Sonic Software), TIBCO JMS (TIBCO), and SwiftMQ (IIT Software). For other JMS products, you can write your own adapter. We will use the same example, OnlineBookStore, to demonstrate SOAP over JMS using the SonicMQ JMS Server.

Publishing a Web service using JMS is similar to publishing one using HTTP. Start the SonicMQ Broker, do the following, and the Web service will be ready over JMS:

electric.server.jms.JMS.startup(

“jms:///book” );

electric.registry.Registry.publish(

“OnLineBookService”, new

OnlineBookServiceImpl() );

It creates a queue named “GlueQueue/ book” in SonicMQ. To invoke the service, just bind to the service using JMS and call the method.

String wsdl =

“jms:///book/OnlineBookStore.wsdl”;

OnlineBookService service =

(OnlineBookService)

electric.registry.Registry.bind( wsdl,

OnlineBookService.class );

List list = service.keywordSearch(“java

web services”);

The example above uses synchronous messaging. JMS also provides asynchronous messaging that loosely couples the sending and receiving of the messages. To receive SOAP messages asynchronously, we need to add another method with a different signature to our interface OnlineBookStore.

public void keywordSearch(String keywords,

electric.util.async.Async

async);

You may have noticed that the new method is different from the previous method in that it has an extra parameter of type Async and the return type is void. Now we add the implementation of the method in our class OnlineBookStoreImpl.

Publishing the Web service is the same for both synchronous and asynchronous messaging. The difference is the invoking. Contrary to the invoking of a synchronous method, when you invoke an asynchronous method there is no response returned as the result of the method call. Instead, after binding to the Web service we need to create an instance of Async and pass it to the asynchronous method. Now we can do something else, then call getResponse on Async to get the result (see Listing 7).

Publishing EJBs as Web Services

GLUE can publish any stateless session bean as a Web service. It uses a generic IService interface that allows different kinds of objects to be exposed. GLUE includes an implementation of IService called StatelessSessionBean Service that acts as a proxy to forward a SOAP request to the stateless session bean, and return the result as a SOAP response.

We will show, in the example, how to publish a stateless session bean that runs on WebLogic App Server. First we’ll create a GLUE application to run in WebLogic using the ‘newapp’ command-line utility.

> newapp -h ejb2ws

Now we have a Web application called ejb2ws. Next we’ll create an XML file called ejb2ws.xml and save it under ejb2wsWEBINF services. The file will look like Listing 8, assuming that we have an EJB with the JNDI name OnlineBookStore and a home interface named OnlineBookStoreHome.

The ejb2ws.xml file provides the Stateless-SessionBeanService with information on both the BEA WebLogic Server and the stateless session bean. We can add the following to instruct WebLogic to load the GLUE application to config.xml of the domain of the application server, assuming that our ejb2ws application is under d:myapplication.

<Application Deployed="true"

Name=”ejb2ws” Path=” d:myapplication”>

<WebAppComponent Name=" ejb2ws "

Targets=”myserver” URI=” ejb2ws “/>

Starting the WebLogic Server will expose the stateless session bean as a Web service.

Using UDDI

UDDI (Universal Description, Discovery and Integration) provides a registry of Web services for advertisement, discovery, and integration purposes. You can use GLUE to publish your business to a registry, or to search for a business using UDDI.

The following code snippet demonstrates publishing a service through UDDI. For simplicity, we use GLUE’s UDDI server.

electric.server.http.HTTP.startup(

“http://localhost:8004/glue/inquiry”,

“/inquiry” );

electric.server.http.HTTP.startup(

“http://localhost:8005/glue/publication”,

“/publication” );

electric.uddi.server.UDDIServer server =

new electric.uddi.server.UDDIServer(

“inquiry/uddi”, “publication/uddi”, “publication/

admin”, “/uddi”, true );

server.setOperator( “me” );

Now we are ready to publish our online book service. Remember that a valid user is required when publishing a service (Listing 9 is the code to create a user).

1. Create a UDDI client connecting to the UDDI server.

String inquiryURL = “http://localhost:

8004/glue/inquiry/uddi”;

String publicationURL = “http://localhost:

8005/glue/publication/uddi”;

String user = “me”;

String password = “ok”;

electric.uddi.client.UDDIClient uddi =

new electric.uddi.client.UDDIClient(

inquiryURL, publicationURL , user , password);

2. Define the business and add some contact information.

electric.uddi.Business business = new

electric.uddi.Business( new

electric.uddi.Name( “Online Book Store,

Inc.”, “en” ) );

electric.uddi.Contact contact = new

electric.uddi.Contact( “support” );

contact.setUseType( “Support” );

electric.uddi.Email email = new electric.

uddi.Email( “support@onlinebook.com”

);

contact.addEmail( email );

electric.uddi.Phone phone = new electric.

uddi.Phone( “1-800-SUPPORT” );

contact.addPhone( phone );

business.addContact( contact );

business.addDescription( new

electric.uddi.Description( “An online

book store” ) );

3. Categorize the business as bookstore (code 451211) using the NAICS 2002 code (North American Industry Classification System) taxonomy.

electric.uddi.Category cat = new electric.

uddi.Category( “ntis-gov:naics:2002”,

“451211” );

cat.setTModelKey(

electric.uddi.IUDDIConstants.UDDI_NAICS_UU

ID );

business.addCategory( cat );

electric.uddi.Business savedBusiness =

uddi.saveBusiness( business );

4. TModel provides information about a Web service specification, categorization specification, or identifier specification. Here we create a TModel categorized as “wsdlSpec” using the “uddi-org:types” taxonomy, which means that it points to the relevant WSDL file.

electric.uddi.TModel tModel = new electric.

uddi.TModel( “Online Book Store” );

electric.uddi.Category category = new

electric.uddi.Category( “uddi-org:types”,

“wsdlSpec” );

category.setTModelKey(

electric.uddi.IUDDIConstants.UDDI_TYPE_TAX

ONOMY_NAME_UUID );

tModel.addCategory( category );

String url =

“http://localhost:8000/book/OnlineBookStor

e.wsdl”;

electric.uddi.Overview overview = new

electric.uddi.Overview( new

electric.uddi.Description( “wsdl link” ),

url );

tModel.setOverview( overview );

electric.uddi.TModel savedTModel =

uddi.saveTModel( tModel );

The complete code is shown in Listing 10.

As I mentioned earlier, another big use for UDDI is to perform inquiries. The example here demonstrates an inquiry using GLUE by connecting to the XMethods’ UDDI server. XMethods is a “virtual laboratory” for developers, listing publicly available Web services and showcasing new ways of using this particular technology.

1. Create a UDDI client connecting to the XMmethods UDDI server.

String inquiryURL =

“http://uddi.xmethods.net/inqu

ire”;

electric.uddi.client.UDDIClien

t uddi = new

electric.uddi.client.UDDIClien

t( inquiryURL );

2. Search a list of businesses containing the word “bookservice”, and get the TModel of the first one found.

electric.uddi.FindTModels

findTModels = new

electric.uddi.FindTModels();

findTModels.setName( “bookservice”

);

electric.uddi.TModelInfos

tModelInfos =

uddi.findTModels( findTModels

);

String tModelKey =

tModelInfos.list[ 0

].getTModelKey();

electric.uddi.TModel tModel =

uddi.getTModel( tModelKey );

3. Get information for the services with bindings to implement the TModel, and get the service of the first match.

electric.uddi.FindServices

findServices = new

electric.uddi.FindServices();

findServices.setTModelKeys(

new String[]{ tModelKey } );

electric.uddi.ServiceInfos

serviceInfos =

uddi.findServices(

findServices );

String serviceKey =

serviceInfos.list[ 0

].getServiceKey();

electric.uddi.Service service

= uddi.getService( serviceKey

);

4. Get the first binding of the service and obtain the endpoint address and URL of the WSDL.

electric.uddi.Binding binding

= service.getBindings()[ 0 ];

String address =

binding.getAccessPoint().getAd

dress();

String wsdlURL =

tModel.getOverview().getOvervi

ewURL();

The results we get are:

wsdlURL =

http://hosting.msugs.ch/cheeso

9/books/books.asmx?WSDL#LookyB

ookServiceSoap

address =

http://hosting.msugs.ch/cheeso

9/books/books.asmx

The complete code is shown in Listing 11.

Summary

This article is an introduction to GLUE, a framework for developing Web services. Hopefully it has provided you with a good understanding of the Web services features GLUE provides.

References

* The Mind Electric GLUE: www. themindelectric.com/glue/ind ex.html

* The Mind Electric Yahoo Group: http://groups.yahoo.com/gr oup/MindElectricTech nology/

* Amazon.com Web services: http://associates.amazon.com /exec/panama/associates/ntg /browse/-/1067662/104-6667 851-1953517

* SonicMQ from Sonic Software: www.sonicsoftware. com /products/sonicmq/index .ssp

* BEA WebLogic Application Server: www.bea.com/framework. jsp?CNT=index.htm&F P=/content/products/server

* XMethods: www.xmethods. com

Shannon Ma is a senior software developer specialized in J2EE, Web Services and BPM. He is currently working at AVAO Corporation, a software company that provides a robust, comprehensive and portable business-process management system (BPMS). SHANNON.MA@AVAO.COM

COPYRIGHT 2003 Sys-Con Publications, Inc.

COPYRIGHT 2003 Gale Group