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 getKernelLogger : Logger
	def getService(Class<Object>) : Object
	def getUniverseContextUUID : UUID
	def getUniverseSpaceUUID : UUID
	def isActive : boolean
	def isRunning : boolean
	def setBootAgentTypeContextUUID
	def setOffline(boolean)
	def setRandomContextUUID
	def setSpecificContextUUID
	def setUniverseContextUUID(UUID)
	def setUniverseSpaceUUID(UUID)
	def setVerboseLevel(int)
	def shutdown
	def shutdown(boolean)
	def startAgent(Class<Agent>, Object[]) : UUID
	def startAgent(int, Class<Agent>, Object[]) : Iterable<UUID>
	def startAgentWithID(Class<Agent>, UUID, Object[])
	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.</importantnote> 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>](../index.html) ##5. Legal Notice * Specification: SARL General-purpose Agent-Oriented Programming Language ("Specification") * Version: 0.10 * Status: Stable Release * Release: 2019-10-26 > Copyright © 2014-2019 [the original authors or authors](http://www.sarl.io/about/index.html). > > 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](http://www.apache.org/licenses/LICENSE-2.0). > > 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.10.0.