First tutorial

The first tutorial present the coding and configuration of a very simple system with two modules.

Overview

Suppose that we want to specify two modules:

• One module increments or decrements a value cyclically
• Another module allows to click on a toggle to set if the first module should increment or decrement the value. It also shows the value

Netbeans configuration

To be able to develop your module, you will need to settup a netbeans environment. Go to Netbeans configuration for an explanation of how to do it.

Architecture

We will define two services:

• One Service will publish the value
• Another Service will publish the state of the toggle button in case of a click event

And two applications:

• The first PublishModule will not have any graphical interface and will:
• Increment or decrement the value
• Publish cyclically the value
• Listen to the toggle event to set if the value should increment or decrement
• The second EventModule will have a graphical interface and will:
• Subscribe to the published value and show this value
• Show a toggle and sends an event when the user clicks on this toggle

XML configuration

Services definition

We define our two services in a services.xml XML file:

• The event service carries the state of the toggle button. It is an event Service because the service should only be invoked when the state of the toggle button changes
• The published service carries the value. It is a publish Service because the service should be invoked cyclically

      <services>
         <event name="event" >
            <data name="event" type="bool" />
         </event>
         <publish name="published" >
            <data name="value" type="int" />
         </publish>
      </services>

Types definition

These two services use a very simple types definition. There are only two types:

• The bool type is a boolean
• The int type is an int

We define these types in a types.xml XML file:

      <types>
         <simpleType name="bool" baseType="boolean" />
         <simpleType name="int" baseType="int" />
      </types>

Applications definition

We define our two applications in an applications.xml XML file:

• The eventAppli only contains the EventModule. This Module:
• sends the event service
• subscribes to the published service
• The publishAppli only contains the PublishModule. This Module:
• sends cyclically the published service
• subscribes to the event service

         <applications>
            <application name="eventAppli" >
               <modules>
                  <module name="EventModule" >
                     <interfaces>
                        <eventSend service="event" attach="attach"/>
                        <subscribe service="published" />
                     </interfaces>
                  </module>
               </modules>
            </application>
            <application name="publishAppli" >
               <modules>
                  <module name="PublishModule" >
                     <interfaces>
                        <eventReceived service="event"/>
                        <cyclic service="published" frequency="200ms" attach="attach"/>
                     </interfaces>
                  </module>
               </modules>
            </application>
         </applications>

For now we did not bridge our services to any implementation for our two applications. This will be done in the next step.

Code the applications

Code the PublishModule

The PublishModule:

• sends cyclically the published service
• subscribes to the event service

We don't have to bother about how to send cyclically the value, because we already specified that we wanted the published service to be invoked cyclically every 200 milliseconds in the module XML specification:

     <cyclic service="published" frequency="200ms" attach="attach"/>

We will create a PublishModule class to implement the behavior of this Module:

• a subscribe method will be notified of the event Service. Depending on the value of the event data, a step variable will have a 1 or -1 value
• a publish method will be invoked cyclically for the published Service. The current value will be incremented or decremented, and the Service will be notified with this current value

      public class PublishModule {
        private ServiceInstance eventService = null;
        private ServiceInstance publishService = null;
        private int count = 1;
        private int step = 1;

        public void init(Module module) {
          eventService = module.getService("event");
          publishService = module.getService("published");
        }

        public void subscribe(ServiceInstance service) {
          boolean evt = eventService.getData("event").getValueAsBoolean();
          if (evt) {
            step = -1;
          } else {
            step = 1;
          }
        }

        public void publish(ServiceInstance service) {
          publishService.setDataIntValue("value", count);
          count += step;
          publishService.invoke();
        }
      }

Specify the bridge between the PublishModule and its implementation

Now that we have coded the PublishModule, we must specify in the applications.xml XML file the bridge between this module and its implementation:

• The jar file which contains the publishAppli
• The Java class which implements the PublishModule

      <application name="publishAppli" >
         <deployment>
            <lib url="samples1Publish.jar" />
         </deployment>
         <modules>
            <module name="PublishModule" >
               <implementation path="org.da.samples.protoframework.publish.PublishModule" >
      ...
               </implementation>
            </module>
         </modules>
      </application>

We must also specify:

• That the init method will be called at the initialization of the Module
• That the subscribe method will be called each time the Module is notified from the event Service
• That the publish method will be called cyclically for the published Service

      <implementation path="org.da.samples.protoframework.publish.PublishModule" >
         <initEntryPoint method="init" />
         <defaultReceiveEntryPoint method="subscribe" />
         <defaultSendEntryPoint method="publish" />
      </implementation>

Code the EventModule

The EventModule:

• sends the event service
• subscribes to the published service

We will create an EventModule class to implement the behavior of this Module. The graphical representation will be in a separate subclass of JFrame to show the toggle button and the label showing the current value:

• a subscribe method will be notified of the published Service. The value will set the text of the label
• a publish method will be invoked when the user clicks on the toggle button, to send the for the event Service

      public class EventModule {
        private ServiceInstance eventService = null;
        private ServiceInstance publishService = null;
        private EventGUI gui = null;

        public void init(Module module) {
          eventService = module.getService("event");
          publishService = module.getService("published");
          gui = new EventGUI(this);
          gui.setup();
          gui.pack();
          gui.setVisible(true);
        }

        public void subscribe(ServiceInstance service) {
          int count = publishService.getData("value").getValueAsInt();
          gui.updateCount(count);
        }

        public void publish(boolean b) {
          eventService.setDataBooleanValue("event", b);
          eventService.invoke();
        }
      }

The associated GUI class has nothing specific to the framework:

      public class EventGUI extends JFrame {
        private JToggleButton button = null;
        private JLabel label = null;
        private EventModule module = null;

        public EventGUI(EventModule module) {
          super("Event GUI");
          this.module = module;
        }

        public void updateCount(int count) {
          label.setText(Integer.toString(count));
          label.invalidate();
          label.repaint();
        }

        public void setup() {
          Container pane = this.getContentPane();
          pane.setLayout(new BoxLayout(pane, BoxLayout.X_AXIS));
          button = new JToggleButton("Positive Step");
          label = new JLabel("0");
          label.setHorizontalAlignment(JLabel.CENTER);
          pane.add(button);
          pane.add(Box.createHorizontalStrut(50));
          pane.add(label);
          pane.add(Box.createHorizontalStrut(50));
          button.addActionListener(new ActionListener() {
          @Override
          public void actionPerformed(ActionEvent e) {
            if (button.isSelected()) {
              button.setText("Negative Step");
            } else {
              button.setText("Positive Step");
            }
            module.publish(button.isSelected());
          }
          });
        }
      }

Specify the bridge between the EventModule and its implementation

Now that we have coded the EventModule, we must specify in the applications.xml XML file the bridge between this module and its implementation:

• The jar file which contains the eventAppli
• The Java class which implements the EventModule

      <application name="eventAppli">
         <deployment>
            <lib url="samplesEvent.jar" />
         </deployment>
         <modules>
            <module name="EventModule" >
               <implementation path="org.da.samples.protoframework.event.EventModule" >
      ...
               </implementation>
            </module>
         </modules>
      </application>

We must also specify:

• That the init method will be called at the initialization of the Module
• That the subscribe method will be called each time the Module is notified from the published Service

      <implementation path="org.da.samples.protoframework.publish.PublishModule" >
         <initEntryPoint method="init" />
         <defaultReceiveEntryPoint method="subscribe" />
      </implementation>

Finalize the XML configuration

We now have a final applications.xml XML file:

      <applications>
         <application name="eventAppli" >
            <deployment>
               <lib url="samplesEvent.jar" />
            </deployment>
            <modules>
               <module name="EventModule" >
                  <implementation path="org.da.samples.protoframework.event.EventModule" >
                     <initEntryPoint method="init" />
                     <defaultReceiveEntryPoint method="subscribe" />
                  </implementation>
                  <interfaces>
                     <eventSend service="event" attach="attach"/>
                     <subscribe service="published" />
                  </interfaces>
               </module>
            </modules>
         </application>
         <application name="publishAppli" >
            <deployment>
               <lib url="samplesPublish.jar" />
            </deployment>
            <modules>
               <module name="PublishModule" >
                  <implementation path="org.da.samples.protoframework.publish.PublishModule" >
                     <initEntryPoint method="init" />
                     <defaultReceiveEntryPoint method="subscribe" />
                     <defaultSendEntryPoint method="publish" />
                  </implementation>
                  <interfaces>
                     <eventReceived service="event"/>
                     <cyclic service="published" frequency="200ms" attach="attach"/>
                  </interfaces>
               </module>
            </modules>
         </application>
      </applications>

In the last step, we will specify the filelist configuration of the system, including:

• The types.xml definition
• The services.xml definition
• The applications.xml definition

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
      </files>

Starting the framework

To start the framework, we must start the framework with our filelist.xml file for our configuration:

      java -jar protoframework.jar config=filelist.xml