Service implementation

Declaring the Services interface

The declaration of the Service interface is performed in the Module configuration:

• The module declares for which services it interfaces to
• For each Service it interfaces to, it specifies if it is a provider or a subscriber of this Service
• Several properties can be defined depending on the Service type

The declaration for the interfaces for a module is specified through the interfaces element. For example:

      <module name="FlightManagementSystem">
         <interfaces>
            <subscribe service="position" />
            <eventReceived service="directTo"/>
         </interfaces>
      </module>

Services interfaces types

There are two kinds of Services interface for a Module:

• Services for which the Module is a provider
• Services for which the Module is a subscriber

Interfacing with services which have a namespace

To interface with services which have a namespace, you just have to add the namespace uri to the declaration. For example:

      <module name="FlightManagementSystem" id="1" >
         <interfaces>
            <subscribe service="position" uri="http://mydomain.com/aircraft" />
            <eventReceived service="directTo"/>
            <requestReceived service="computeFlightPlan"/>
         </interfaces>
      </module>

Publish Services

A Module can declare itself as:

• Publishing the Service on demand: the Module provides the Service, and the Service is invoked on a explicit order from the Module. For example: <publish service="position" />
• Publishing the Service cyclically: the Module provides the Service, and the Service is invoked cyclically. For example: <cyclic service="position" frequency="100ms" />
• Subscribing to the Service: the Module is notified to the Service invocation. For example: <subscribe service="position" />
• Listening to the Service: the Module is notified to the Service invocation. For example: <listen service="position" />. See also listening to a Service
• Listening to all Services: the Module is notified to all Services invocation in the framework. For example: <listenAll />. See also listening to all Services.

Note that it is allowed and it is not an error for a Module to be both a provider and subscriver of a Service. See being a Module which is both a provider and a subscriber of a Service for more information.

Cyclic publication

For a Service which is published cyclically, you don't need by default to call explicitly the ServiceInstance.invoke() method, the invocation will automatically be performed after the entry point has been executed.

You can configure the cyclic interface not to call the invocation automatically by setting the autoInvoke attribute to false:

         <interfaces>
            <cyclic service="myService" autoInvoke="false" frequency="100ms" />
         </interfaces>

In that case the invoke() will have to be called in the method.

Cyclic publication activation

You can configure the cyclic interface not to be activated at start by setting the activated attribute to false:

         <interfaces>
            <cyclic service="myService" activated="false" frequency="100ms" />
         </interfaces>

It is possible to activate or deactivate the cyclic invocation of the service by using the PublishCyclicServiceInstance.setActivated(boolean) method

Cyclic publication example

      <module name="MyModule" >
         <implementation path="org.PublishModule" >
            <initEntryPoint method="init" />
            <defaultSendEntryPoint method="publish" />
         </implementation>
         <interfaces>
            <cyclic service="myService" frequency="100ms" />
         </interfaces>
      </module>

and:

      <services>
         <publish name="myService">
            <data name="value" type="int" />
         </publish>
      </services>

We can have the following code for the publish method:

      public class PublishModule {
        private int count = 0;

        public void init(Module module) {
        }

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

Event Services

A Module can declare itself as:

• Publishing the event Service: the Module provides the Service, and the Service is invoked on an explicit order from the Module. For example: <eventSend service="position" />
• Subscribing to the Service: the Module is notified to the Service invocation. For example:<eventReceived service="position" />
• Listening to the Service: the Module is notified to the Service invocation. For example: <listen service="position" />. See also listening to a Service
• Listening to all Services: the Module is notified to all Services invocation in the framework. For example: <listenAll />. See also listening to all Services.

Event Services publisher configuration

By default a Module which publish an event service will keep the values of all the Service datas to their value after invoking the Service. However it is possible to reset the values to their default values by setting the resetAfterSend attribute. For example:

       <eventSend service="position" resetAfterSend="true" />

Cyclic events

For an event Service which is published cyclically, you don't need by default to call explicitly the ServiceInstance.invoke() method, the invocation will automatically be performed after the entry point has been executed.

However, you can configure the cyclicEvent interface not to call the invocation by setting the autoInvoke attribute to false:

         <interfaces>
            <cyclicEvent service="tick" autoInvoke="false" frequency="1s" />
         </interfaces>

Cyclic publication activation

You can configure the cyclicEvent interface not to be activated at start by setting the activated attribute to false:

         <interfaces>
            <cyclicEvent service="myService" activated="false" frequency="100ms" />
         </interfaces>

It is possible to activate or deactivate the cyclic invocation of the service by using the SendEventCyclicServiceInstance.setActivated(boolean) method

Cyclic events example

      <module name="MyModule" >
         <implementation path="org.PublishModule" >
            <initEntryPoint method="init" />
            <defaultSendEntryPoint method="publish" />
         </implementation>
         <interfaces>
            <cyclicEvent service="tick" frequency="1s" />
         </interfaces>
      </module>

and:

      <services>
         <event name="tick">
            <data name="time" type="int" />
         </event>
      </services>

We can have the following code for the publish method:

      public class PublishModule {
        private int time = 0;

        public void init(Module module) {
        }

        public void publish(ServiceInstance service) {
          publishService.setDataIntValue("time", count);
          time++;
        }
      }

Request-response Services

A Module can declare itself as:

• Publishing the Service: the Module provides the Service. It is notified of requests, and will be invoked for the response on a explicit order from the Module to return the response. For example: <requestSend service="position" />
• Subscribing to the Service: the Module can invoke the Service for the the request, and is notified of the response. For example:<requestReceived service="position" />
• Listening to the Service: the Module is notified to the Service invocation. For example: <listen service="position" />. See also listening to a Service
• Listening to all Services: the Module is notified to all Services invocation in the framework. For example: <listenAll />. See also listening to all Services.

Request-response Services subscriber configuration

The timeOut attribute specified how long (in ms) the subscriber must wait before the response is declared as timed out. The default value is 300ms. For example:

       <requestSend service="position" timeOut="500ms" />

A value of "none" for the timeOut attribute specifies that there is no timeOut specified for the request, which means that the response will never *be decklared as time out regardless of the time used by the perovider to return the response.

Blocking invocation

The RequestServiceInstance.invokeBlocking() method allows to send a request and wait in the sender thread until the response has been received or the timeout has elapsed. For example:

      requestService.invokeBlocking();
      Data<?> data = requestService.getData("result");
      ...

Listening to a Service

You might think that declaring that a module is listening to a Service is identical that declaring that this module is subscribing to the Service, but its not:

Declaring that a Module is listening to a Service means that the Module will receive every notification from the Service invocations, which means that:

• For a publish Service: it's identical to declaring that the module is subscribing to the Service
• For a event Service: it's identical to declaring that the module is subscribing to the Service
• For a request-response Service: the module will be notified from the request and the response, and it can not send any request

For example, in the following example, the "debugModule" will be notified from both the request and the response from the computeFlightPlan Service:

      <applications>
         <application name="aircraft" id="1">
            <modules>
               <module name="Display" id="1" >
                  <interfaces>
                     <requestSend service="computeFlightPlan"/>
                  </interfaces>
               </module>
               <module name="FlightManagementSystem" id="2" >
                  <interfaces>
                     <requestReceived service="computeFlightPlan"/>
                  </interfaces>
               </module>
               <module name="debugModule" id="2" >
                  <interfaces>
                     <listen service="computeFlightPlan"/>
                  </interfaces>
               </module>
            </modules>
         </application>
      </applications>

Listening to all Services

Sililarly to the listen element which declares that the module is listening to a particular service, the listenAll element declares that the module is listening to all services defined for the framework.

For example, in the following example, the "debugModule" will be notified from all services in the framework:

      <applications>
         <application name="aircraft" >
            <modules>
               <module name="debugModule"  >
                  <interfaces>
                     <listenAll/>
                  </interfaces>
               </module>
            </modules>
      ...
         </application>
      </applications>

Being both a provider and a subscriber of a Service

It is allowed and it is not an error for a Module to be both a provider and subscriver of a Service. For example, the following declaration is valid:

      <applications>
         <application name="application" id="1">
            <modules>
               <module name="myModule" id="1" >
                  <interfaces>
                     <publish service="publish" />
                     <subscribe service="publish" />
                  </interfaces>
               </module>
         </application>
      </applications>

In this example, the module will be notified of its own invocation of the publish service.

Service interfaces correspondance

Attaching the Service

To be able to invoke a Service, a module must be declared as a provider to this Service, but it must also be attached to the Service.

• By default if a Service has only one module provider, the framework will attach this module to the Service
• If a Service has more than one provider, the framework will not attach by default any provider to this service. To attach one or more providers to the Service, you must declare the attached services explicitely with the attach attribute

Declaring specific service entry points

For each service, it is possible to declare specific entry-points which will be used for the Service rather than the default entry points declared globally for the Module.

For example:

• The default receive entryPoint, with the receive(ServiceInstance service) signature is used for the "directTo" service notification
• The receivePosition entryPoint, with the receivePosition(ServiceInstance service) signature is used for the "position" service notification
• The receiveRequest entryPoint, with the receiveRequest(ServiceInstance service) signature is used when receiving the "computeFlightPlan" service request

      <module name="FlightManagementSystem" id="1" >
         <implementation path="org.da.aircraft.fms.FMS" >
            <initEntryPoint method="init" />
            <startEntryPoint method="start" />
            <defaultReceiveEntryPoint method="receive" />
         </implementation>
         <interfaces>
            <subscribe service="position" >
              <entryPoint="receivePosition"/>
            </subscribe>
            <eventReceived service="directTo"/>
            <requestReceived service="computeFlightPlan" >
              <entryPoint="receiveRequest"/>
            </requestReceived>
         </interfaces>
      </module>

Declaring specific service trigger entry points

It is possible to specify a spcific method for an event service which is triggering another one with the triggerEntryPoint element. For example:

      <module name="module1">
         ...
         <interfaces>
            <eventReceived service="service1" >
               <triggerEntryPoint method="trigger" />
            </eventReceived>
            <eventSend service="service2" />
         </interfaces>
      </module>

The signature of this method must be: <method_name>(ServiceInstance service, ServiceInstance service). The method will be called after the notification if the service is triggering another one. The first argument is the triggering service (which must be a subscribed event service), the second is the triggered service (which must be a provided event service).

Python http modules service interfaces options

Python http modules have specific options for the service interfaces declaration, allowing to block the Python script on specific services receptions.

Invoking the service

The method ServiceInstance.invoke() allow to invoke a Service in a Module which is a provider of this Service. Note that this method will only have an effect after the start of the Framework.

For example:

      eventService = module.getService("event");
      eventService.setDataBooleanValue("event", true);
      eventService.invoke();

The method will return true if the invocation has been successful, and false in the following cases:

• The Module which invokes the Service is not a provider of this Service
• The Module which invokes the Service is not attached to the Service
• The Module has invoked the Service before the start of the Framework

Being notified of a Service

Depending on the entryPoint defined for a Service subscriber, the associated method will be called upon notification of this Service.

For example:

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

Detecting if a module has been notified from the service of has invoked the service

• It is possible for a module to detect if it has been notified from a service a least once by using the ServiceInstance.isNotified() method. Note that if the module is not a subscriber of the service, if will always return false. This method will return true just before the module is invoked for the first time for the service
• It is also possible for a module to detect if it has invoked service a least once by using the ServiceInstance.isInvoked() method. note that if the module is not a provider of the service, it will always return false. This method will return true just after the service has been invoked for the first time by the module

For example:

      public class MyModule {
        private ServiceInstance initService = null;

        public void init(Module module) {
          initService = module.getService("initService");
        }

        public void subscribe(ServiceInstance service) {
          if (initService.isNotified()) {
            // do something
          }
        }
      }

Detecting if a service was invoked by the notified module

It is possible for a module to detect that it was this module which invoked the service itself, by using the ServiceInstance.invokedByMe() method. This can be the case if the module is both a provider and a subscriber of the service, and if it invoked this service.

For example, suppose the following architecture:

      <module name="MyModule" >
         <implementation path="org.da.MyModule" >
            <initEntryPoint method="init" />
            <initEntryPoint method="start" />
            <defaultReceiveEntryPoint method="receive" />
         </implementation>
         <interfaces>
            <eventSend service="sendEvent" />
            <eventReceived service="sendEvent"/>
         </interfaces>
      </module>

and the following code for this module. In this case the module invoke the sendEvent service at start, and it is also notified from this service:

      public class MyModule {
        private ServiceInstance sendEventService = null;

        public void init(Module module) {
          sendEventService = module.getService("sendEvent");
        }

        public void start() {
          sendEventService.invoke();
        }

        public void subscribe(ServiceInstance service) {
          if (service.invokedByMe()) {
            System.out.println("The MyModule module invoked the sendEvent service");
          }
        }
      }