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/OnlineBookStore.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.com Web 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/AmazonWebServices.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/XMLSchema-instance");
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:KeywordSearchRequest");
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 "KeywordSearchRequest" 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 ejb2ws\WEB-INF\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 StatelessSessionBeanService 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.

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_UUID );
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_
TAXONOMY_NAME_UUID );
tModel.addCategory( category );
String url =
"http://localhost:8000/book/OnlineBookStore.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/inquire";
electric.uddi.client.UDDIClient uddi =
new electric.uddi.client.UDDIClient( 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().getAddress();
String wsdlURL = tModel.getOverview().getOverviewURL();

The results we get are:

wsdlURL = http://hosting.msugs.ch/cheeso9/books/books.asmx?
WSDL#LookyBookServiceSoap
address = http://hosting.msugs.ch/cheeso9/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

• Source Code