Java modules service interface

This article explains how to interface with services in the Java modules implementation.

Entry points

Being notified from a Service is performed through an entry point method which is called by the framework. The method will be called each time the module is notified from the reception of the Service.

For example, in the following case, the receive(ServiceInstance service) method will be called each time the module is notified from the position service:

      <applications>
         <application name="application">
            <modules>
               <module name="FMS" >
                  <implementation path="org.da.aircraft.Aircraft" >
                     <initEntryPoint method="init" />
                     <defaultSendEntryPoint method="send" />
                  </implementation>
                  <interfaces>
                     <subscribe service="position" />
                  </interfaces>
               </module>
            </modules>
         </application>
      </applications>

Calling cyclically a publish Service

If a publish Service is called cyclically by the framework, the service entry point will be called each time the service is automatically invoked by the framework.

For example, in the following case, the sendServiceInstance service) method will be called each time the position service is automatically invoked:

      <applications>
         <application name="application">
            <modules>
               <module name="Aircraft" >
                  <implementation path="org.da.aircraft.Aircraft" >
                     <initEntryPoint method="init" />
                     <defaultSendEntryPoint method="send" />
                  </implementation>
                  <interfaces>
                     <cyclic service="position" frequency="200ms "/>
                  </interfaces>
               </module>
            </modules>
         </application>
      </applications>

Calling cyclically an event Service

If a event Service is called cyclically by the framework, the service entry point will be called each time the service is automatically invoked by the framework.

For example, in the following case, the sendServiceInstance service) method will be called each time the tick service is automatically invoked:

      <applications>
         <application name="application">
            <modules>
               <module name="Aircraft" >
                  <implementation path="org.da.aircraft.Aircraft" >
                     <initEntryPoint method="init" />
                     <defaultSendEntryPoint method="send" />
                  </implementation>
                  <interfaces>
                     <cyclicEvent service="tick" frequency="1s "/>
                  </interfaces>
               </module>
            </modules>
         </application>
      </applications>

Getting a specific service

If you defined an entry point for several services, sevberal methods can be used to check the service identification:

• The ServiceInstance.getName() allows to check the Service name^[1]
  Beware that it does not take into account the Service namespace if the Service is defined in a namespace
• The ServiceInstance.getKey() allows to check the Service complete identification, which is especially useful if if the Service is defined in a namespace

For example, when taking into account only the Service name:

      public void subscribe(ServiceInstance<?, ?> service) {
        if (service.getName().equals("myService") {
        ...
        }
      }

An when taking into account the full service identification:

      public void subscribe(ServiceInstance<?, ?> service) {
        NamespaceKey key = NamespaceKey.createKey("http://my.uri", "myService");
        if (service.getKey().equals(key) {
        ...
        }
      }

Make a copy of a service

In some cases, you want to prepare the values of datas for a service in several different contexts, and send one or the other set of values depending on the context.

The ServiceInstance.createCopy() method allows to create copies of publsh or event services. The ServiceInstance.invoke() method for the copy will work exactly as the invoke method in the original service, except that the current values of the copied service will be used for the Datas.

This allows to keep several independent set of datas for a service and set the one you need at will.

Getting the time stamp of a service

For every service, it is possible to get the time stamp of the Service in java.time.Duration in milliseconds (as for the System.currentTimeMillis()) by calling the ServiceInstance.getTimeStamp() method. This value is the exact time when the service was invoked.

Getting the elapsed time for a service since the start of the framework

For every service, it is possible to get the elapsed time of the Service in milliseconds since the start of the framework by calling the ServiceInstance.getElapsedTime() method.

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. This can be the case if the module is both a provider and a subscriber of the service, and if it invoked this service.

Getting a data

Getting a Data for a Service is performed through the ServiceInstance.getData(String) method.

Getting the value of a data

The Data class has several methods allowing to get the value of the data as various types^[2]

Note that the framework will try to perform the transtyping of the data when possible

.

For example, getting the value of the "latitude" data as a float:

      public void receive(ServiceInstance service) {
        Data latitude = service.getData("latitude");
        float lat = data.getValueAsFloat();
      }

Knowing if the value of a Data has changed

The framework indicates if a state value has been modified since the last notification. To know if the value of a data has changed since the last notification, you can use the ServiceInstance.hasChanged(String) method.

Knowing if the content of a Service has changed

To know if the content of a Service has changed since the last notification, you can use the ServiceInstance.hasChanged() method. it means that the value of at least one of the datas of this Service has changed.

Setting the value of a data

The Data class has several methods allowing to set the value of the data as various types^[2]

Note that the framework will try to perform the transtyping of the data when possible

.

For example, setting the value of the "latitude" data as a float:

      public void send(ServiceInstance service) {
        Data latitude = service.getData("latitude");
        data.setValueAsFloat(0.25f);
      }

Case of objectType datas

Handling objectType datas is not different from handling any other datas types.

For example, if we have the "data" data of the "obj" type:

      <types>
         <objectType name="obj" class="my.package.MyClass" />
      </types>

The following code will retrieve the data associated value:

      public void received(ServiceInstance service) {
        Data data = service.getData("data");
        MyClass instance = (MyClass)data.getValue();
      }

Invoking a Service

Invoking a Service is performed through the ServiceInstance.invoke() method.

For example:

      public void send(ServiceInstance service) {
        Data latitude = service.getData("latitude");
        data.setValueAsFloat(0.25f);
        service.invoke();
      }

Getting the processing time for request/response services

It is possible to get the time used to process a request-response Service by the service provider by using the RequestServiceInstance.getProcessingDuration() or RequestServiceInstance.getProcessingDuration(long) method.

• The getProcessingDuration() method return the duration for the last response
• The getProcessingDuration(long requestID) method return the duration for the reponse corresponding to a specified request ID

In the case where the request ID is not found, the method will return -1.