WS-Notification sample walkthrough

The event source example, EventSource.java, is a simple event source that sends a single, hard-coded event to the Web Services. It demonstrates the following steps that an event source must follow:

  1. Obtaining an event factory
  2. Creating an event and populating it with required data
  3. Using the generated Web Services client side stubs to send an event

The source code for EventSource.java is available in the <sdk_install_dir>/samples/wsnt-was/src/com/wtci/samples/was/source directory of the SDK.

This example uses Hyades logging classes as well as classes generated from the wsdl files. Use the following import statements to access the required packages:

import com.ibm.wtci.samples.waswsn10.emitter.NotificationConsumerService;
import com.ibm.wtci.samples.waswsn10.emitter.NotificationConsumerServiceLocator;
import com.ibm.wtci.samples.waswsn10.wsn.NotificationConsumer;
import com.ibm.wtci.samples.waswsn10.wsn.NotificationMessageHolderType;

import com.ibm.ws.webservices.engine.xmlsoap.SOAPElement;
import com.ibm.ws.webservices.engine.xmlsoap.SOAPFactory;

import org.eclipse.hyades.logging.events.cbe.CommonBaseEvent;
import org.eclipse.hyades.logging.events.cbe.EventFactory;
import org.eclipse.hyades.logging.events.cbe.EventFactoryFactory;
import org.eclipse.hyades.logging.events.cbe.Situation;
import org.eclipse.hyades.logging.events.cbe.util.EventFormatter;

import java.net.URL;

The main method of EventSource.java creates a new instance of EventSource using the default constructor. It then calls the private sendEvent method, which contains the main program logic. After the sendEvent method returns, the main() method prints the message "Notification sent" to standard output.

    /**
     * Main method for the event source.
     * 
     * @param args
     *            arguments passed from the command line
     */
    public static void main(String args[]) {
        EventSourceWsn10 source = new EventSourceWsn10();
        try {
            source.sendEvent();
            System.out.println("Notification sent");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Creating and populating the event

The createEvent() method of EventSource.java is a helper method used to create an event and populate it with a minimal set of property data. This method is called by the sendEvent method to create the event that will be sent to the Web Services.

    public static CommonBaseEvent[] createEvents() throws Exception {
        CommonBaseEvent[] events = null;

        String cbeFile = System.getProperty("cbe.file");
        if (cbeFile != null) {
            events = EventFormatter.eventsFromCanonicalXMLDoc(cbeFile);
        } else {
            // The first step is accessing the event factory
            EventFactory eventFactory = EventFactoryFactory.createEventFactory();

            // Creating an event with an extension name.
            CommonBaseEvent event = eventFactory.createCommonBaseEvent("EVENT");
            event.setCreationTimeAsLong(System.currentTimeMillis());

            // Setting the mandatory situation description for the event.
            Situation situation = eventFactory.createSituation();
            situation.setCategoryName(Situation.REPORT_SITUATION_CATEGORY);
            situation.setReportSituation("INTERNAL", "Succeeded");
            event.setSituation(situation);

            // Setting the mandatory component identification for the
            // event source
            event.setSourceComponentId("Event Source",
                "source.EventSource",
                "createEvent()",
                "http://www.ibm.com/namespaces/autonomic/Tivoli/Samples",
                "Sample",
                "unknown",
                "hostname");

            // Setting Common Base Event version
            event.setVersion("1.0.1");
            // Setting optional fields
            event.setSeverity((short) 10);
            event.setMsg("Common Event Infrastructure Tutorial");

            events = new CommonBaseEvent[] { event };
        }

        return events;
    }

The createEvent method performs the following steps:

  1. It uses the createEventFactory() method of the EventFactoryFactory to create a new EventFactory object
  2. It uses the createCommonBaseEvent(String) method of the event factory to create a new event object (an instance of CommonBaseEvent). The specified string ("EVENT") is used to set the extensionName property of the event, and the current system time is used to set the creationTime property.
  3. It sets the value of the situation property of the event. Because situation is a complex property, it is represented by a specialized Java class. Therefore, setting the situation property requires several separate steps:
    1. Creating a new Situation object
    2. Using setter methods to populate the Situation object with required property data
    3. Setting the situation property of the event by calling the Event.setSituation() method, specifying the populated Situation object
  4. It sets the values of several other event properties, some required and some optional. These properties include severity, msg, version, and sourceComponentId.
    Note: Like situation, sourceComponentId is also a complex property. However, its child properties are all simple attributes represented by strings, so you can use the setSourceComponentId() helper method rather than separately instantiating a specialized Java object.

    The other properties set by the example (version, severity, and msg) are all simple properties represented by strings or integers.

  5. Finally, the createEvent() method returns the event, which is now populated with property data.

Creating the notification message

The next method of the event source example, createNotificationMessage(event), is a helper method used to create notification message encapsulating the event passed in as parameter to the method. This method is called by the sendEvent method to create the notification message that will be sent to the Web Services.

    public static NotificationMessageHolderType[] createNotificationMessage(
            CommonBaseEvent events[]) throws Exception {
        NotificationMessageHolderType[] notificationArray = 
            new NotificationMessageHolderType[events.length];
        for (int i = 0; i < events.length; i++) {

            //Creating an instance of NotificationMessageHolderType
            notificationArray[i] = new NotificationMessageHolderType();

            //Creating a Topic element with the name 'Topic'
            SOAPFactory soapFactory = new SOAPFactory();
            SOAPElement topicSE = (SOAPElement) 
                soapFactory.createElement("Topic");
            SOAPElement topicSEChild = (SOAPElement)
                topicSE.addChildElement("Topic");
            topicSEChild.setAttribute("dialect","none");
            notificationArray[i].setTopic(topicSE);

            //Setting the event to be the message of the notification
            SOAPElement messageSE = (SOAPElement) 
                soapFactory.createElement("Message");
            messageSE.addNamespaceDeclaration("ns2",
                "http://www.ibm.com/AC/commonbaseevent1_0_1");
            messageSE.addAttribute("http://www.w3.org/2001/XMLSchema-instance",
                "type",
                "ns2:CommonBaseEvent");
            String cbeStr = EventFormatter.toCanonicalXMLString(events[i]);
            SOAPElement cbeSE = (SOAPElement) 
                soapFactory.createElementFromXMLString(cbeStr);
            messageSE.addChildElement(cbeSE);
            notificationArray[i].setMessage(messageSE);

            //Setting information about the producer of the event in
            //the notification
            SOAPElement producerSE = (SOAPElement) 
                soapFactory.createElement("ProducerReference");
            SOAPElement producerSEChild = (SOAPElement) 
                soapFactory.createElement("Address",
                "ns1",
                "http://schemas.xmlsoap.org/ws/2003/03/addressing");
            producerSEChild.addTextNode("protocol://your.event.source.address");
            producerSE.addChildElement(producerSEChild);
            notificationArray[i].setProducerReference(producerSE);
        }
        return notificationArray;
    }

The createNotificationMessage(event) performs the following steps:

  1. It creates a NotificationMessageHolderType object which holds information of the notification to be sent.
  2. The Topic element of the notification is created with name 'Topic'. A nested child element is added to show that everything inside of the Topic element will be ignored when the notification is received.
  3. The message of the notification is set to be the event passed into the method.
  4. The information about the producer of the event is set in the notification.
  5. The notification message, thus created and populated with information is returned to the caller.

Sending event

The last method of the event source example, sendEvent(), contains the main program logic. This method handles all interaction with the NotificationConsumer client, including sending the event.

    private void sendEvent() throws Exception {
        //The first step is creating an event
        CommonBaseEvent[] events = createEvents();

        //Creating the Notification message encapsulating the event
        NotificationMessageHolderType[] notification = 
            createNotificationMessage(events);

        //Obtaining the address of the NotificationConsumerService webservice
        String endpoint = System.getProperty("service.address");
        if (endpoint == null) {
            // If no address was specified, the webservice is assumed to be
            // runnning in the localhost at port 9080 for was
            endpoint = "http://localhost:9080/wsnt-was/services/NotificationConsumer10Soap";
        }

        //Creating an URL object for the address obtained
        java.net.URL serviceURL = new URL(endpoint);

        //Creating an instance of NotificationConsumerServiceLocator
        NotificationConsumerService notifierSvc = 
            new NotificationConsumerServiceLocator();
        NotificationConsumer notifier = 
            notifierSvc.getNotificationConsumer10Soap(serviceURL);

        //Sending the notification
        notifier.notify(notification);

    }

The sendEvent() method performs the following steps:

  1. It calls the createEvent() helper method to create and populate a new event.
  2. It calls the createNotificationMessage(event) helper method to create a notification message encapsulating the event created.
  3. From the system property, it obtains the address of the NotificationConsumer Web Services, servicing the notification request.
  4. It instantiates the NotificationConsumerServiceLocator, which is then used to obtain a NotificationConsumer object
  5. It sends the event by invoking the notify() method of the NotificationConsumer. This generates a SOAP message encapsulating the event


Related topics
Building the samples
Running the samples


Related concepts
Converting an event in the Common Base Event format to Enterprise Console event format