Fork me on GitHub

Run SARL Agent from a Java Program

For running an agent, you must launch this agent on the runtime environment. This document explains how to launch an agent on any SARL Run-time Environment (SRE) from a Java program.

The default SRE is the Janus platform.

1. Definition of the SRE Bootstrap

In the SARL API, a bootstrap is definition is provided. It represents an access point to the SRE from any program. This access point may be used for accessing the features of the underlying SRE, independently of the implementation. In other words, the SRE Bootstrap gives access to the standard SRE functions without forcing you to add an explicit dependency to the SRE Library, e.g. Janus, into your application classpath.

The SARL API defines a SRE bootstrap as:

interface SREBootstrap {
    def getBootAgentIdentifier : UUID
    def isActive : boolean
    def setBootAgentTypeContextUUID
    def setDefaultContextUUID
    def setOffline(boolean)
    def setRandomContextUUID
    def setVerboseLevel(int)
    def startAgent(Class<Agent>, Object[]) : UUID
    def startAgent(int, Class<Agent>, Object[]) : Iterable<UUID>
    def startWithoutAgent : AgentContext
}

A run-time environment, such as Janus must provide a service implementing this bootstrap interface. The standard Java service management feature is used. in other words, the SRE should declare the service implementation into its META-INF/services/io.sarl.bootstrap.SREBootstrap file.

2. Using the SRE Bootstrap

In order to help you to use the bootstrap functions, the SARL API provides a static utility type, named SRE. In the following Java code, the SRE utility type is used for retrieving the bootstrap.

    public class MyProgram {

        public static void main(String[] arguments) {
            SREBootstrap bootstrap = SRE.getBootstrap();
        }

    }

Then, it is possible to use the bootstrap for launching an agent. In the following example, a agent of type MyAgent is launched. Please note that you must not create an instance of an agent by yourself. It is the role of the SARL run-time environment to create this instance for you, with the proper initialization.

    SREBootstrap bootstrap = SRE.getBootstrap();
    bootstrap.startAgent(MyAgent.class)

In the case you want to launch more than one agent programmatically, you could call the startAgent function the number of times you need.

3.  Direct Access to the API of the Janus SRE

Caution: using the API of Janus within your program is not recommended by the SARL team. Prefer to use the Bootstrap API.

The Janus platform provides a Boot class. For launching the platform, you must use this boot class.

The Boot class provides the startJanus function, which permits to launch Janus programmatically.

Let consider you want to launch your agent, defined in the MyAgent class. The following SARL code gives you an example of how to launch this agent in Janus.

The first parameter of the startJanus function is the Java type of the agent to launch.

The second parameter of the startJanus function is the list of parameters to pass with the Initialize event to the launched agent.

The Janus platform enables to launch a single agent at start-up. If you want to launch more agents, please read the next section.

    import io.janusproject.Boot;
    import myprogram.MyAgent;
    public class MyProgram {
        public static void main(String[] args) {
            Boot.startJanus(MyAgent.class, args);
        }
    }

In the case you want to launch more than one agent programmatically, you could use the Kernel instance provided by Janus.

This instance is replied by the startJanus function of the Boot class.

The Kernel type provides the spawn functions, which permit launching an agent programmatically.

The previous example could be updated for launching two agents of the same type. The resulting code is shown below.

The first parameter of the spawn function is the Java type of the agent to launch.

The second parameter of the spawn function is the list of parameters to pass with the [:initevent] event to the launched agent.

that the first agent is launched by the startJanus function, and the second agent is launched by the spawn function.

    import io.janusproject.Boot;
    import myprogram.MyAgent;
    public class MyProgram {
        public static void main(String[] args) {
            Boot.startJanus(MyAgent.class, args);
            janusKernel.spawn(MyAgent.class, args);
        }
    }

4. What's next?

Now, you are ready for developing agents with the SARL language. Please read the rest of the documentation for obtaining more details.

Next>

Copyright © 2014-2018 the original authors or authors.

Licensed under the Apache License, Version 2.0; you may not use this file except in compliance with the License. You may obtain a copy of the License.

You are free to reproduce the content of this page on copyleft websites such as Wikipedia.

Generated with the translator io.sarl.maven.docs.generator 0.8.0.