Advanced Middleware RPC API Specification¶

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.