API

las2peer service API

las2peer defines an own API package (i5.las2peer.api) that services can use to communicate with the las2peer network. This allows preventing services from illegal access to some data. While these pages introduce the concepts, the Javadoc contains a detailed description of all methods.

As of las2peer 0.7, a service does not have full access to the core anymore for security reasons.

Concepts overview

A brief introduction to concepts is given on this page.

Structure of the API

A las2peer service inherits from the abstract Service class (or, in case of a RESTful service, from the RESTService class). This section only deals with plain las2peer services. For details about implementing a web service, please read about RESTful services.

The Service class

The Service class is instantiated once per node. This means, that it will resist across multiple invocations. It is executed by a so called ServiceAgent (read more about agents) which is unique per node and version. To get the current service name and version, you can obtain it from the ServiceAgent (available using Context.get().getServiceAgent()) via the getServiceNameVersion() method.

In the service, all public service methods are exposed to the las2peer network and available for (remote) method invocations (synonym: service call).

The service class has two abstract hooks that can be implemented to start and stop a service:

• onStart() throws ServiceException
• onStop()

These should be used set up the service initially, such as setting up connections. Note that you should never store any user specific data in the service class. Since these hooks are not executed in the service's execution environment, access to the p2p system is limited. Service.getAgent() and Service.getLogger() are available for logging purposes.

Configuration files

If you need a configuration file for your service (e.g. a database connection or other passphrases), you can create a ./etc/your.package.YourServiceClass.properties file and store properties line by line in the format key=value. When setFieldValues() is called, these properties will be parsed to Java types and the corresponding class attributes of your service class will be set to these values. For example, if you have the attribute int myProperty and the property file entry myProperty=5, this value will properly be parsed and made available via the myProperty member.

However, using configuration files makes it impossible to automatically distribute the service over the network (see next section) and thus its use is not recommended.

Self-deploying services vs manual deployment

las2peer is able to start services on nodes in the network and scales up your service automatically. All you have to do is to upload your service to the network as described here.

However, this is not possible for all services. Services relying on one of these features:

• configuration files
• access to the file system
• ...

have to disable self-deployment first by adding the @ManualDeployment annotation to the service class. Those services can still be uploaded to the network, but have to be started manually on a node as described here.

Service environment

Each service call is executed in its own thread. That means, that you cannot start other threads manually. To execute operations asynchronly, there is an Executor set up for the call's thread, which can be obtained via Context.get().getExecutor().

The execution Context

Each service call is bound to a context, which consists of the calling agent (likely the UserAgent of the logged in user), the current service and the executing node. It provides access to the p2p features such as storage access, agents/permission management, invocations and logging.

The current context can be obtained using the static method Context.get() or Context.getCurrent().

The current service class can be obtained using Context.get().getService() or Context.get().getService(MyService.class), which is useful if you use some libraries for abstraction which do not support DI.