Building & Deploying ASTRA Programs

The Quick Start showed how to create and run an ASTRA project using the Maven archetype. This guide explains what is going on in more detail: how to set up a project without the archetype, how the ASTRA build works, and how to choose which agent program is run and what the first agent is called.

You will need a JDK (1.8 or later) and Maven 3.3+, as described in the Quick Start.

Creating a project from scratch

In a project directory of your choosing, create the following directory structure (for example, on *nix systems, type mkdir -p src/main/astra):

|-- src
|    |-- main
|          |-- astra
|-- pom.xml

Now create the maven build file (pom.xml):

<project xmlns="http://maven.apache.org/POM/4.0.0"
		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>examples</groupId>
	<artifactId>hello</artifactId>
	<version>0.1.0</version>

    <parent>
        <groupId>com.astralanguage</groupId>
        <artifactId>astra-base</artifactId>
        <version>2.0.13</version>
    </parent>

    <build>
        <defaultGoal>clean compile astra:deploy</defaultGoal>
        <plugins>
            <plugin>
                <groupId>com.astralanguage</groupId>
                <artifactId>astra-maven-plugin</artifactId>
                <version>2.0.13</version>
            </plugin>
        </plugins>
    </build>
</project>

You should change the groupId and artifactId to reflect your own project.

Alternatively, the Quick Start shows how to generate the same project structure using the ASTRA Maven archetype.

How ASTRA builds work

ASTRA code is compiled into Java code prior to deployment by the ASTRA compiler, which can be invoked by using the astra:compile goal. The compiler converts each agent program (a .astra file) into a Java class that is created in the target/gen/java folder. Once all the agent programs have been compiled into Java classes, the ASTRA compiler then compiles the Java code with the class files being added to the target/classes folder.
ASTRA code is designed to closely correspond to Java code. This includes adopting the Java package model. Programs written in the src/main/astra folder are considered to be in the default package. Programs written in subfolders of that folder as considered to be in named packages and, like Java, the program must include a package declaration. For example, the following program: src/main/astra/soccer/Defender.astra is in the soccer package and so should include the following declaration at the top of the agent program: package soccer;
Each generated Java program includes a main() method that can be used to run the agent independently. This method: sets up a scheduling policy for the platform; creates an instance of the agent (with a default name: main); and gives the agent an initial goal of the form !main(list args) where the args parameter is a list containing any values passed to the main() method when the program is launched.
ASTRA programs can be run using the astra:deploy Maven goal. This goal assumes that there is an agent program with name Main in the default package (the src/main/astra folder) of the codebase. You can override this by setting the astra.main property in maven. For example, the code below would use the soccer.Manager agent program as a starting point.

<properties>
    <astra.main>soccer.Manager</astra.main>
</properties>

Other properties you can set here include:

astra.name can be used to specify the name to be given to the first agent created (by default, this agent is called main)

The build file includes a default goal, so running mvn in the project root folder is the same as running:

mvn clean compile astra:deploy

Understanding the Hello World program

The Main.astra agent program created by the archetype (or that you can create yourself in the src/main/astra folder) looks like this. Main.astra is the default file searched for by the ASTRA compiler plugin; you can use other filenames, as shown below.

src/main/astra/Main.astra

agent Main {
    module Console C;

    plan +!main(list args) {
        C.println("Hello World, ASTRA");
    }
}

There are a few things to note:

The agent keyword is a lot like the Java class keyword, in fact, the syntax is very similar – this is done purposefully to make writing ASTRA code more familiar.
The agent keyword declares a new agent program whose name/id matches the name of the file (the Main agent program is in the Main.astra file).
The module statement declares that an instance of the astra.lang.Console class (the package is inferred just like Java infers that the Object class is actually java.lang.Object) will be created. This class implements an ASTRA API (a set of methods that implement functionality that can be used in the ASTRA program).
The plan statement declares an agent behaviour. Each plan defines how an agent responds to an event in a context. Here, the event is the +!main(...) event which is generated when an agent program is executed (it is the ASTRA equivalent of a main() method). The above plan does not provide a context, meaning that the plan is always applicable. We will see an example of a context later.
The Console API class provides a series of methods that support input/output from/to the console. In the example, the agent prints out “Hello World, ASTRA”.

Running a “non-default” Agent Program

By default, the astra:deploy goal is configured to run the Main.astra agent program. We can override this by setting the astra.main property either in the maven build file or at the command prompt.

To see an example of how to do this, create a new agent program called Namey.astra and place it in the default package (src/main/astra).

src/main/astra/Namey.astra

agent Namey {
    module Console console;
    module System system;

    plan +!main(list args) {
        console.println("Hello World, "+system.name());
    }
}

This program differs from the previous program in 3 ways:

The name of the agent program is Namey this has been changed to match the name of the file that the agent program was written in.
We have added a second module – the System module.
The println(....) statement uses the System module to get the name of the agent which is included in the output.

To run the program, you can either add a properties setting to the maven build file:

<properties>
    <astra.main>Namey</astra.main>
</properties>

Alternatively, you can override the default agent program name at the command line:

mvn -Dastra.main=Namey

This should result in the following output:

[main] Hello World, main

Notice that the name of the agent appears in two places. The left-hand occurrence is to enable you to know which agent is generating output. The right-hand occurrence is due to the code we wrote above.

As a second step, we can also change the name of the default agent. We do this by overriding the default value for astra.name. Again, we can do this in the properties section of the pom.xml file:

<properties>
    <astra.main>Namey</astra.main>
    <astra.name>George</astra.name>
</properties>

Or we can do this at the command line:

mvn astra:deploy -Dastra.main=Namey -Dastra.name=George

The output of this would be:

[George] Hello World, George

Summary

You have now seen how an ASTRA project is structured, how it is built and deployed, and how to customise the start-up process to change the main agent program and the main agent name.