Welcome to FIWARE Advanced Middleware KIARA documentation!¶

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.

Secure connection to remote service¶

KIARA also provides a way to stablish secure TCP connections with servers running in secure mode. To to so, simply change the connection URL to use TCPS instead of TCP.

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

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

Note that a client running normal (non secure) TCP transport can initialize a connection with a non-secure TCP server, but this does not happen in the opposite way.

Explicitly instanciate and configure Advanced Middleware components¶

This examples shows how to create a direct connection as above, but using a TCP transport and CDR serialization created and configured explicitly by the user.

Context context = Kiara.createContext();
// User instantiates a transport object which can be configured later.
Transport transport = context.createTransport("tcp://192.168.1.18:8080");
// User instantiates a serialization object which can be configured later.
Serializer serializer = context.createSerializer("cdr");
Connection connection = context.connect(transport, serializer);
CalculatorClient client = connection.getServiceProxy(CalculatorClient.class);

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

Providing a service¶

This examples shows how to create a server and add a service to it.

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

// User creates and registers it's implementation of the servant.
Calculator calculator_impl = new CalculatorServantImpl();
service.register(calculator_impl);

// Add the service to the server
server.addService(service, "tcp://0.0.0.0:8080", "cdr");

server.run();

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

Explicitly instanciate and configure Advanced Middleware components¶

This example shows how to provide a service as above, but using a TCP transport and CDR serialization created and configured explicitly by the user.

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

// User creates and registers it's implementation of the servant.
Calculator calculator_impl = new CalculatorServantImpl();
service.register(calculator_impl);

// Transport and Serializer are expicitly created ...
Transport transport = context.createTransport("tcp://0.0.0.0:8080");
Serializer serializer = context.createSerializer("cdr");

// ... and bound to the service when adding it to the server
server.addService(service, transport, serializer);

server.run();

Secure TCP server¶

KIARA allows the server to initialize using a secure TCP layer so that only clients using the same protocol can establish a connection with it.

The transport used to handle secure connections is SSL v3.1 (Secure Sockets Layer) over TLS v1.2 (Transport Layer Security). In order to start a secure server, the only change the user has to take into account is changing the URL of the server so that it uses TCPS instead of TCP.

This example shows how to create a secure server and add a service to it.

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

// User creates and registers it's implementation of the servant.
Calculator calculator_impl = new CalculatorServantImpl();
service.register(calculator_impl);

// Add the service to the server
server.addService(service, "tcps://0.0.0.0:8080", "cdr");

server.run();

Transport and Serialization instances are implicitly created by the connection, based on the string parameters of the addService 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:

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

The public methods of this class are listed below:

org.fiware.kiara.ps.publisher.PublisherListener¶

The public methods of this class are listed below:

org.fiware.kiara.ps.subscriber.SubscriberListener¶

The public methods of this class are listed below:

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

The public methods of this class are listed below:

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

The public methods of this class are listed below:

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

The public methods of this class are listed below:

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

The public methods of this class are listed below:

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

The public methods of this class are listed below:

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

The public methods of this class are listed below:

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

The public methods of this class are listed below:

Interface Header¶

The interface header consists of three elements:

1. An optional modifier specifying if the interface is an abstract interface.
2. The interface name. The name must be preceded by the old OMG IDL 3.5 keyword interface or the new modern keyword service.
3. An optional inheritance specification.

An interface declaration containing the keyword abstract in its header, declares an abstract interface. Abstract interfaces have slightly different rules from regular interfaces, as described in section Abstract interface.

An interface declaration containing the keyword local in its header, declares a local interface. Local interfaces are not currently supported by the FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this, and explain the interface will be used as a regular interface.

Interface Inheritance Specification¶

The syntax for interface inheritance is as follows:

<interface_inheritance_spec> ::= ":" <interface_name> { "," <interface_name> }*
<interface_name> ::= <scoped_name>
<scoped_name> ::= <identifier>
            |   "::" <identifier>
            |   <scoped_name> "::" <identifier>

Each <scoped_name> in an <interface_inheritance_spec> must be the name of a previously defined interface or an alias to a previously defined interface.

Interface Body¶

The interface body contains the following kind of declarations:

• Constant declarations whose syntax is described in section Constant Declaration.
• Type declarations whose syntax is described in section Type Declaration.
• Exception declarations whose syntax is described in section Exception Declaration.
• Attribute declarations whose syntax is described in section Attribute Declaration.
• Operation declarations whose syntax is described in section Operation Declaration.

Abstract interface¶

An interface declaration contains the keyword abstract in its header, declares an abstract interface. The following special rule apply to abstract interfaces:

• Abstract interfaces may only inherit from other abstract interfaces.

Basic Types¶

The syntax for the supported basic types is as follows:

<floating_pt_type> ::= "float"
                   |   "double"
                   |   "long" "double"
                   |   "float32"
                   |   "float64"
                   |   "float128"
<integer_type> ::= <signed_int>
               |   <unsigned_int>
<signed_int> ::= <signed_short_int>
             |   <signed_long_int>
             |   <signed_longlong_int>
<signed_short_int> ::= "short"
                   |   "i16"
<signed_long_int> ::= "long"
                  |    "i32"
<signed_longlong_int> ::= "long" "long"
                      |   "i64"
<unsigned_int> ::= <unsigned_short_int>
               |   <unsigned_long_int>
               |   <unsigned_longlong_int>
<unsigned_short_int> ::= "unsigned" "short"
                     |   "ui16"
<unsigned_long_int> ::= "unsigned" "long"
                    |   "ui32"
<unsigned_longlong_int> ::= "unsigned" "long" "long"
                        |   "ui64"
<char_type> ::= "char"
<wide_char_type> ::= "wchar"
<boolean_type> ::= "boolean"
<octet_type> ::= "octet"
             |   "byte"
<any_type> ::= "any"

Each IDL data type is mapped to a native data type via the appropriate language mapping. The syntax allows to use some OMG IDL 3.5 keywords and to use new modern keyword. For example, FIWARE Middleware IDL supports both keywords: long and i32.

The any type is not supported currently by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this.

Structures¶

The syntax for the struct type is as follows:

<struct_type> ::= "struct" <identifier> "{" <member_list> "}"
<member_list> ::= <member> +
<member> ::= <type_spec> <declarators> ";"

Example of struct syntax:

struct MyStruct {
    i32 f_int;
    string f_str;
    boolean f_bool;
};

Unions¶

The syntax for the union type is as follows:

<union_type> ::= "union" <identifier> "switch"
                 "(" <switch_type_spec> ")"
                 "{" <switch_body> "}"
<switch_type_spec> ::= <integer_type>
                   |   <char_type>
                   |   <boolean_type>
                   |   <enum_type>
                   |   <scoped_name>
<switch_body> ::= <case> +
<case> ::= <case_label> + <element_spec> ";"
<case_label> ::= "case" <const_exp> ":"
             |   "default" ":"
<element_spec> ::= <type_spec> <declarator>

The <scoped_name> in the <switch_type_spec> production must be a previously defined integer, char, boolean or enum type.

Example of union syntax:

union MyUnion switch(i32)
{
   case 1:
      i32 f_int;
   case 2:
      string f_str;
   default:
      boolean f_bool;
};

<enum_type> ::= "enum" <identifier>
                "{" <enumerator> { "," <enumerator> } * "}"
<enumerator> ::= <identifier>

enum MyEnum {
   ENUM1,
   ENUM2,
   ENUM3
};

Template Types¶

Template types are:

<template_type_spec> ::= <sequence_type>
                     |   <set_type>
                     |   <map_type>
                     |   <string_type>
                     |   <wide_string_type>
                     |   <fixed_pt_type>

<sequence_type> ::= "sequence" "<" <simple_type_spec> "," <positive_int_const> ">"
                |   "sequence" "<" <simple_type_spec> ">"
                |   "list" "<" <simple_type_spec> "," <positive_int_const> ">"
                |   "list" "<" <simple_type_spec> ">"

list<string> mylist;
list<string, 32> myboundedlist;

<set_type> ::= "set" "<" <simple_type_spec> "," <positive_int_const> ">"
                |   "set" "<" <simple_type_spec> ">"

set<string> myset;
set<string, 32> myboundedset;

<map_type> ::= "map" "<" <simple_type_spec> ","
                    <simple_type_spec> "," <positive_int_const> ">"
                |   "map" "<" <simple_type_spec> "," <simple_type_spec> ">"

map<i32, string> mymap;
map<i32, string, 32> myboundedmap;

struct MapEntry_<key_type>_<value_type>[_<bound>] {
    <key_type> key;
    value_type> value;
};

typedef sequence<MapEntry_<key_type>_<value_type>[_<bound>][, <bound>]>
   Map_<key_type>_<value_type>[_<bound>];

<string_type> ::= "string" "<" <positive_int_const> ">"
              |   "string"

<wide_string_type> ::= "wstring" "<" <positive_int_const> ">"
                   |   "wstring"

<fixed_pt_type> ::= "fixed" "<" <positive_int_const> "," <positive_int_const> ">"
<fixed_pt_const_type> ::= "fixed"

Complex Types¶

<array_declarator> ::= <identifier> <fixed_array_size>+
<fixed_array_size> ::= "[" <positive_int_const> "]"

i32 myi32array[32];
string mystrarray[32];

Native Types¶

The syntax for native types is as follows:

<type_dcl> ::= "native" <simple_declarator>
<simple_declarator> ::= <identifier>

Native types are not supported by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this and ignore this definition.

Operation attribute¶

The syntax for operation attributes is as follows:

<op_attribute> ::= "oneway"

This attribute is supported in FIWARE Middleware for backward compatibility. But in FIWARE Middleware IDL the preferedby way to define a oneway function is using the @Oneway annotation as described in section Oneway functions.

Parameter Declarations¶

Parameter declarations in FIWARE Middleware IDL operation declarations have the following syntax:

<parameter_dcls> ::= "(" <param_dcl> { "," <param_dcl> }* ")"
                 |   "(" ")"
<param_dcl> ::= [ <param_attribute> ] <param_type_spec> <simple_declarator>
<param_attribute> ::= "in"
                  |   "out"
                  |   "inout"
<raises_expr> ::= "raises" "(" <scoped_name> { "," <scoped_name> }* ")"
<param_type_spec> ::= <base_type_spec>
                  |   <string_type>
                  |   <wide_string_type>
                  |   <scoped_name>

The FIWARE Middleware IDL will not use output parameters, as modern IDLs do. It supports the keywords in, inout, and out, but any FIWARE Middleware IDL parser will inform users all parameters will be input parameters.

Raises Expressions¶

There are two kinds of raises expressions.

<raises_expr> ::= "raises" "(" <scoped_name> { "," <scoped_name> }* ")"

<attr_raises_expr> ::= <get_excep_expr> [ <set_excep_expr> ]
                   |   <set_excep_expr>
<get_excep_expr> ::= "getraises" <exception_list>
<set_excep_expr> ::= "setraises" <exception_list>
<exception_list> ::= "(" <scoped_name> { "," <scoped_name> }* ")"

Context Expressions¶

The syntax for content expressions is as follows:

<context_expr> ::= "context" "(" <string_literal> { "," <string_literal> }* ")"

Context expressions are supported by FIWARE Middleware IDL but not by FIWARE Middleware. Any FIWARE Middleware IDL parser has to inform users about this and it will ignore these expressions.

Annotation Header¶

The header consists of: - The keyword @annotation, followed by an identifier that is the name given to the annotation. - Optionally a single inheritance specification.

The syntax of an annotation header is as follows:

<annotation_header> ::= "@annotation" <identifier> [<annotation_inheritance_spec>]
<annotation_inheritance_spec> ::= ":" <scoped_name>

Annotation Body¶

The body contains a list of zero to several member embedded within braces. Each attribute consists of: - The keyword attribute. - The member type, which must be a constant type <const_type>. - The name given to the member. - An optional default value, given by a constant expression <const_expr> prefixed with the keyword default. The constant expression must be compatible with the member type.

The syntax of annotation body is as follows:

<annotation_body> ::= <annotation_member>*
<annotation_member> ::= <const_type> <simple_declarator>
                        [ "default" <const_expr> ] ";"

Annotation Forwarding¶

Annotations may also be forward-declared, which allow referencing an annotation whose definition is not provided yet.

The syntax of a forwarding annotation is as follows:

<annotation_forward_dcl> ::= "@annotation" <scoped_name>

Member IDs¶

All members of aggregated types have an integral member ID that uniquely identifies them within their defining type. Because OMG IDL 3.5 has no native syntax for expressing this information, IDs by default are defined implicitly based on the members’ relative declaration order. The first member (which, in a union type, is the discriminator) has ID 0, the second ID 1, the third ID 2, and so on.

As described in OMG IDL for X-Types, these implicit ID assignments can be overridden by using the “ID” annotation interface. The equivalent definition of this type is as follows:

@annotation ID {
    attribute ui32 value;
};

Optional members¶

The FIWARE Middleware IDL allows to declare a member optional, applying the “Optional” annotation. The definitions is as follows:

@annotation Optional {
    attribute boolean value default true;
};

The CDR marshalling for this optional members is defined in IDL X-Types standard.

Key members¶

The FIWARE Middleware IDL allows to declare a member as part of the key, applying the “Key” annotation. This will be needed for future pub/sub communication using DDS. The definitions is as follows:

@annotation Key {
    attribute boolean value default true;
};

Oneway functions¶

The FIWARE Middleware IDL allows to declare a function as oneway method, applying the “Oneway” annotation. The definitions is as follows:

@annotation Oneway {
    attribute boolean value default true;
};

Asynchronous functions¶

The FIWARE Middleware IDL allows to declare a function as asynchronous method, applying the “Async” annotation. The definitions is as follows:

@annotation Async {
    attribute boolean value default true;
}