Dev Guide


Contents:


This document explains how to use JaCa-Web framework to develop a simple client-side Web application on top of an agent-oriented platform. To undestand following guidelines it’s strongly recommended at least a basic knowledge Jason language (and platform) and CArtAgO framework. If you don’t know these technologies, you can find a lot of references in Documents page.


To develop a Web application using JaCa-Web you need:

  • A Web browser as Mozilla Firefox 3.x, Google Chrome or IE 8+ (Safari is not well supported yet).
  • Java Plugin 1.4 or higher installed on your browser.
  • JaCa-Web framework, which include some technologies as:
    • Jason
    • CArtAgO
    • C4Jason
    • LiveConnect
    • HTTPCoreApi


To download a distribution of JaCa-Web visit sourceforge page of the project at http://sourceforge.net/projects/jaca-web/.


A JaCa-Web application is physically composed by three parts:

  1. A web page developed by standard HTML + JavaScript programming languages and techniques.
  2. The Applet part of JaCa-Web contained in differents jars: app.jar, jaca-web.jar, jason.jar, cartago.jar, c4jason.jar, liveconnect.jar, httpcore.jar.
  3. The JavaScript part of JaCa-Web contained in jaca-web.js which provide a communication layer between JavaScript and Applet using LiveConnect functionalities.

To develop this kind of application, you can follow these guidelines:

  1. According to MVC design pattern, our Web application developed using JaCa-Web can be designed splitting “View” part from business logic of “Control” part. As an example, first of all you can develop the “View” part of the application:
    1. Developing the UI means writing an html page (index.html for example) and one or more JavaScript files (index.js, etc.) where you can define some functions for dynamic page access and modification (as an example: getInput1():return_type, setOutput1(out_type):void, etc.). You can use all common tecnhologies and mechanisms for Web programming during this phase, but you should think to this part as a “View” part, in the same way you usually design GUI in a common desktop application.
    2. Second, you have to include JaCa-Web in this page (index.html):
      • Include jaca-web.js script, which enable JaCa-Web communication between page and applet:
      <script type="text/javascript" src="script/jaca-web.js"></script>
      • Also include JaCa-Web framework as Java applet (usually in the bottom of the page). You can do it adding following lines:
    3. <applet id="jacaweb" code="jacaweb.JacaWebRunner.class"
             archive="app.jar, jaca-web.jar, jason.jar, cartago.jar,
                      c4jason.jar, httpcore.jar"
             width="0" height="0" MAYSCRIPT='true' >
      
      	<PARAM name="mas2j_path"
                           value="path_of_mas2j_file_inside_app.jar" />
      
      	<PARAM name="page_artifact_name"
                           value="name_of_myPageArtifact" />
      
      	<PARAM name="page_artifact_class"
                           value="class_and_package_of_myPageArtifact" />
      
      </applet>

      You’ll understand the meaning of all parameters following next points of this guidelines. Now, in the same directory of index.html you must put all jars specified in this applet tag (in this example are applet.jar,jason.jar,cartago.jar,c4jason.jar,liveconnect.jar,httpcore-4.0-beta1.jar). Applet id must be always “jacaweb”, allowing jaca-web.js script finding it.

    4. Third step is to develop a MyPageArtifact as a CArtAgO artifact equivalent of the page. You can do it extending the abstract artifact jacaweb.PageArtifact, included in JaCa-Web framework. MyPageArtifact should offer some high level operations and observable properties that describe at this high level the UI. Every operation is implemented using functions provided by index.js script, through a method of the abstract artifact PageArtifact called void executeJSFunction(String function_name,Object … args) . Since now, the “Control” part of the application, developed using Jason language and agent paradigm, will interact with UI only through this artifact.
  2. Now, you should develop agents and artifacts specifics for the application, implementig its business logic. You can do it using Jason and CArtAgO infrastructure, as you can do for a non-Web application,  where MyPageArtifact resolves most of problems of interaction with the Web page. Some points where you should pay attention are:
    • All classes and resources (.asl and .mas2j files) of the project must be wrapped by app.jar. No files of the Jason project must be placed in the same root of index.html and outside this jar (this is because JaCa-Web make use of Java Applet).
    • Defining mas2j file of Jason project, according to Jason specifications, you must specific the .asl source path through this line:
      [...]
        aslSourcePath: "asl_files_path";
      [...]
  3. Deployment of this kind of Web application developed using JaCa-Web is totally similar to a common HTML + JavaScript + Java Applet web page. You have just to upload all content (.html, .js and .jar files) on a Web Server and you can access the application using every Web browser (Safari is not yet well supported). Finally, we must remarks that JaCa-Web make use of a particular type of Java Applet, called “Signed Applet”, which require an explicit acceptance of the user before starting execution.
preload preload preload