C Java interfacing library

The Java interfacing library models the C library functions for configured C modulesusing JNA. Each method corresponds to one function in the C library.

Overview

Each function which corresponds to a service invocation (output) or a service notification (input) for the C module corresponds to one method in the interface.

Declaration type for a service

For each service which is invoked by the C library or notified to the library, you must add the corresponding method in the interfacing library. The signature of the method corresponds to the signature of the C function.

You must also for each of this service add a SignatureTag annotation which will specify:

• The service name (and optionnaly URI)
• The interface type, which can be:
• SignatureType.NOTIFICATION for a service which is notified through the function
• SignatureType.INVOCATION for a service which is invoked through the function
• SignatureType.REQUEST for the invocation of a request-response Service request through the function
• SignatureType.RESPONSE for the notification of a response of a request-response Service through the function
• SignatureType.CYCLIC_SERVICE for a service which is invoked cyclically through the function

The table of correspondance for the interfaces is the following:

Signature	Type	Interface	Service
SignatureType.NOTIFICATION	notification	subscribe eventReceived listen[1] It is possible to listen to a request-response Service	publish Service event Service
SignatureType.INVOCATION	invocation	push eventSend	publish Service event Service
SignatureType.CYCLIC_SERVICE	invocation	cyclic cyclicEvent	publish Service event Service
SignatureType.REQUEST	invocation	requestSend[2] This corresponds to the request datas for a subscriber of the service	request-response Service
SignatureType.RESPONSE	notification	requestSend[3] This corresponds to the response datas for a subscriber of the service	request-response Service

Notifications

For a service which corresponds to a notification, the Java code will call the associated function when the C module is notified.

For example here we have a service named "event" which is notified to the C module:

      public interface CLibrary extends Library {      
        @SignatureTag(type=SignatureType.NOTIFICATION, name="event")
        public void receive(boolean state);
      }      

Here we have a service named "http://my.namespace:event"^[4]

the service use a namespace in this case

which is notified to the C module:

      public interface CLibrary extends Library {      
        @SignatureTag(type=SignatureType.NOTIFICATION, name="event", uri="http://my.namespace")
        public void receive(boolean state);
      }      

Invocations

A function which corresponds to an invocation to the C module define the callback which will be used by the framework to call the associated Java code.

For example here we have a service named "published" which is invoked by the C module:

      public interface CLibrary extends Library {      
        @SignatureTag(type=SignatureType.INVOCATION, name="published")
        public void setInvoker(Invoker callback);

        public interface Invoker extends Callback {
          void invoke(int value);
        }
      }      

At initialization the framework will call the setInvoker function, which will give to the C library the pointer to the function to call.

When the C library wants to invoke the "published" service, it just have to call the function which was given in the callback.

Example

For example the following declaration corresponds to the interface with a C module implementing the PublishModule in the first tutorial:

      public interface CLibrary extends Library {      
        @SignatureTag(type=SignatureType.NOTIFICATION, name="event")
        public void receive(boolean state);
   
        @SignatureTag(type=SignatureType.CYCLIC_SERVICE, name="published")
        public void publish();   
   
        @SignatureTag(type=SignatureType.INVOCATION, name="published")
        public void setInvoker(Invoker callback);

        public interface Invoker extends Callback {
          void invoke(int value);
        }
      }