A Short Introduction to Brahms Java Activities
April 8, 2005
version 0.2
Charis Kaskiris

 
AKNOWLEDGEMENTS

This mini tutorial was predominately based on notes, feedback, and guidance of Ron Van Hoof and Mike Scott. All errors are of the author.

PURPOSE

The purpose of today's lecture is to introduce the Brahms Java API (BJAPI) with some basic java activities for Brahms and instructions on how to setup and utilitze Eclipse to write java activities for Brahms models. It introduces basic java activities and the generation of random numbers for Brahms objects and agents.

AUDIENCE

The audience for this document is new Brahms modelers who want to get a quick introduction to building java activities in Brahms. Prior knowledge of modeling in Brahms at the level of the Brahms tutorial [tutorial] is assumed. Some familiariy with Java will be assummed.

SOFTWARE

The audience for this document is new Brahms modelers who want to get a quick introduction to building java activities in Brahms. Prior knowledge of modeling in Brahms at the level of the Brahms tutorial [tutorial] is assumed.

SOFTWARE

The software needed to follow this tutorial includes downloading and installing Eclipse [eclipse.org], installing Brahms Professional Agent [resources], and making use of JDK 1.5.x. Brahms Professional Agent comes bundled with the JRE, hence, Eclipse may be setup to make use of the java compiler within the Brahms distribution. It also not necessary to use Eclipse to program java activities. Jave IDEs, like NetBeans [netbeans.org], JBuilder [jbuilder], or JCreator [jcreator] can be alternatively used. The description we follow in this tutorial is with respects to Eclipse.

DOCUMENTATION

Java resources are throughout the net, with the authoritative source been the java.sun.com site. The javadoc for the BJAPI can be found here. The same document can be found in your local Professional Agent installation in directory ProfessionalAgent\docs\vmapi\index.html. Documentation on using Eclipse is provided at the eclipse.org site.

 

PRELIMINARIES

In order to develop Brahms Java activities/agents a set of *.jar files need to be always included in the classpath. These provide the BJAPI classes which that Brahms VM (BVM) makes use of and include the log4j [link] facilities for the BVM. The following jar files need to be included:

  • vm.jar [ProfessionalAgent/Common]
  • common.jar [ProfessionalAgent/Common]
  • log4j-1.2.8.jar [ProfessionalAgent/Common]
  • jacorb.jar [ProfessionalAgent]

When working on a set of java activities, it would make sense to create a package for them. When doing so, choose a package name that make sense for your project. The common naming convention is to use the domain name of your organization followed by the project name, sub-project name, and modules. For example, the naming convention for the Mobile Agents project is gov.nasa.arc.brahms.maa.<module>. The package structure follows the one on your file system.

The java activities are a combination between writing

SETTING UP ECLIPSE FOR BJAPI APPLICATIONS

Download and setup Eclipse following the instructions on the eclipse.org site. Once you have Eclipse 3.0 installed, choose to be in the Java Perspective. Once you have Eclipse properly running, then the following steps will setup a java project that can utilize the Brahms JAPI:

  1. Create a new project (File->New_>Project->Java Project)
  2. Project name: MyActivities (use your own project name instead)
  3. Under Project layout select "Create separate source and output folders"
  4. Press "Configure Details". Select Folders and enter for "Source folder name": 'src' and for "Output folder name": 'build' (without quotes) and press OK.
  5. Press Next and go to the Libraries tab. Add the following libraries using Add External JARs:
    • vm.jar [ProfessionalAgent/Common]
    • common.jar [ProfessionalAgent/Common]
    • log4j-1.2.8.jar [ProfessionalAgent/Common]
    • jacorb.jar [ProfessionalAgent]
  6. Press Finish

Your java project now has access to the BJAPI libraries. In the next steps we look into generating a package structure for your project.

In the Package Explorer go to the project, open it and right mouse click on the src folder and select New->Package. Enter the package name you want to use as discussed in above. This will create the appropriate directory structure in your filesystem. Now you can add classes to that package and compile them. The compiled classes will go into the build directory.

To use the activities/agents in Brahms it is easier to package them up in a jar file. Alternatively you could copy the root of the package directory into the Agents directory, i.e. copy the directories under your build directory to Agents. Creating a jar file is however very easy in Eclipse.
  1. Right mouse click on your project and select Export....
  2. Select JAR file and press next
  3. Use all the defaults and specify the name of the JAR file and the location of the JAR file under "Select the export destination.". A good practice is to create a lib directory under your project and put the jar file in that directory. Under your project you would then have a src, build and lib directory.
  4. Press Next and select on that next step "Save the description ..."
  5. For the description file name choose the same name as your project.
  6. Press Finish (the last step only has advanced features you won't need yet)
  7. Check the lib directory and the jar file should have been generated if your code compiled without a problem.
  8. In Eclipse you have to manually regenerate the jar file when you are ready to test or deploy. To do so just right click on the jardesc entry in your Project Explorer and select "Create Jar". That will regenerate the jar file. You can then copy the jar file into the Agents directory.
These were the basics for getting started with any Java project. Eclipse is setup by default to generate the class files as soon as you change the code. Build All would be unselectable. If that's not how it is setup for you then indeed you will need to do a Build All whenever you are ready to recompile the code. It's a matter of preference.
 
Now when you defined your class in Java, packaged it up and copied it into the Agents directory you can use it in Brahms by declaring it as:
 
    java <activityname>(<parameters>) {
        class: "<packagename>.<classname>";
    }
 
For example:
 
    java myActivity(string input, string output) {
        class: "gov.nasa.arc.brahms.maa.myactivities.MyActivity";

    }

Examples for how to actually implement some basic activities are demonstrated in the next section.

BASIC JAVA ACTIVITIES: AddTwoNumbers.java

Follow the examples in class. {I will add them for you later today}

RANDOM JAVA ACTIVITIES: Uniform.java

Follow the examples in class. {I will add them for you later today}

RANDOM JAVA ACTIVITIES: Gen_Obj_With_Unif_Atr_Val.java

Follow the examples in class. {I will add them for you later today}

BRAHMS CODE FOR CALLING JAVA ACTIVITIES

Follow the examples in class. {I will add them for you later today}

DEBUGGING

Future section.