API: RMI

Remote Method Invocations

Remote method invocations (RMI calls or service calls) are a key concept of las2peer. The idea is that services do one job and do them well and use as many other services as possible to split functionality across the services and increase reusability of data and code. This requires communication between these services.

Service calls are stateless. No data is shared between service calls. More concrete, service calls may be executed on different nodes, as las2peer always chooses the best available service instance to increase throughput and load balancing.

In the usual use case, the executing agent is shared between the calling service and the executed service, which means that the possible actions of the acting agent are the same in both services. As consequence, services should be designed and implemented location independent.

Define service methods

All public methods of the main service class are exposed to other services. Defining a RMI method is as simple as writing

public class MyService extends Service {
  public String getString() {
    return "Hi";
  }

  public MyCustomDataType getCustom() {
    return new MyCustomDataType("Hi");
  }
}

It is also possible to define custom data types as return type, as long as they implement the Serializable interface. To allow other services to use these data types, they should be packaged in its own library and defined as dependency in the calling service, as described here. TODO

Call a service method

If you want to call the method with the current context's main agent as calling agent, use

Serializable Context.get().invoke("i5.las2peer.services.exampleService.ServiceClass@2.3", "myMethod", (int) param1, (String) param2, ...)

The current service agent can also be used as executing entity to handle service-related requests (e.g. metadata):

Serializable Context.get().invokeInternally(String serviceIdentifier, String method, Serializable... parameters)

Do not use invokeInternally for user-related actions as this will bypass las2peer's permission system.

Specifying versions

The first parameter serviceIdentifier of the methods shown above allows to specify a service version to be invoked. Specifying a service version is recommended since a service A might change the API in a newer version and all services invoking service A may break.

Service versions have the format major.minor.sub-build where minor, sub and build are optional. When specifying a version, an appropriate version will be picked as follows: If version 1.0 is specified, all versions starting with 1.0 fit (e.g. 1.0.5-123, but not 1.1). las2peer tries to invoke the newest version that fits to the specified version, but this is not guaranteed as full knowledge of all services is not possible in a p2p network and other factors (e.g. node load, response time, ...) play a role in the service selection.

If no version has been specified (e.g. i5.las2peer.services.exampleService.ServiceClass), any version (= the newest possible version) is used. You should not assume that the newest version will be chosen in this case - especially if there exist many versions in the network.