Welcome to FIWARE Advanced Middleware KIARA documentation!¶

Gradle¶

Gradle is the newest and most flexible build tool for Java. It provides every good and detailed documentation and tutorials to get developers started. Official installation instructions are here.

The official way to install Gradle is to download and unpack the binary ZIP file to a common directory, set the environment variable GRADLE_HOME and add the bin directory to your PATH environment variable.

unzip ~\Download\gradle-x.x.x-all.zip -d "C:\Program Files"
setx GRADLE_HOME "C:\Program Files\gradle-x.x.x" /M
setx PATH "%PATH%;%GRADLE_HOME%\bin" /M

$ sudo unzip ~/gradle-x.x.x-all.zip -d /usr/share/
$ sudo ln -s /usr/share/gradle-x.x.x /usr/share/gradle

export GRADLE_HOME=/usr/share/gradle
export PATH=$PATH:$GRADLE_HOME/bin

$ curl -s get.gvmtool.net | bash
... follow instructions
$ gvm install gradle

$ gradle -v
------------------------------------------------------------
Gradle 2.2.1
------------------------------------------------------------

Build time:   2014-11-24 09:45:35 UTC
Build number: none
Revision:     6fcb59c06f43a4e6b1bcb401f7686a8601a1fb4a

Groovy:       2.3.6
Ant:          Apache Ant(TM) version 1.9.3 compiled on December 23 2013
JVM:          1.7.0_65 (Oracle Corporation 24.65-b04)
OS:           Linux 3.13.0-34-generic amd64

Apache Maven¶

Apache Maven is a very common build tool in the Java/JVM world and is very well known for its dependency management and its central artifact repository (mavencentral). Find the documentation and tutorials on the main page. Installation instructions and downloads are here.

The official way to install Maven is to download and unpack the binary ZIP file to a common directory, set the environment variable M2_HOME and add the bin directory to your PATH environment variable.

$ sudo unzip ~/apache-maven-x.x.x-bin.zip -d /usr/share/
$ sudo ln -s apache-maven-x.x.x /usr/share/maven

export M2_HOME=/usr/share/maven
export PATH=$PATH:$M2_HOME/bin

$ mvn -version
Apache Maven 3.2.3 (33f8c3e1027c3ddde99d3cdebad2656a31e8fdf4; 2014-08-11T22:58:10+02:00)
Maven home: /usr/local/Cellar/maven/3.2.3/libexec
Java version: 1.8.0_20, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_20.jdk/Contents/Home/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "10.10.2", arch: "x86_64", family: "mac"

Integraded Development Environments (IDE)¶

To install your IDE please check the webpage of your prefered IDE product:

• Eclipse
• IntelliJ IDEA
• Netbeans

These IDEs typically integrate well with Gradle and Apache Maven using plugins. Alternatively you have to copy the KIARA libraries manually to the library folder of your project and add them to your classpath.

Installation of the kiaragen tool¶

The kiaragen tool is part of the KIARA components available on Maven Central. Depending on your build tool kiaragen can be easily integrated or it can be called with a shell/batch script.

If you are using Maven or an IDE you can download an executable jar file of kiaragen from the ga|1|g:org.fiware.kiara|KIARA Maven-Central repository, or you can find it in a standalone distribution available online.

Gradle¶

$ mkdir calculator
$ cd calculator
$ gradle init --type java-library

apply plugin: 'java'

sourceCompatibility = 1.7
version = '1.0'

// In this section you declare where to find the dependencies of your project
repositories {
  mavenCentral()
}

// In this section declare the dependencies for your production and test code
dependencies {
    compile group: 'org.fiware.kiara', name: 'kiara', version: '0.2.0'
    compile group: 'org.slf4j', name: 'slf4j-api', version: '1.7.7'
    testCompile group: 'junit', name: 'junit', version: '4.11'
}

.
├── build                                       // generated files
│   ├── classes                                 // compiled classes
│   │   └── main
│   │       └── com
│   │           └── example
│   │               ├── Calculator.class
│   │               ├── CalculatorAsync.class
│   │               ├── CalculatorClient.class
│   │               ├── CalculatorProcess.class
│   │               ├── CalculatorProxy.class
│   │               ├── CalculatorServant.class
│   │               ├── CalculatorServantExample.class
│   │               ├── ClientExample.class
│   │               ├── IDLText.class
│   │               └── ServerExample.class
│   ├── generated-src                           // generated support classes
│   │   └── kiara
│   │       └── com
│   │           └── example
│   │               ├── Calculator.java
│   │               ├── CalculatorAsync.java
│   │               ├── CalculatorClient.java
│   │               ├── CalculatorProcess.java
│   │               ├── CalculatorProxy.java
│   │               └── CalculatorServant.java
│   └── libs
│       └── Calculator-1.0.jar                 // packaged application
├── build.gradle                               // gradle build file
├── gradle
│   └── wrapper                                // gradle wrapper files
│       └── ...
├── gradlew                                    // gradle wrapper unix script
├── gradlew.bat                                // gradle wrapper windows script
├── settings.gradle
└── src                                        // source files
    ├── main
    │   ├── idl                                // IDL definitions for KIARA
    │   │   └── com
    │   │       └── example
    │   │           └── Calculator.idl
    │   └── java                               // application code
    │       └── com
    │           └── example
    │               ├── ClientExample.java               // client start code
    │               ├── ServerExample.java               // server start code
    │               └── CalculatorServantExample.java    // servant impl.
    └── test
        └── java

Apache Maven¶

$ mvn archetype:generate \
 -DgroupId=mw.kiara \
 -DartifactId=calculator \
 -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

IDL derived operation mode¶

The IDL derived operation mode is similar to the traditional middleware approaches.

Based on the IDL definition we generate with a precompiler stub- and skeleton-classes, which have to be used by the application to implement the server and client (or Pub/Sub) application parts.

Prerequisite: IDL definition

Generated: Stubs and Skeletons (at compile time) which have to be used by the application

Examples: Corba, DDS, Thrift, ...

Application derived operation mode¶

This mode is typical for some modern (e.g. RMI, WebService,...) frameworks. Based on an application specific interface definitions, the framework automatically generates Server- and Client-Proxy-Classes, which serialize the application internal data structures and send them over the wire. Using Annotations, the required serialization and transport mechanisms and type mappings can be influenced.

This mode implicitly generates an IDL definition based on the Java interfaces definition and provide this IDL through a “service registry” for remote partners.

Prerequisite: Application-Interface-Definition (has to be the same on client and server side)

Generated: Server-/Client-Proxies (generated at runtime)

Examples: RMI, JAX-RS, Spring REST, ...

Mapped operation mode¶

Goal of the mapped operation mode is to separate the application interfaces from the data structure used to transport the data over the wire. Therefore the middleware has to map the application internal data structure and interfaces to a common IDL definition. Advantage is, that the application interface on client and server (or publisher/subscriber) side can be different.

Prerequisite: Application-Interface-Definition (can be different on server and client side) IDL Definition

Generated: Server-/Client-Proxis (generated at runtime, which map the attributes & operations

Examples: KIARA

The current release of KIARA provides support for the traditional IDL derived operation mode, being able to handle different communication patterns such as RPC or Publish/Subscribe. Application derived and mapped operation mode will follow in a future release.

Calculator¶

The KIARA Calculator example application provides an API to ask for simple mathematics operations over two numbers. Is a common used example when trying to understand how an RPC framework works.

Basically the service provides two functions:

• float add (float n1, float n2) :

  Returns the result of adding the two numbers introduced as parameters (n1 and n2).

• float subtract (float n1, float n2) :

  Returns the result of subtracting the two numbers introduced as parameters (n1 and n2).

The KIARA Calculator example is provided within this distribution, so itcan be used as starting point.

Basic procedure¶

Before diving into the details describing the features and configure your projectfor KIARA, the following quick example should show the basic steps to create a simple client and server application in the different operation modes.

Detailed instructions on how to execute the particular steps are given in chapter Building a KIARA RPC application.

service Calculator
{
    float32 add (float32 n1, float32 n2);
    float32 subtract (float32 n1, float32 n2);
};

public static class CalculatorServantImpl extends CalculatorServant
{
    @Override
    public float add (/*in*/ float n1, /*in*/ float n2) {
        return (float) n1 + n2;
    }

    @Override
    public float subtract (/*in*/ float n1, /*in*/ float n2) {
        return (float) n1 - n2;
    }
    ...
}

Context context = Kiara.createContext();
Server server = context.createServer();
Service service = context.createService();

// Create and register an instance of the CalculatorServant implementation.
CalculatorServant Calculator_impl = new CalculatorServantImpl();
service.register(Calculator_impl);

// register the service on port 9090 using CDR serialization
server.addService(service, "tcp://0.0.0.0:9090", "cdr");

// run the server
server.run();

Context context = Kiara.createContext();

// setup the connection to the server
Connection connection = context.connect("tcp://192.168.1.18:9090?serialization=cdr");

// get the client Proxy implementation
CalculatorClient client = connection.getServiceProxy(CalculatorClient.class);

// call the remote methods
float result = client.add(3, 5);

Kiaragen installation¶

To install kiaragen, please follow the installation instructions that can be found in the .

Generate support code manually using kiaragen¶

To call kiaragen manually it has to be installed and in your run path.

The usage syntax is:

$ kiaragen [options] <IDL file> [<IDL file> ...]

Options:

IDL derived operation mode in RPC¶

The general steps to build an application in IDL derived operation mode are:

1. Define a set of remote procedures: using the KIARA Interface Definition Language.
2. Generation of specific remote procedure call support code: a Client-Proxy and a Server-Skeleton.
3. Implement the servant: with the needed behaviour.
4. Implement the server: filling the server skeleton with the behaviour of the procedures.
5. Implement the client: using the client proxy to invoke the remote procedures.

This section describes the basic concepts of these four steps that a developer has to follow to implement a distributed application.

Defining a set of remote procedures using the KIARA IDL¶

The KIARA Interface Definition Language (IDL) can be used to define the remote procedures (operations) the server will offer. Simple and Complex Data Types | used as parameter types in these remote procedures are also defined in the IDL file. The IDL file for our example application (calculator.idl) shows the usage of some of the above elements.

service Calculator
{
    float32 add (float32 n1, float32 n2);
    float32 substract (float32 n1, float32 n2);
};

Generating remote procedure call support code¶

KIARA Advanced Middleware includes a Java application named kiaragen. This application parses the IDL file and generates Java code for the defined set of remote procedures.

All support classes will be generated (e.g. for structs):

• x.y.<StructName>: Support classes containing the definition of the data types as well as the serialization code.

Using the -example option (described below), kiaragen will generate the following files for each of your module/service definitions:

• x.y.<IDL-ServiceName>:

  Interface exposing the defined synchronous service operation calls.

• x.y.<IDL-ServiceName>Async:

  Interface exposing the asynchronous operation calls.

• x.y.<IDL-ServiceName>Client:

  Interface exposing all client side calls (sync & async).

• x.y.<IDL-ServiceName>Process:

  Class containing the methods that will be executed to process dynamic calls.

• x.y.<IDL-ServiceName>Proxy:

  This class encapsulates all the logic needed to call the remote operations. (Client side proxy → stub).

• x.y.<IDL-ServiceName>Servant:

  This abstract class provides all the mechanisms (transport, un/marshalling, etc.) the server requires to call the server functions.

• x.y.<IDL-ServiceName>ServantExample:

  This class will be extended to implement the server side functions (see Servant Implementation).

• x.y.ClientExample:

  This class contains the code needed to run a possible example of the client side application.

• x.y.ServerExample:

  This class contains the code needed to run a possible example of the server side application.

• x.y.IDLText:

  This class contains a String whose value is the content of the IDL file.

The package name x.y. can be declared when generating the support code using kiaragen (see -package option in kiaragen tool description).

For our example the call could be:

$ kiaragen -example rpc -package com.example src/main/idl/calculator.idl
Loading templates...
org.fiware.kiara.generator.kiaragen
org.fiware.kiara.generator.idl.grammar.Context
Processing the file calculator.idl...
Creating destination source directory... OK
Generating Type support classes...
Generating application main entry files for interface Calculator... OK
Generating specific server side files for interface Calculator... OK
Generating specific client side files for interface Calculator... OK
Generating common server side files... OK
Generating common client side files... OK

This would generate the following files:

.
└── src                                                // source files
    ├── main
    │   ├── idl                                        // IDL definitions for kiaragen
    │   │   └── calculator.idl
    │   └── java                                       // Generated support files
    │       └── com.example
    │            │                                     // Generated using --example
    │            ├── Calculator.java                   // Interface of service
    │            ├── CalculatorAsync.java              // Interface of async calls
    │            ├── CalculatorProcess.java            // Process methods for dynamic operations
    │            ├── CalculatorClient.java             // Interface client side
    │            ├── CalculatorProxy.java              // Client side implementation
    │            ├── CalculatorServant.java            // Abstract server side skeleton
    │            ├── CalculatorServantExample.java     // Dummmy servant impl.
    │            ├── ClientExample.java                // Example client code
    │            ├── ServerExample.java                // Example server code
    │            └── IDLText.java                      // IDL File contents
    └── build.gradle                                   // File with targets to compile the example

Servant implementation¶

Please note that the code inside the file x.y.<IDL-ServiceName>ServantExample.java (which in this case is CalculatorServantExample.java) has to be modified in order to specify the behaviour of each declared function.

class CalculatorServantExample extends CalculatorServant {

  public float add (/*in*/ float n1, /*in*/ float n2) {
        return (float) n2 + n2;
    }

    public float substract (/*in*/ float n1, /*in*/ float n2) {
        return (float) n1 - n2;
    }

}

Implementing the server¶

The source code generated using kiaragen tool (by using the -example option) contains a simple implementation of a server. This implementation can obviously be extended as far as the user wants, this is just a very simple server capable of executing remote procedures.

The class containing the mentioned code is named ServerExample, and its code is shown below:

public class ServerExample {

    public static void main (String [] args) throws Exception {

        System.out.println("CalculatorServerExample");

        Context context = Kiara.createContext();
        Server server = context.createServer();

        CalculatorServant Calculator_impl = new CalculatorServantExample();

        Service service = context.createService();

        service.register(Calculator_impl);

        //Add service waiting on TCP with CDR serialization
        server.addService(service, "tcp://0.0.0.0:9090", "cdr");

        server.run();

    }

}

Implementing the client¶

The source code generated using kiaragen tool (by using the -example option) contains a simple implementation of a client. This implementation must be extended in order to show the output received from the server.

In the KIARA Calculator example, as we have defined first the add function in the IDL file, this will be the one used by default in the generated code. The code for doing this is shown in the following snippet:

public class ClientExample {
    public static void main (String [] args) throws Exception {
        System.out.println("CalculatorClientExample");

    float n1 = (float) 3.0;
    float n2 = (float) 5.0;

        float ret = (float) 0.0;

        Context context = Kiara.createContext();

        Connection connection =
                     context.connect("tcp://127.0.0.1:9090?serialization=cdr");
        Calculator client = connection.getServiceProxy(CalculatorClient.class);

    try {
            ret = client.add(n1, n2);
            System.out.println("Result: " + ret);
        } catch (Exception ex) {
            System.out.println("Exception: " + ex.getMessage());
            return;
        }
    }

    Kiara.shutdown();
}

The previous code has been shown exactly the way it is generated, with only two differences:

• Parameter initialization: Both of the parameters n1 and n2 have been initialized to random values (in this case 3 and 5).
• Result printing: To have feedback of the response sent by the server when the remote procedure is executed.

Compiling the client and the server¶

For the client and server examples to compile, some jar files are needed. These files are located under the lib directory provided with this distribution, and they must be placed in the root working directory, under the lib folder:

.
├── src                       // source files
├── lib                       // generated support files
└── build.gradle              // Gradle compilation script

To compile the client using gradle, the call would be the next one (change target clientJar to serverJar to compile the server):

$ gradle clientJar
:compileJava UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:clientJar

BUILD SUCCESSFUL

Total time: 3.426 secs

After compiling both of them the following files will be generated:

.
├── src                       // source files
├── build                     // generated by gradle
│   ├── classes               // Compiled .class files
│   ├── dependency-cache      // Inner gradle files
│   ├── libs                  // Executable jar files
│   └── tmp                   // Temporal files used by gradle
├── lib
└── build.gradle              //  Gradle compilation script

In order to execute the examples, just cd where they are placed (build/libs directory), and execute them using the command java -jar file_to_execute.jar.

Declaring the remote calls and data types at runtime¶

In the dynamic approach, the comple time kiaragen code-generator will not be required anymore. Instead, the middleware provides a function to load the IDL definition from a String object. The generation of the IDL String has to be done by the developer. For example it can be loaded from a File, from a URL or generated by an algorithm.

The process to declare the dynamic part is as follows:

• The server loads the IDL String (e.g. from a file).
• The IDL definition will then be provided to the clients connecting with the server.
• On the server the developer has to provide objects to act as servants and execute code depending on the function the client has requested.

// Load IDL content string from file
String idlString = new String(Files.readAllBytes(Paths.get("calculator.idl")));
/* This is just one way to do it. Developer decides how to do it */

// Load service information dynamically from IDL
Service service = context.createService();
service.loadServiceIDLFromString(idlString);

// Create type descriptor and dynamic builder
final TypeDescriptorBuilder tdbuilder = Kiara.getTypeDescriptorBuilder();
final DynamicValueBuilder dvbuilder = Kiara.getDynamicValueBuilder();
// Create type descriptor int (used for the return value)
final PrimitiveTypeDescriptor intType =
                        tdbuilder.createPrimitiveType(TypeKind.INT_32_TYPE);

// Implement the functional interface for the add function
DynamicFunctionHandler addHandler = new DynamicFunctionHandler() {
     @Override
     public void process(
          DynamicFunctionRequest request,
          DynamicFunctionResponse response
     ) {
          // read the parameters
          int a = (Integer)((DynamicPrimitive)request.getParameterAt(0)).get();
          int b = (Integer)((DynamicPrimitive)request.getParameterAt(1)).get();
          // create the return value
          final DynamicPrimitive intValue =
                              (DynamicPrimitive)dvbuilder.createData(intType);
          intValue.set(a+b);    // implmement the function
          response.setReturnValue(intValue);
     }
}

// Register function and map handler (do this for every function)
service.register("Calculator.add", addHandler);

Implementing the server¶

Because the server functionality is not encapsuled in generated Servant classes, the server implmentation is a bit more extensive. It still follows the same pattern as in the static API, but the implementation and registration of the dynamic functions has to be done completely by the developer.

The following ServerExample class shows, how this would look like:

public class ServerExample {
    public static void main (String [] args) throws Exception {
        System.out.println("CalculatorServerExample");

        Context context = Kiara.createContext();
        Server server = context.createServer();

        // Enable negotiation with clients
        server.enableNegotiationService("0.0.0.0", 8080, "/service");

        Service service = context.createService();
        String idlContent =
        new String(Files.readAllBytes(Paths.get("calculator.idl")))
        service.loadServiceIDLFromString(idlContent);

        // Create descriptor and dynamic builder
        final TypeDescriptorBuilder tdbuilder = Kiara.getTypeDescriptorBuilder();
        final DynamicValueBuilder dvbuilder = Kiara.getDynamicValueBuilder();

        // Declare handlers
        DynamicFunctionHandler addHandler;
        DynamicFunctionHandler substractHandler;
        addHandler = /* Implement handler for the add function */;
        substractHandler = /* Implement handler for the substract function */;

        // Register services
        service.register("Calculator.add", addHandler);
        service.register("Calculator.substract", substractHandler);

        //Add service waiting on TCP with CDR serialization
        server.addService(service, "tcp://0.0.0.0:9090", "cdr");

        server.run();
    }
}

Implementing the client¶

On the client side the key point is the negotiation with the server to download the IDL it provides. After downloading, it will automatically parse the content and generate the necessary information to create the dynamic objects.

When the DynamicProxy is created the functions provided by the server can be executed by using DynamicFunctionRequest objects. The parameters of the functions have to be set in the request using DynamicData objects. The call of the request function execute() will finally perform the call to the server and return the result in a DynamicFunctionResponse object.

The following code shows the client implementation:

public class ClientExample {
    public static void main (String [] args) throws Exception {
        System.out.println("CalculatorClientExample");

        Context context = Kiara.createContext();

        // Create connection indicating the negotiation service
        Connection connection =
                     context.connect("kiara://127.0.0.1:9090/service");

        // Create client by using the proxy's name
        DynamicProxy client = connection.getDynamicProxy("Calculator");

        // Create request object
        DynamicFunctionRequest request = client.createFunctionRequest("add");
        ((DynamicPrimitive) request.getParameterAt(0)).set(8);
        ((DynamicPrimitive) request.getParameterAt(1)).set(5);

        // Create response object and execute RPC
        DynamicFunctionResponse response = request.execute();
        if (response.isException()) {
            DynamicData result = response.getReturnValue();
            System.out.println("Exception = " + (DynamicException) result);
        } else {
            DynamicData result = response.getReturnValue();
            System.out.println("Result = " + (DynamicPrimitive) result);
        }
    // shutdown the client
        Kiara.shutdown();
    }
}

IDL derived operation mode using Pub/Sub¶

The general steps to build an application in IDL derived operation mode are:

1. Define the application data types using KIARA IDL: using the KIARA Interface Definition Language.
2. Generation of specific support code: those classes representing the types defined using IDL.
3. Generate the Pub/Sub example: using the kiaragen tool.
4. Implementing the Publisher side: using the Publisher entity and the generated type support classes.
5. Implementing the Subscriber side: using the Subscriber entity and the generated type support classes.

This section describes the basic concepts of these steps that a developer has to follow to implement a distributed application.

Defining the application data types using KIARA IDL¶

The KIARA Interface Definition Language (IDL) can be used to define the application data types to be published. Simple and Complex Data Types inside the structures can also be defined in the IDL file, but take into account that only structures will count as Topic types.

The IDL file for our RPC example application shows the definition of a temperature sensor whose value is going to be published over the wire when changed.

struct TSensor
{
    float32 temperature;
};

Generate Pub/Sub code using kiaragen¶

KIARA Advanced Middleware includes a Java application named kiaragen. By using this application, the type support code for the structure defined in the IDL file can be generated. The files that will result as the output of the kiaragen execution are the following:

• x.y.: Support classes containing the definition of the data types as well as the serialization code.
• x.y.Type: Topic class for the data type. This class will be the one used to register the data types in a specific topic.

Using ps as -example option, kiaragen will generate the following files for the data type definitions:

• x.y.SubscriberExample: This class contains the code needed to run a simple application with a Subscriber.
• x.y.PublisherExample: This class contains the code needed to run a simple application with a Publisher.

The package name x.y. can be declared when generating the support code using kiaragen (see -package option below).

For our example the call could be:

$ kiaragen -example ps -package com.example src/main/idl/calculator.idl
Loading templates...
org.fiware.kiara.generator.kiaragen
org.fiware.kiara.generator.idl.grammar.Context
Processing the file calculator.idl...
Creating destination source directory... OK
Generating Type support classes...
Generating Type support class for structure TSensor... OK
Generating Topic class for structure TSensor... OK
Generating Publisher example main code for Topic TSensor... OK
Generating Subscriber example main code for Topic TSensor... OK

Generating GRADLE compilation script... OK

This would generate the following files:

.
└── src                                                // source files
    ├── main
    │   ├── idl                                        // IDL definitions for kiaragen
    │   │   └── sensor.idl
    │   └── java                                       // Generated support files
    │       └── com.example
    │            │                                     // Generated using --example ps
    │            ├── TSensor.java                      // User data type
    │            ├── TSensorType.java                  // Topic class for user data type
    │            ├── TSensorPublisherExample.java      // Publisher example code
    │            └── TSensorSubscriberExample.java     // Subscriber example code
    └── build.gradle                                   // File with targets to compile the example

Static Endpoint Discovery (SED) using XML files¶

In this version of the Publish/Subscribe pattern implemented in KIARA, the discovery of endpoints is done statically by loding the information of those endpoints from an XML file. It supports loading such information from a String variable with the contents of the XML discovery file as well.

The discovery information than can be represented into the XML file includes the participant (with its name), and the endpoints this participant might have (readers or writers). it also supports adding multiple participant entities as well as multiple reader or writer configurations.

The XML tags supported by KIARA are described below, grouped into different categories according to the entity they belong to.

Implementing the Publisher¶

The PubliserExample class is the one containing the main entry point for creating an application capable of publishing the user’s data types over the wire. This class is automatically generated by using the kiaragen tool, and it contains a basic initialization of QoS (Qualities of Service), a participant, and one simple Publisher entity.

The following PublisherExample class shows how this would look like:

public class TSensorPublisherExample {

    private static final TSensorType type = new TSensorType();

    public static void main (String [] args) throws InterruptedException {

The generated class has a static final variable named type, and it will be used to register the user’s data type.

The predefined arguments this example will handle are:

• domainId: This parameter is a number indicating the domain identifier for the RTPS communication. If not specified, the default value is 0.
• sampleCount: Number of samples the publisher will send. If not specified, the publisher will send examples without stopping.

int domainId = 0;
if (args.length >= 1) {
     domainId = Integer.parseInt(args[0]);
}

int sampleCount = 0;
if (args.length >= 2) {
     sampleCount = Integer.parseInt(args[1]);
}

In the following lines, the data itself is created by using the generated Topic class. The developer can now edit the created object before sending it over the network.

TSensor instance = type.createData();

// Initialize your data here

Now, the participant’s attributes are initialized. Note that the domainId introduces as a parameter will be used here, and also that the attributes specify the participant to activate the static discovery protocol.

To use the static discovery, either an XML file or a String variable with the XML contents can be used. In the generated example, the chosen approach is to load the XML discovery information by using a single String variable. In this String, the known endpoints have to be defined. In this case, a participant containing a BEST_EFFORT reader.

ParticipantAttributes pAtt = new ParticipantAttributes();
pAtt.rtps.builtinAtt.domainID = domainId;
pAtt.rtps.builtinAtt.useStaticEDP = true;

final String edpXml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
        + "<staticdiscovery>"
        + "    <participant>"
        + "        <name>SubscriberParticipant</name>"
        + "        <reader>"
        + "            <userId>1</userId>"
        + "            <topic name=\"TSensorTopic\" dataType=\"TSensor\" kind=\"NO_KEY\"></topic>"
        + "            <expectsInlineQos>false</expectsInlineQos>"
        + "            <reliabilityQos>BEST_EFFORT_RELIABILITY_QOS</reliabilityQos>"
        + "        </reader>"
        + "    </participant>"
        + "</staticdiscovery>";

pAtt.rtps.builtinAtt.setStaticEndpointXML(edpXml);

pAtt.rtps.setName("PublisherParticipant");

At this point, the only thing remaining to be done before creating the Publisher is to finally create the Participant and register the user’s data type. To do so, the generated Topic class must be used after the participant has been correctly initialized.

Participant participant = Domain.createParticipant(pAtt, null /* LISTENER */);
if (participant == null) {
     throw new RuntimeException("createParticipant");
}

Domain.registerType(participant, type);

The Publisher’s attributes must specify the topic name and the name of the data type, and this information has to be the same in the other endpoints so that they can communicate with each other. In this generated example, the topic data name will be the same of the defined structure. Note that the example uses by default a BEST_EFFORT configuration for the Publisher.

// Create publisher
PublisherAttributes pubAtt = new PublisherAttributes();
pubAtt.setUserDefinedID((short) 1);
pubAtt.topic.topicDataTypeName = "TSensor";
pubAtt.topic.topicName = "TSensorTopic";
pubAtt.qos.reliability.kind = ReliabilityQosPolicyKind.BEST_EFFORT_RELIABILITY_QOS;

org.fiware.kiara.ps.publisher.Publisher<TSensor> publisher = Domain.createPublisher(participant, pubAtt, null /* LISTENER */);

if (publisher == null) {
    Domain.removeParticipant(participant);
    throw new RuntimeException("createPublisher");
}

Finally, the examples are sent according to the number of samples specified via parameter (without stopping if this number is not set).

int sendPeriod = 4000; // milliseconds
for (int count=0; (sampleCount == 0) || (count < sampleCount); ++count) {
     System.out.println("Writing TSensor, count: " + count);
     publisher.write(instance);
     Thread.sleep(sendPeriod);
}

In order for the Participant to stop succesfully, it must be removed from the Domain (all the associated endpoints will be stopped as well), and then the method named shutdown belonging to the Kiara class will be the one to stop all running services.

        Domain.removeParticipant(participant);

        Kiara.shutdown();

        System.out.println("Publisher finished");

    }

}

Implementing the Subscriber¶

The SubscriberExample class is the one containing the main entry point for creating an application capable of subscribing to a topic representing the user’s data types. This class is automatically generated by using the kiaragen tool, and it contains a basic initialization of QoS (Qualities of Service), a participant, and one simple Subscriber entity.

The following PublisherExample class shows how this would look like:

public class TSensorSubscriberExample {

    private static final TSensorType type = new TSensorType();

    public static void main (String [] args) throws InterruptedException {

as it happened with the PublisherExample, the generated class has a static final variable named type, and it will be used to register the user’s data type.

The predefined arguments this example will handle are:

• domainId: This parameter is a number indicating the domain identifier for the RTPS communication. If not specified, the default value is 0.
• sampleCount: Number of samples the subscriber expects to receive. If not specified, the will run without stopping.

int domainId = 0;
if (args.length >= 1) {
     domainId = Integer.parseInt(args[0]);
}

int sampleCount = 0;
if (args.length >= 2) {
     sampleCount = Integer.parseInt(args[1]);
}

Now, the participant’s attributes are initialized. Note that the domainId introduces as a parameter will be used here, and also that the attributes specify the participant to activate the static discovery protocol.

To use the static discovery, either an XML file or a String variable with the XML contents can be used. In the generated example, the chosen approach is to load the XML discovery information by using a single String variable. In this String, the known endpoints have to be defined. In this case, a participant containing a BEST_EFFORT writer.

ParticipantAttributes pAtt = new ParticipantAttributes();
pAtt.rtps.builtinAtt.domainID = domainId;
pAtt.rtps.builtinAtt.useStaticEDP = true;

final String edpXml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
        + "<staticdiscovery>"
        + "    <participant>"
        + "        <name>PublisherParticipant</name>"
        + "        <writer>"
        + "            <userId>1</userId>"
        + "            <topicName>TSensorTopic</topicName>"
        + "            <topicDataType>TSensor</topicDataType>"
        + "            <topicKind>NO_KEY</topicKind>"
        + "            <reliabilityQos>BEST_EFFORT_RELIABILITY_QOS</reliabilityQos>"
        + "            <livelinessQos kind=\"AUTOMATIC_LIVELINESS_QOS\" leaseDuration_ms=\"100\"></livelinessQos>"
        + "        </writer>"
        + "     </participant>"
        + "    </staticdiscovery>";

pAtt.rtps.builtinAtt.setStaticEndpointXML(edpXml);

pAtt.rtps.setName("SubscriberParticipant");

At this point, the only thing remaining to be done before creating the Subscriber is to finally create the Participant and register the user’s data type. To do so, the generated Topic class must be used after the participant has been correctly initialized.

Participant participant = Domain.createParticipant(pAtt, null /* LISTENER */);
if (participant == null) {
     throw new RuntimeException("createParticipant");
}

Domain.registerType(participant, type);

The Publisher’s attributes must specify the topic name and the name of the data type, and this information has to be the same in the other endpoints so that they can communicate with each other. In this generated example, the topic data name will be the same of the defined structure. Note that the example uses by default a BEST_EFFORT configuration for the Subscriber.

// Create publisher
SubscriberAttributes satt = new SubscriberAttributes();
satt.setUserDefinedID((short) 1);
satt.topic.topicDataTypeName = "TSensor";
satt.topic.topicName = "TSensorTopic";
satt.qos.reliability.kind = ReliabilityQosPolicyKind.BEST_EFFORT_RELIABILITY_QOS;


// CountDown object to store the number of received samples
final CountDownLatch doneSignal = new CountDownLatch(sampleCount);

For this Subscriber, a SubscriberListener object is implemented below. It will print out when a new saple has been received by the Subscriber, and it will also take care of the total number of samples that have already been received.

org.fiware.kiara.ps.subscriber.Subscriber<TSensor> subscriber = Domain.createSubscriber(participant, satt, new SubscriberListener() {

    @Override
    public void onNewDataMessage(Subscriber<?> sub) {
        TSensor type = (TSensor) sub.takeNextData(null /* SampleInfo */);
        while (type != null) {
            System.out.println("Message received");
            type = (TSensor) sub.takeNextData(null);
            doneSignal.countDown();
        }
    }

    @Override
    public void onSubscriptionMatched(Subscriber<?> sub, MatchingInfo info) {
        // Write here you handling code
    }

});

if (subscriber == null) {
    Domain.removeParticipant(participant);
    throw new RuntimeException("createSubscriber");
}


int receivePeriod = 4000; // milliseconds
while ((sampleCount == 0) || (doneSignal.getCount() != 0)) {
    System.out.println("$ctx.currentSt.name$ Subscriber sleeping for " + receivePeriod/1000 + " seconds..");
    Thread.sleep(receivePeriod);
}

In order for the Participant to stop succesfully, it must be removed from the Domain (all the associated endpoints will be stopped as well), and then the method named shutdown belonging to the Kiara class will be the one to stop all running services.

        Domain.removeParticipant(participant);

        Kiara.shutdown();

        System.out.println("Publisher finished");

    }

}

API & Data Access¶

The application accesses the communication middleware using a set of defined function calls provided by the API-layer. They may vary depending on the communication pattern (see below).

The main functionality of the Data Access Layer is to provide the mapping of data types and Function Stubs/Skeletons (request/response pattern) or DataReaders/-Writers (publish/subscribe or point-to-point pattern).

The Advanced Middleware GE provides two variants of this functionality:

• A basic static compile-time Data-Mapping and generation of Function Stubs/Skeletons or DataReaders/-Writers, created by a compile time IDL-Parser/Generator from the remote service description, which is provided in an Interface Definition Language (IDL) syntax based on the Object Management Group (OMG) IDL (see below), which is submitted as a W3C draft.
• A dynamic runtime Data-Mapping and invocation of Function or DataReader/-Writer proxies, by parsing the IDL description of the remote service at runtime and map it to the function/data definition provided by the developer when setting up the connection.

Quality of Service (QoS) parameters and Security Policies may be provided through the API and/or IDL-Annotations. This information will be used by the QoS and Security modules to ensure the requested guarantees.

Depending on the communication pattern, different communication mechanisms will be used.

• For publish/subscribe and point-to-point scenarios, the DDS services and operations will be provided. When opening connections, a DataWriter for publishers/sender and a DataReader for subscribers/receivers will be created, which can be used by the application to send or receive DDS messages.
• For request/reply scenarios the Function Stubs/Skeletons created at compile-time can be used to send or receive requests/replies.

Marshalling¶

Depending on configuration, communication pattern and type of end-points the data will be serialized to the required transmission format when sending and deserialized to the application data structures when receiving.

• Common Data Representation (CDR) an OMG specification used for all DDS/RTPS and high-speed communication.
• Extensible Markup Language (XML) for WebService compatibility.
• JavaScript Object Notation (JSON) for WebService compatibility.

Wire Protocols¶

Depending on configuration, communication pattern and type of end-points the matching Wire-Protocol will be chosen.

• For publish/subscribe and point-to-point patterns the Real Time Publish Subscribe (RTPS) Protocol is used.
• For request/reply pattern with WebService compatibility the HTTP Protocol is used.
• For request/reply pattern between DDS end-points the Real Time Publish Subscribe (RTPS) Protocol is used.

Dispatching¶

The dispatching module is supporting various threading models and scheduling mechanisms. The module is providing single-threaded, multi-threaded and thread-pool operation and allows synchronous and asynchronous operation. Priority or time constraint scheduling mechanisms can be specified through QoS parameters.

Transport Mechanisms¶

Based on the QoS parameters and the runtime-environment the QoS module will decide which transport mechanisms and protocols to choose for data transmission.

In Software Defined Networking (SDN) environments, the QoS module will interface with the Netfloc GE to get additional network information or even provision the network components to provide the requested quality of service or privacy.

Transport Protocols¶

All standard transport protocols (TCP, UDP) as well as encrypted tunnels (TLS, DTLS) are supported.

Security¶

The security module is responsible for authentication of communication partners and will ensure in the whole middleware stack, the requested data security and privacy. The required information can be provided with Security Annotations in the IDL and by providing a security policy via the API.

Negotiation¶

The negotiation module provides mechanisms to discover or negotiate the optimal transmission format and protocols when peers are connecting. It discovers automatically the participants in the distributed system, searching through the different transports available (shared memory and UDP by default, TCP for WebService compatibility) and evaluates the communication paradigms and and the corresponding associated QoS parameters and security policies.

API & Data Access¶

The application accesses the communication middleware using a set of defined function calls provided by the API-layer. They may vary depending on the communication pattern (see below).

The main functionality of the Data Access Layer is to provide the mapping of data types and Function Stubs/Skeletons (request/response pattern) or DataReaders/-Writers (publish/subscribe or point-to-point pattern).

The Advanced Middleware GE provides two variants of this functionality:

• A basic static compile-time Data-Mapping and generation of Function Stubs/Skeletons or DataReaders/-Writers, created by a compile time IDL-Parser/Generator from the remote service description, which is provided in an Interface Definition Language (IDL) syntax based on the Object Management Group (OMG) IDL (see below), which is submitted as a W3C draft.
• A dynamic runtime Data-Mapping and invocation of Function or DataReader/-Writer proxies, by parsing the IDL description of the remote service at runtime and map it to the function/data definition provided by the developer when setting up the connection.

Quality of Service (QoS) parameters and Security Policies may be provided through the API and/or IDL-Annotations. This information will be used by the QoS and Security modules to ensure the requested guarantees.

Depending on the communication pattern, different communication mechanisms will be used.

• For publish/subscribe and point-to-point scenarios, the DDS services and operations will be provided. When opening connections, a DataWriter for publishers/sender and a DataReader for subscribers/receivers will be created, which can be used by the application to send or receive DDS messages.
• For request/reply scenarios the Function Stubs/Skeletons created at compile-time can be used to send or receive requests/replies.

Marshalling¶

Depending on configuration, communication pattern and type of end-points the data will be serialized to the required transmission format when sending and deserialized to the application data structures when receiving.

• Common Data Representation (CDR) an OMG specification used for all DDS/RTPS and high-speed communication.
• Extensible Markup Language (XML) for WebService compatibility.
• JavaScript Object Notation (JSON) for WebService compatibility.

Wire Protocols¶

Depending on configuration, communication pattern and type of end-points the matching Wire-Protocol will be chosen.

• For publish/subscribe and point-to-point patterns the Real Time Publish Subscribe (RTPS) Protocol is used.
• For request/reply pattern with WebService compatibility the HTTP Protocol is used.
• For request/reply pattern between DDS end-points the Real Time Publish Subscribe (RTPS) Protocol is used.

Dispatching¶

The dispatching module is supporting various threading models and scheduling mechanisms. The module is providing single-threaded, multi-threaded and thread-pool operation and allows synchronous and asynchronous operation. Priority or time constraint scheduling mechanisms can be specified through QoS parameters.

Transport Mechanisms¶

Based on the QoS parameters and the runtime-environment the QoS module will decide which transport mechanisms and protocols to choose for data transmission.

In Software Defined Networking (SDN) environments, the QoS module will interface with the Netfloc GE to get additional network information or even provision the network components to provide the requested quality of service or privacy.

Transport Protocols¶

All standard transport protocols (TCP, UDP) as well as encrypted tunnels (TLS, DTLS) are supported.

Security¶

The security module is responsible for authentication of communication partners and will ensure in the whole middleware stack, the requested data security and privacy. The required information can be provided with Security Annotations in the IDL and by providing a security policy via the API.

Negotiation¶

The negotiation module provides mechanisms to discover or negotiate the optimal transmission format and protocols when peers are connecting. It discovers automatically the participants in the distributed system, searching through the different transports available (shared memory and UDP by default, TCP for WebService compatibility) and evaluates the communication paradigms and and the corresponding associated QoS parameters and security policies.

org.fiware.kiara.Kiara¶

This class is the main entry point to use the Advanced Middlware. It creates or provides implementation of the top level Advanced Middleware interfaces, especially the Context.

Functions:

• getTypeDescriptorBuilder: This function returns an instance of the type descriptor builder. It is a part of the dynamic API and is described here.
• getDynamicValueBuilder: This function returns an instance of the dynamic value builder. It is a part of the dynamic API and is described here.
• createContext: This function creates a new instance of the Context class, which is described below.
• shutdown: This function closes and releases all internal Advanced Middleware structures (e.g. stops all pending tasks). Call this before you exit your application.

org.fiware.kiara.Context¶

This interface is the starting point to use the Advanced Middleware. It holds the configuration of the middleware and hides the process of negotiation, selection, and configuration of the correct implementation classes. Also it provides users a way to instantiate Advanced Middleware components.

Functions:

• connect: This function creates a new connection to the server. This connection might be used by proxies to send requests to the server.
• createTransport: This function provides a direct way to create a specific network Transport instance which can be configured for specific use cases.
• createSerializer: This function provides a direct way to create a specific Serializer instance which can be configured for specific use cases.
• createServer: This function creates a new Server instance used to add Service instances.
• createService: This function creates a new Service instance used to register Servant instances.

org.fiware.kiara.transport.Transport¶

This interface provides a basic abstraction for network transport implementations. To create a Transport instance directly, the developer must use the factory method createTransport of the interface org.fiware.kiara.Context, which will return a compliant network transport implementation.

Functions:

• getTransportFactory: This function returns an instance of the factory class used to create this transport instance.

org.fiware.kiara.transport.ServerTransport¶

This interface provides an abstraction for a server-side connection endpoint waiting for incoming connections.

Functions:

• getTransportFactory: This function returns an instance of a factory class which was used to create this server transport instance.
• setDispatchingExecutor: This function sets executor service used for dispatching incoming messages.
• getDispatchingExecutor: Returns executor service previously set.
• isRunning: Returns true if server is up and waiting for incoming connections.
• startServer: Starts server.
• stopServer: Stops server.
• getLocalTransportAddress: Returns transport address to which this server is bound.

org.fiware.kiara.client.AsyncCallback¶

This interface provides an abstraction used by the client to return the server’s reply when the call was asynchronous.

Functions:

• onSuccess: This function will be called when the remote function call was successfull. It must be implemented by the user.
• onFailure: This function will be called when the remote function call was not successfull.It must be implemented by the user.

org.fiware.kiara.server.Server¶

Using this interface, users can start up multiple services on different ports. The implementation uses serialization mechanisms and network transports to listen for client requests and executes the proper Servant implementation. The optional negotiation protocol provides automatic discovery of all available services via the HTTP protocol.

Functions:

• enableNegotiationService: Enables the negotiation service on the specified port and configuration path.
• disableNegotiationService: Disables the negotiation service.
• addService: This function registers the service on a specified URL and with a specified serialization protocol.
• removeService: Removes a previously registered service.
• run: Starts the server.

org.fiware.kiara.server.Service¶

This interface represent a service that can be registered with the server.

Functions:

• register: Register a Servant object or DynamicHandler with the service.
• loadServiceIDLFromString: Load the service IDL from a string. This function is only required when the service is handled via dynamic handlers.

org.fiware.kiara.server.Servant¶

This interface provides an abstraction used by the server to execute the provided functions when a client request is received.

Functions:

• getServiceName: Returns the name of the service implemented by this servant.
• process: This function processes the incoming request message and returns the produced response message. It is automatically generated.

x.y.<IDL-ServiceName>¶

This interface is a mapping of the Advanced Middleware IDL service. It exposes the service’s procedures. All classes that implement these service’s procedures, have to inherit from this interface. For example the imlementation of the servant have to inherit from this interface, allowing the user to implement the service’s procedures.

Functions:

• add: This function is the mapping of the Advanced Middleware IDL service procedure add().

x.y.<IDL-ServiceName>Async¶

This interface is a mapping of the Advanced Middleware IDL service. It exposes the asynchronous version of the service’s procedures. All classes that that implement these service’s asynchronous procedures have to inherit from this interface.

Functions:

• add: This function is the asynchronous version of the Advanced Middleware IDL service’s procedure add(). It has no return value.

x.y.<IDL-ServiceName>Process¶

This class is a mapping of the Advanced Middleware IDL service. It provides the asynchronous version of the service’s processing procedures.

Functions:

• add_processAsync: This function is the asynchronous version of the Advanced Middleware IDL service’s process procedure. It has no return value.

x.y.<IDL-ServiceName>Client¶

This interface provides the synchronous and asynchronous version of the Advanced Middleware IDL service, because it implements the previously described interfaces x.y.<IDL-ServiceName> and x.y.<IDL-ServiceInterface>Async. The Advanced Middleware IDL service proxy will implement this interface, allowing the user to call the service’s remote procedures synchronously or asynchronously. It is only used on the client side in order to make the Proxy to implement all the functions for this service (both synchronous and asynchronous).

Functions:

• add: Function inherited from x.y.<IDL-ServiceName> interface. This function is the mapping of the Advanced Middleware IDL service.
• add: Function inherited from x.y.<IDL-ServiceName>Async interface. This function is the asynchronous version of the Advanced Middleware IDL service’s procedure.

x.y.<IDL-ServiceName>Proxy¶

This class encapsulates the implementation of the interface x.y.<IDL-ServiceName>Client. It provides the logic to call the Advanced Middleware IDL service’s remote procedures, synchronously or asynchronously.

Functions:

• add: Function inherited from x.y.<IDL-ServiceName>Client interface. This function is the mapping of the Advanced Middleware IDL service.
• add: Function inherited from x.y.<IDL-ServiceName>Client interface. This function is the asynchronous version of the Advanced Middleware IDL service’s procedure.

x.y.<IDL-ServiceName>Servant¶

This abstract class can be used by users to implement the Advanced Middleware IDL service’s procedures. This class implements the interface org.fiware.kiara.server.Servant, providing the mechanism the server will use to call the user’s procedure implementations. Also it inherits from the interface x.y.<IDL-ServiceName> leaving the implementation of this functions to the user.

Direct connection to remote service¶

This example shows how to create a direct connection to a server using the TCP transport and the CDR serialization. After it creates the connection, the service proxy is instantiated and used to call a remote procedure.

Context context = Kiara.createContext();
Connection connection = context.connect("tcp://192.168.1.18:8080?serialization=cdr");
CalculatorClient client = connection.getServiceProxy(CalculatorClient.class);

int result = client.add(3,4);

Transport and Serialization instances are implizitly created by the connection, based on the string parameter of the connect method.

org.fiware.kiara.Kiara¶

This class is the main entry point to use Advanced Middleware middleware. It creates or provides implementation of top level Advanced Middleware interfaces, especially Context.

Functions:

• getTypeDescriptorBuilder: This function returns an instance of the type DescriptorBuilder described below.
• getDynamicValueBuilder: This function returns an instance of the DynamicValueBuilder described below.
• createContext: This function creates a new instance of the Context class, which is part of the public Advanced Middleware RPC API.
• shutdown: This function closes releases all internal Advanced Middleware structures, and is a part of the public Advanced Middleware RPC API.

org.fiware.kiara.serialization.Serializer¶

This interface is part of the public Advanced Middleware RPC API.

org.fiware.kiara.serialization.impl.Serializable¶

This interface is the one that must be implemented by all the used defined data types in order to be serializable. It defines the methods serialize and deserialize for each data type. This class will not be described in this document, for more information take a look at the Advanced Middleware RPC API document.

org.fiware.kiara.client.Connection¶

The Connection interface manages the connection to the server. It holds the required Transport objects and Serialization objects. Also it can create these object automatically depending on the server information. The connection provides the service proxy interfaces, which will be used by the application to call remote functions.

Functions:

• getDynamicProxy: This function looks in the endpoint for a service whose name is the same as the one specified as a parameter, and creates a new DynamicProxy representing that service. This DynamicProxy will provide the user with all the functions defined in such a service.

org.fiware.kiara.typecode.TypeDescriptorBuilder¶

This interface defined the operations used to create type-describing objects. It allows the users to create every supported data type inside Advanced Middleware by acting as a single access builder.

Functions:

• createVoidType: This function creates a new DataTypeDescriptor representing a void data type..
• createPrimitiveType: This function returns a new PrimitiveTypeDescriptor whose kind is the same specified as a parameter.
• createArrayType: Function that creates a new ArrayTypeDescriptor object representing an array.
• createListType: This function creates a new ListTypeDescriptor object representing a list of objects.
• createSetType: Function that creates a new SetTypeDescriptor object representing a set. A set is defined as a list with no repeated objects.
• createMapType: This function is used to create a MapTypeDescriptor object that represents a map data type.
• createStructType: This function creates a new StructTypeDescriptor object representing a struct data type.
• createEnumType: Function that creates a new EnumTypeDescriptor object representing an enumeration.
• createUnionType: This function can be used to create a new UnionTypeDescriptor that represents a union data type.
• createExceptionType: Function that creates a new ExceptionTypeDescriptor used to represent an exception data type.
• createFunctionType: This function can be used to create a new FunctionTypeDescriptor representing a Remote Procedure Call (RPC).
• createServiceType: Function that creates a new ServiceTypeDescriptor object used to represent a service defined in the server’s side.

org.fiware.kiara.typecode.TypeDescriptor¶

This class is used to manipulate the objects used to describe the data types. It allows the users to know what type of data an object represents.

Interface TypeDescriptor

Functions:

• getKind: Function that returns the TypeKind of a TypeDescriptor object.
• isData: This function returns true if and only if the TypeDescriptor represented by the object in which is invoked describes a data type. Functions and services are not considered data types.
• isPrimitive: Function used to know if a TypeCode object is a description of a primitive data type.
• isVoid: This function returns true if the TypeDescriptor object represents a void data type.
• isContainer: This function can be used to check if a TypeDescriptor object is representing a container type. The types considered as container data types are arrays, lists, sets and maps.
• isArray: Function used to know if a TypeDescriptor object is a description of an array data type.
• isList: Function used to know if a TypeDescriptor object is a description of a list data type.
• isMap: Function used to know if a TypeDescriptor object is a description of a map data type.
• isSet: Function used to know if a TypeDescriptor object is a description of a set data type.
• isMembered: This function is used to know if a TypeDescriptor object is a description of a membered data type. Membered types are structs, enumerations, unions and exceptions.
• isStruct: Function used to know if a TypeDescriptor object is a description of a struct data type.
• isEnum: Function used to know if a TypeDescriptor object is a description of an enumeration data type.
• isUnion: Function used to know if a TypeDescriptor object is a description of a union data type.
• isException: Function used to know if a TypeDescriptor object is a description of an exception data type.
• isFunction: Function used to know if a TypeDescriptor object is a description of a function.
• isService: Function used to know if a TypeDescriptor object is a description of a service.

org.fiware.kiara.typecode.data.DataTypeDescriptor¶

Interface that represents the top level class of the data type hierarchy. It is used as a generic type to englobe only and exclusively data type descriptors.

Interface DataTypeDescriptor

Functions: None

org.fiware.kiara.typecode.data.PrimitiveTypeDescriptor¶

Interface that represents a primitive data type. Primitive types include boolean, byte, i16, ui16, i32, ui32, i64, ui64, float32, float64, char and string.

Interface PrimitiveTypeDescriptor

Functions:

• isString: This function returns true if and only if the PrimitiveTypeDescriptor object represents a string data type.
• setMaxFixedLength: This function can only be used with string types. It sets the maximum length value for a specific string represented by the PrimitiveTypeDescriptor object.
• getMaxFixedLength: This function returns the maximum length specified when creating the PrimitiveTypeDescriptor object if it represents a string data type.

org.fiware.kiara.typecode.data.ContainerTypeDescriptor¶

Interface that represents a container data type. Container data types are arrays, lists, maps and sets.

Interface ContainerTypeDescriptor

Functions:

• setMaxSize: This function sets the maximum size of a container data type.
• getMaxSize: This function returns the maximum size of a container data type.

org.fiware.kiara.typecode.data.ArrayTypeDescriptor¶

Interface that represents an array data type. Arrays can hold multiple repeated objects of the same data type inside.

Interface ArrayTypeDescriptor

Functions:

• getElementType: This function returns the DataTypeDescriptor object describing the content type of the array.
• setElementType: This function sets the DataTypeDescriptor object describing the content type of the array.
• setDimensions: This method sets the dimensions of the array.
• getDimensions: This method returns the different dimensions of the array.

org.fiware.kiara.typecode.data.ListTypeDescriptor¶

Interface that represents a list data type. Lists can hold multiple repeated objects of the same data type inside.

Interface ListTypeDescriptor

Functions:

• getElementType: This function returns the DataTypeDescriptor object describing the content type of the list.
• setElementType: This function sets the DataTypeDescriptor object describing the content type of the list.

org.fiware.kiara.typecode.data.SetTypeDescriptor¶

Interface that represents a set data type. Sets can have non repeated objects of the same data type inside.

Interface SetTypeDescriptor

Functions:

• getElementType: This function returns the DataTypeDescriptor object describing the content type of the set.
• setElementType: This function sets the DataTypeDescriptor object describing the content type of the set.

org.fiware.kiara.typecode.data.MapTypeDescriptor¶

Interface that represents a map data type. Maps can hold multiple key-object pairs inside if and only if the key objects are unique.

Interface MapTypeDescriptor

Functions:

• getKeyTypeDescriptor: This function returns the DataTypeDescriptor object describing the key type of the map.
• setKeyTypeDescriptor: This function sets the DataTypeDescriptor object describing the key type of the map.
• getValueTypeDescriptor: This function returns the DataTypeDescriptor object describing the value type of the map.
• setValueTypeDescriptor: This function sets the DataTypeDescriptor object describing the value type of the map.

org.fiware.kiara.typecode.data.MemberedTypeDescriptor¶

Interface that represents a membered data type. Membered data types are structs, enumerations, unions and exceptions.

Interface MemberedTypeDescriptor

Functions:

• getMembers: This function returns the list of member objects stored in a ContainerTypeDescriptor object.
• getName: This function returns the name of the ContainerTypeDescriptor object.

org.fiware.kiara.typecode.data.StructTypeDescriptor¶

Interface that represents a struct data type. Structs can have multiple different DataTypeDescriptor objects inside stored as members. Every struct member is identified by a unique name.

Interface StructTypeDescriptor

Functions:

• addMember: This function adds a new TypeDescriptor object as a member using a specific name.
• getMember: This function returns a DataTypeDescriptor object identified by the name introduced as a parameter.

org.fiware.kiara.typecode.data.EnumTypeDescriptor¶

Interface that represents an enumeration data type. Enumerations are formed by a group of different string values.

Interface EnumTypeDescriptor

Functions:

• addValue: This function adds a new value to the enumeration using the string object received as a parameter.

org.fiware.kiara.typecode.data.UnionTypeDescriptor¶

Interface that represents a union data type. Unions are formed by a group of members identified by their names and the labels of the discriminator to which they are assigned.

Interface UnionTypeDescriptor

Functions:

• addMember: This function adds a new TypeDescriptor object as a member using a specific name and the labels of the discriminator.

org.fiware.kiara.typecode.data.ExceptionTypeDescriptor¶

Interface that represents a struct data type. Exceptions can have multiple different DataTypeDescriptor objects inside stored as members. Every struct member is identified by a unique name.

Interface ExceptionTypeDescriptor

Functions:

• addMember: This function adds a new TypeDescriptor object as a member using a specific name.
• getMember: This function returns a DataTypeDescriptor object identified by the name introduced as a parameter.
• getMd5: This function returns the Md5 hash string of the exception name.

org.fiware.kiara.typecode.data.Member¶

Interface that represents a member of a MemberedTypeDescriptor object. Each member is identified by its name and the TypeDescriptor object that it holds.

Interface Member

Functions:

• getName: This function returns the member’s name.
• getTypeDescriptor: This function returns a DataTypeDescriptor object stored inside the member.

org.fiware.kiara.typecode.data.EnumMember¶

Interface that represents a member of a EnumTypeDescriptor object. It inherits from Member interface and therefore it has no new methods.

Interface EnumMember

Functions: None

org.fiware.kiara.typecode.data.UnionMember¶

Interface that represents a member of a UnionTypeDescriptor object. It inherits from Member interface and therefore it has no new methods.

Interface UnionMember

Functions: None

org.fiware.kiara.typecode.services.FunctionTypeDescriptor¶

This interface represents a function, providing methods to easily describe it by setting its return type, parameters and exceptions that it might throw.

Interface FunctionTypeDescriptor

Functions:

• getReturnType:This function returns the return DataTypeDescriptor of the function.
• setReturnType: This function sets the return DataTypeDescriptor of the function.
• getParameter: This function returns a DataTypeDescriptor representing a parameter whose name is the same as the one indicated.
• addParameter: This function adds a new DataTypeDescriptor to the parameters list with the name indicated.
• getException: This function returns an ExceptionTypeDescriptor whose name is the same as the one specified as a parameter.
• addException: This function adds a new ExceptionTypeDescriptor to the exceptions list.
• getName: This function returns the function name.
• getServiceName: This function returns the name of the ServiceTypeDescriptor in which the FunctionTypeDescriptor is defined.
• setServiceName: This function sets the name of the ServiceTypeDescriptor in which the FunctionTypeDescriptor is defined.

org.fiware.kiara.typecode.services.ServiceTypeDescriptor¶

This interface represents a service, providing methods to add the FunctionTypeDescriptor objects representing every function defined in a specific service.

Interface ServiceTypeDescriptor

Functions:

• getName: This function returns the service name.
• getScopedName: This function returns the service scoped name.
• getFunctions: This function returns the list of FunctionTypeDescriptor objects stored inside the ServiceTypeDescriptor.
• addFunction: This function adds a FunctionTypeDescriptor to the list of functions defined inside the service.

org.fiware.kiara.dynamic.DynamicValueBuilder¶

This class allows the users to create new data types based on their TypeCode descriptions.

Interface DynamicValueBuilder

Functions:

• createData: This function allows the user to create new DynamicData objects by using their TypeDescriptor.
• createFunctionRequest: This function receives a FunctionTypeDescriptor object describing a function, and it generates a new DynamicFunctionRequest (which inherits from DynamicData) object representing it.
• createFunctionResponse: This function receives a FunctionTypeDescriptor object describing a function, and it generates a new DynamicFunctionResponse (which inherits from DynamicData) object representing it.
• createService: This function receives a ServiceTypeDescriptor object describing a function, and it creates a new DynamicService object representing it.

org.fiware.kiara.dynamic.DynamicValue¶

Interface that acts as a supertype for every dynamic value that can be managed. Every DynamicValue object is defined by using a TypeDescriptor which is used to describe the data. It defines the common serialization functions as well as a function to retrieve the TypeDescriptor object it was created from.

Interface DynamicValue

Functions:

• getTypeDescriptor: This function returns the TypeDescriptor used when creating the DynamicValue object.
• serialize: This function serializes the content of the DynamicValue object inside a BinaryOutputStream message.
• deserialize: This function deserializes the content of a BinaryInputStream message into a DynamicValue object.

org.fiware.kiara.dynamic.data.DynamicData¶

Interface that is used to group all the DynamicValues representing data types.

Interface DynamicData

Functions: None

org.fiware.kiara.dynamic.data.DynamicPrimitive¶

This class allows the users to manipulate DynamicData objects made from PrimitiveTypeDescriptor objects.

Interface DynamicPrimitive

Functions:

• set: This function sets the inner value of a DynamicPrimitive object according to the TypeDescriptor specified when creating it.
• get: This function returns the value of a DynamicPrimitive object.

org.fiware.kiara.dynamic.data.DynamicContainer¶

This class holds the data values of a DynamicData object created from a ContainerTypeDescriptor.

Interface DynamicContainer

Functions: None

org.fiware.kiara.dynamic.data.DynamicArray¶

This class holds the data values of a DynamicData object created from an ArrayTypeDescriptor. A DynamicArray contains a group of DynamicData objects (all must be the same type) stored in single or multi dimensional matrixes.

Interface DynamicArray

Functions:

• getElementAt: This function returns DynamicData object stored in a certain position or coordinate..
• setElementAt: This function sets a DynamicData object in a specific position inside the array. If the array has multiple dimensions, the object will be set in a specific coordinate.

org.fiware.kiara.dynamic.data.DynamicList¶

This class holds the data values of a DynamicData object created from a ListTypeDescriptor. A list can only have one dimension and it has a maximum length. All the DynamicData objects stored inside a DynamicList must have been created from the same TypeDescriptor definition.

Interface DynamicList

Functions:

• add: This function adds a DynamicData object into the list in the last position or in the position specified via parameter.
• get: This function returns a DynamicData object stored is a specific position in the list.
• isEmpty: This function returns true if the DynamicList is empty.

org.fiware.kiara.dynamic.data.DynamicSet¶

This class holds the data values of a DynamicData object created from a SetTypeDescriptor. A set can only have one dimension and it has a maximum length. All the DynamicData objects stored inside a DynamicSet must have been created from the same TypeDescriptor definition and it cannot be duplicated objects.

Interface DynamicSet

Functions:

• add: This function adds a DynamicData object into the list in the last position or in the position specified via parameter.
• get: This function returns a DynamicData object stored is a specific position in the list.
• isEmpty: This function returns true if the DynamicSet is empty.

org.fiware.kiara.dynamic.data.DynamicMap¶

This class holds a list of pairs key-value instances of DynamicData. In a DynamicMap, the key values cannot be duplicated.

Interface DynamicMap

Functions:

• put: This function adds a new key-value pair using the DynamicData objets introduces as parameters. It will return false if the key value already exists in the map.
• containsKey: This function returns true if the DynamicMap contains at least one key-value pair in which the key DynamicData object is equal to the one introduced as a parameter.
• containsValue: This function returns true if the DynamicMap contains at least one key-value pair in which the value DynamicData object is equal to the one introduced as a parameter.
• get: This function returns a DynamicData object from a key-value pair whose key is equal to the one introduced as a parameter.

org.fiware.kiara.dynamic.data.DynamicMembered¶

This class represents a DynamicData type formed by multiple DynamicData objects stored into a class named DynamicMember.

Interface DynamicMembered

Functions: None

org.fiware.kiara.dynamic.data.DynamicStruct¶

This class holds group of DynamicData objects acting as members of a stucture. Each member is identified by its name.

Interface DynamicStruct

Functions:

• getMember: This function returns a DynamicData object (acting as a member of the structure) whose name is the same as the one introduced as a parameter.

org.fiware.kiara.dynamic.data.DynamicEnum¶

This class is used to dynamically manipulate enumerations described by a specific EnumTypeDescriptor object.

Interface DynamicEnum

Functions:

• set: This function sets the actual value of the DynamicEnum object to the one specified as a parameter.
• get: This function returns the actual value of the DynamicEnum object.

org.fiware.kiara.dynamic.data.DynamicUnion¶

This class is used to dynamically manipulate unions described by a specific UnionTypeDescriptor object. A union is formed by some DynamicData objects, and the valid one is selected by using a discriminator.

Interface DynamicUnion

Functions:

• _d: This function either returns the discriminator or sets a new one, depending on the existence of an object parameter indicating a new value.
• getMember: This function returns valid DynamicData value depending on the selected discriminator.
• setMember: This function sets the DynamicData object received as a parameter in the member whose name is the same as the one introduced (if and only if the discriminator value is correct).

org.fiware.kiara.dynamic.data.DynamicException¶

This class holds group of DynamicData objects acting as members of an exception. Each member is identified by its own name.

Interface DynamicException

Functions:

• getMember: This function returns a DynamicData object whose name is the same as the one introduced as a parameter.

org.fiware.kiara.dynamic.data.DynamicMember¶

This class represents a dynamic member of any DynamicMembered object. It is used to store the DynamicData objects inside structures, unions, enumerations and exceptions.

Interface DynamicMember

Functions:

• getName: This function returns the member’s name.
• getDynamicData: This function returns the DynamicData stored inside a DynamicMember object.
• equals: It returns true if two DynamicMember objects are equal.

org.fiware.kiara.dynamic.service.DynamicFunctionRequest¶

This class represents a dynamic function request. This class is used to create objects whose objective is to invoke functions remotely.

Interface DynamicFunctionRequest

Functions:

• getParameter: This function returns a DynamicData object stored in the parameter list depending on its name or its position in such list.
• execute: This function executes a function remotely. It serializes all the necessary information and sends the request over the wire. It returns a DynamicFunctionResponse with the result.
• executeAsync: This function behaves the same way as the function execute. The only difference is that it needs a callback to be executed when the response arrives from the server.

org.fiware.kiara.dynamic.service.DynamicFunctionResponse¶

This class represents a dynamic function response. This class is used to retrieve the information sent from the server after a remote procedure call.

Interface DynamicFunctionResponse

Functions:

• isException: This function returns true if the server raised an exception when executing the function.
• setException: This method sets the attribute indicating that an exception has been thrown on the server side.
• setReturnValue: This function sets a DynamicData object as a return value for the remote call.
• getReturnValue: This function returns the DynamicData representing the result of the remote call.

org.fiware.kiara.dynamic.service.DynamicProxy¶

This class represents a proxy than can be dynamically used to create an instance of DynamicFunctionRequest or a DynamicFunctionResponse depending if the user wants an object to execute a remote call or to store the result.

Interface DynamicProxy

Functions:

• getServiceName: This function returns the service name.
• createFunctionRequest: This function creates a new object instance of DynamicFunctionRequest according to the FunctionTypeDescriptor that was used to describe it.
• createFunctionResponse: This function creates a new object instance of DynamicFunctionResponse according to the FunctionTypeDescriptor that was used to describe it.

org.fiware.kiara.dynamic.service.DynamicFunctionHandler¶

This class represents a dynamic object used to hold the implementation of a specific function. Its process method must be defined by the user when creating the object, and it will be used to register the service’s functions on the server’s side.

Interface DynamicFunctionHandler

Functions:

• process: This function is the one that will be registered to be executed when a client invokes remotely a function. It must be implemented by the user.

org.fiware.kiara.ps.participant.Participant¶

Singleton class representing a node in the network. It might have multiple publishers and subscribers associated to it. This object acts as a supervisor of this node in the network. All the methods in this class will be static, since the constructor will be hidden to the user.

Functions:

• registerTopicDataType:

  This function is used to register new TopicDataType objects in a Participant (network node). The registration acts as a contract defining which data types a publisher is able to understand. It allows the creation of publishers and subscribers that use the registered TopicDataType.

• createPublisher:

  Function to create a new Publisher for a specific TopicDataType object and associate it with a listener.

• createSubscriber:

  Function to create a new Subscriber for a specific TopicDataType object and associate it with a listener.

• removePubisher:

  This function removes a Publisher from this Participant.

• removeSubscriber:

  This function removes a Subscriber from this Participant.

• registerType:

  This function is used to register a TopicDataType in this participant.

org.fiware.kiara.ps.topic.TopicDataType¶

This interface describes the serialization and deserialization procedures of the selected data type. It also defines how the key is obtained from the data object in case the topic is a keyed topic.

Functions:

• serialize:

  This function defines the signature of the serialization functions for every TopicDataType object existing in the framework.

• deserialize:

  This function defines the signature of the deserialization functions for every TopicDataType object existing in the framework.

• createData:

  This function returns a new object of the type represented by the TopicDataType.

• getKey:

  This function is used to return the IntanceHandle object representing the 16-Byte key of the TopicDataType.

org.fiware.kiara.ps.publisher.Publisher¶

This class is the one used to describe a data publisher inside a specific node. It has multiple parameters grouped into a single PublisherAttributes object, which will be detailed later.

It also provides functions to easily change and manipulate the parameters of the publisher, as well as a function to send data over the wire.

Functions:

• getAttributes:

  This function is used to retrieve the PublisherAttributes object contained within this class.

• setAttributes:

  This function is used to set the PublisherAttributes object inside this class.

• write:

  This function is the one used to send data through the network. Its function is to publish information about a specific topic which the publisher is able to use.

• destroy:

  This function is used to delete all the entities associated to this publisher.

org.fiware.kiara.ps.subscriber.Subscriber¶

This class is similar to the Publisher class. All the parameters associated with each subscriber are aggregated into a single SubscriberAttributes object that can be retrieved and changed by using its accessor functions.

Functions:

• getAttributes:

  This function is used to retrieve the SubscriberAttributes object contained within this class.

• setAttributes:

  This function is used to set the SubscriberAttributes object inside this class.

• readNextData:

  This function is used to retrieve an unread CacheChange with the data sent through the network. The data received belongs to a topic the subscriber has subscribed to.

• takeNextData:

  This function is used to retrieve and remove the next unread CacheChange with data receiver over the wire.

• waitForMessage:

  This method blocks the execution thread until a message is received. This message can be retrieved then using the read function.

• destroy:

  This function is used to delete all the entities associated to this subscriber.

org.fiware.kiara.ps.listeners.PublisherListener¶

This interface is designed to be implemented for those classes that ought to manage certain events in the publisher side. It defines a set of methods that can be overwritten by the user to specify the behaviour of the publisher when certain events occur. An example of this would be a new subscriber that has been discovered.

Functions:

• onPublicationMatched:

  This function is the one that will be called when the data published by a publisher matches with the subscriber for a specific topic. The MatchingInfo class provided as a parameter gives the user information about the matched subscriber.

org.fiware.kiara.ps.listeners.SubscriberListener¶

This interface is similar to the PublisherListener interface described above, but in this case it defines a set of methods used to specify the subscriber’s behaviour. An example of this would be a new message that has been received.

Functions:

• onSubscriptionMatched:

  This method’s objective is the same as the one described in the PublisherListener class, but in this case, it will be executed when a new subscription matches with the data a publisher is publishing.

• onNewDataMessage:

  This function will be executed when a new message is received by the subscriber.

org.fiware.kiara.ps.utils.InstanceHandle¶

This class contains the serialized data of a specific message the user is sending or receiving through the network. It provides functions to retrieve the information of such message.

Functions: None

org.fiware.kiara.ps.attributes.TopicAttributes¶

This structure contains all the different attributes of a Topic. These attributes will include the topic name, the data type name and the topic kind.

Attributes:

• topicKind:

  This attribute represents the kind of the Topic (with key or without key)

• topicName:

  This attribute represents the topic name.

• topicDataTypeName:

  This attribute represents the name of the data type for a specific topic.

• historyQos:

  This attribute represents the History QoS.

• resourceLimitQos:

  This attribute represents the limit of the resources for this topic.

org.fiware.kiara.ps.attributes.PublisherAttributes¶

This structure contains all the different attributes of a publisher. These attributes will include the topic attributes (topic name, topic data type, etc), as well as the list of locators, times and writer QoS.

Attributes:

• topic:

  Object instance of TopicAttributes. It holds all the attributes of the Topic.

• wqos:

  Represents the Qualities of Service associated to the Writer.

• times:

  Time values associated to the Publisher entity.

• unicastLocatorList:

  List of unicast locators representing different Endpoints.

• multicastLocatorList:

  List of multicast locators representing different Endpoints.

Functions:

• getUserDefinedID:

  Returns the user defined identifier for this object.

• setUserDefinedID:

  Sets the user defined identifier for this object.

• getEntityId:

  Returns the EntityID that uses this attributes class.

• setEntityId:

  Sets the EntityID that uses this attributes class.

org.fiware.kiara.ps.attributes.SubscriberAttributes¶

This structure contains all the different attributes of subscriber. These attributes will include the topic attributes (name, topic data type, etc), as well as the list of locators, times and reader QoS.

Attributes:

• topic:

  Object instance of TopicAttributes. It holds all the attributes of the Topic.

• rqos:

  Represents the Qualities of Service associated to the Reader.

• times:

  Time values associated to the Subscriber entity.

• unicastLocatorList:

  List of unicast locators representing different Endpoints.

• multicastLocatorList:

  List of multicast locators representing different Endpoints.

• expectsInlineQos:

  This attribute defines whether or not the Subscriber will expect inline QoS.

Functions:

• getUserDefinedID:

  Returns the user defined identifier for this object.

• setUserDefinedID:

  Sets the user defined identifier for this object.

• getEntityId:

  Returns the EntityID that uses this attributes class.

• setEntityId:

  Sets the EntityID that uses this attributes class.

org.fiware.kiara.ps.utils.SampleInfo¶

This class contains information about each particular message, for example the publisher who originated it or a timestamp of its creation time. The GUID of the writer is related to the node from where the information comes from.

Functions:

• getWriterGUID:

  This function is used to obtain the GUID of the writer who originated a specific message.

• getTimestamp:

  This function returns the timestamp value indicating the exact time when the message was created.

org.fiware.kiara.ps.utils.MatchingInfo¶

This class informs the user of whether the event is a matching or an un-matching event and also the global identifier of the remote endpoint.

Functions:

• getMatchingStatus:

  This function allows the users to know the matching status of a specific endpoint with the risen event.

• getRemoteEndpointGUID:

  This function returns the endpoint’s unique identifier.

org.fiware.kiara.ps.common.GUID¶

This class represents a unique identifier of a node in the network. It is formed by two members, a prefix (12 Bytes) and an entity ID (4 Bytes).

Functions:

• getEntityId:

  This function returns the EntityId associated to the GUID.

• getGUIDPrefix:

  This function returns the GUIDPrefix associated to the GUID.

org.fiware.kiara.ps.participant.Participant¶

The public methods of this class are listed below:

org.fiware.kiara.ps.topic.TopicDataType¶

The public methods of this class are listed below:

org.fiware.kiara.ps.publisher.Publisher¶

The public methods of this class are listed below: