Agents Services

Since all acting entities in las2peer are represented as agents, a service is no different. For a basic understanding, think of a service agent as the recipient of a (service) method invocation, called by a user agent for example (see also the tutorial on Users).

The following class represents a small service.
(For information on how your project structure should look like to compile this class, see the project's ReadMe.)

package i5.las2peer.services.myService;
import i5.las2peer.api.Service;
public class MyService extends Service {
   public String theOnlyMethod() {
     return "The Service is working";
   }
}

Starting a service by generating a new service agent

One way to create a service agent is to call the method startService(String serviceNameVersion) on a running node. This method takes a class name and version of the service to start and generates a new agent with a random pass phrase:

1 : Node -1 > startService('i5.las2peer.services.myService.MyService@1.0')

Note that an exact match with the service jar's version is required.

If no agent for this service is present locally, a new agent will be generated and stored to etc/startup/i5.las2peer.services.myService.MyService@1.0.xml by default, the passphrase will be added to etc/startup/passphrases.txt. When starting the service in future, the agent is loaded from there.

If you have an existing agent as XML file, you can put it into the startup folder, name it after the same scheme and add the pass phrase to the file. Your agent will be picked up when starting the service next time.

Starting a service from within a service

Attention: Only for testing! Doing this in production is a bad idea since the core is responsible for deploying services!

We assume here that the service agent is already uploaded to the global storage of the LAS2peer network (for example via the uploadStartupDirectory command). To get the ServiceAgent (i5.las2peer.security.ServiceAgent) instance of a given service, a reference to the current LAS2peer Node (i5.las2peer.p2p.Node) is needed. To get the reference of the LAS2peer node in a service, the method getContext().getLocalNode() must be called.

Node node = this.getActiveNode();

The method getServiceAgent (ServiceNameVersion serviceNameVersion) returns the ServiceAgent reference of the given service class.

ServiceAgent serviceAgent = node.getServiceAgent(ServiceNameVersion.fromString('i5.las2peer.services.myService.MyService@1.0'));

The following statements unlocks the private key of the service agent and starts the service on this node.

serviceAgent.unlockPrivateKey('ServicePassphrase');
node.registerReceiver(serviceAgent);

If the service agent is not uploaded to the global storage of the LAS2peer network, the static method ServiceAgent#createServiceAgent(ServiceNameVersion service, String passphrase) could be called to generate a new service agent.