Home

JaCa-Android is a framework based on the JaCaMo platform that allows for designing and programming Android mobile apps using cognitive agents based on the BDI architecture and the Agents & Artifacts (A&A) environment conceptual model.

In the simplest case, a mobile app in JaCa-Android is programmed as a single standalone Jason BDI agent equipped with all the tools (artifacts) necessary for functioning as a user assistant, including artifacts for the UI, for modeling and accessing the user context, the device context, as well as to exploit the mobile environment facilities and services (based on Android in this case).

Hello World - The How/To guide

After having included the JaCa-Android library into your project (see README.md), consider following steps in order to use JaCa-Android.

NOTE: In the following description we assume you have already created a standard android project with an application module called app

[1] MAS SETUP

Add a res folder called resources (ensure that such folder is created at the same level of the standard android res folder. Create into this folder a sub folder with the same name you want to give to your MAS (we assume helloworld). This folder will be the parent of your MAS configuration (*.mas2j) and agents' code (*.asl)

Create into the folder the MAS2J, e.g. as follows (into resources/helloworld/project.mas2j)

MAS helloworld{
  infrastructure: Centralised
  
  environment: jaca.CartagoEnvironment("infrastructure")

  agents:
    main mainAgent agentArchClass jaca.CAgentArch;

    aslSourcePath: "helloworld/agents";
}

Note that the MAS name must be the same of the created folder within the resources one - helloworld in this case. Moreover the path must be specified for aslSourcePath is the path within the MAS dedicated folder where agents' code will be found - in this case resources/helloworld/agents/

[2] AGENTS' CODE

Add the agent (or agents) code (e.g., for the specified mainAgent agent into resources/helloworld/agents/mainAgent.asl)

!init.

+!init
  <-  makeArtifact("mainUI", "it.unibo.pslab.jaca_android.helloexample.MainUI",[],MainUI);
      focus(MainUI).

+ui_ready [artifact_name(Id,MainUI)]
  <- println("MainUI ready.").

[3] UI ARTIFACTS' CODE

Android activities can be managed as artifacts. In particular, the previous agent creates the MainUI artifact into the android app default package (its code in the MainUI.java file)

package it.unibo.pslab.jaca_android.helloexample;

import cartago.INTERNAL_OPERATION;
import it.unibo.pslab.jaca_android.core.ActivityArtifact;
import it.unibo.pslab.jaca_android.core.JaCaBaseActivity;
import android.widget.TextView;

public class MainUI extends ActivityArtifact {
    
    /* 
     * You must include a static reference to an Android activity extending JaCaBaseActivity class
     * in each Activity Artifact (declare also this activity into the android manifest)
     */
    public static class MainActivity extends JaCaBaseActivity {}

    /*
     * Inits the artifact, with the reference to the static activty and the reference to the layout file
     */
    public void init() {
        super.init(MainActivity.class, R.layout.activity_main, true);
    }

    /*
     * Allows for all operations generally added to the onCreate() callback of an activity AFTER the UI inflating
     */
    @INTERNAL_OPERATION
    protected void setup() {
        initUI();
    }

    private void initUI(){
        execute(() -> {
            TextView label = (TextView) findUIElement(R.id.textview);
            label.setText("Hello, JaCa-Android!");
        });
    }
}

In above example, note (1) the decalration of the static instance of the related activity, (2) the usage of method init() and setup(), (3) the usage of the method execute() allowing to demand a portion of code to the main thread (e.g. to update the UI). Note also that Android layouts can be defined like in standard Android app, using XML res files accessed programmatically through the R instance.

[4] The App Manifest

Add to the manifest the meta-data related to the MAS.

<meta-data
  android:name="mas2j"
  android:value="/helloworld/project.mas2j" />

Declare the Main Activiy and the MAS Service. This is a standard setup for all JaCa-Android project.

<service 
  android:name="it.unibo.pslab.jaca_android.MasService" />

<activity
  android:name="it.unibo.pslab.jaca_android.LauncherActivity"
  android:label="@string/app_name">
  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity>

Notes about the lifecycle of a MAS in JaCa-Android The LauncherActivity activates the MAS Service which is responsible for MAS creation and running according to the MAS2J file. Then, such activity is automatically closed, assuming one agent will be responsible for the creation of an ActivityArtifact (the MainUI of the example).

Finally, declare into the manifest all others Activity declared within all activity artifacts.

<activity
  android:name="it.unibo.pslab.jaca_android.core.JaCaBaseActivity"
  android:label="@string/app_name" />

<activity
  android:name=".MainUI$MainActivity"
  android:label="@string/app_name" />

Note you must also declare once the JaCaBaseActivity to be recognised by Android O.S.

[5] Run the App

That's all, you can build and run the App using the emulator or a physical device. You can find this example into the JaCa-Android-HelloExample folder of this repository.