<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:svg="http://www.w3.org/2000/svg"
      xmlns:mml="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook">
  <title>GaviaLib Manual</title>

  <chapter>
    <title>GaviaLib</title>

    <section>
      <title>Agents and World</title>

      <para>TODO intro to agent dev</para>
    </section>

    <section>
      <title>Library architecture</title>

      <para><mediaobject>
          <imageobject xml:id="libraryArchitectureImg">
            <imagedata fileref="../../../docs/documentation/architecture/media/LibraryArchitecture.svg"
                       format="SVG"></imagedata>
          </imageobject>
        </mediaobject></para>

      <section>
        <title>Agent types</title>

        <para></para>
      </section>

      <section>
        <title>Logging</title>

        <para>Each instance of Agent has one big physical Logger, all log
        messages are send to this log.</para>

        <para>There are four default types of logs:</para>

        <para><variablelist>
            <varlistentry>
              <term>In log</term>

              <listitem>
                <para>Logs all messages received from the environment.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Out log</term>

              <listitem>
                <para>Logs all command send to the environment.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>User log</term>

              <listitem>
                <para>Log records issued by the user programmer go into this
                log.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Platform log</term>

              <listitem>
                <para>For logging of internal messages of the PogamutBASE
                library.</para>
              </listitem>
            </varlistentry>
          </variablelist>Messages from this global log are distributed to the
        logical logs by set of filters. Each filter is registered to the main
        logger through an associated Handler. Handler is responsible for
        publishing the log record (see
        http://java.sun.com/developer/technicalArticles/Using/index.html for
        details of Java Logging API). Type of the log message is determined by
        the type of objects included with the LogRecord (see
        LogRecord.getParameters()). This code shows how to set up new user log
        handler publishing the log records to the console:</para>

        <para><programlisting>Handler userLogHandler = new ConsoleHandler();
userLogHandler.setFilter(new UserFilter());
log.addHandler(userLogHandler);</programlisting><code></code></para>
      </section>

      <section>
        <title>Exceptions</title>

        <para>Mediator creates ExceptionMessage</para>

        <para>Superclass of all Pogamut exceptions is PogamutException.</para>
      </section>

      <section>
        <title>WorldView</title>

        <para></para>

        <section>
          <title>Native Worlds</title>

          <para></para>

          <para><mediaobject>
              <imageobject>
                <imagedata fileref="../../../docs/documentation/architecture/WorldViewNative.svg"
                           format="SVG"></imagedata>
              </imageobject>
            </mediaobject></para>
        </section>

        <section>
          <title>External Worlds</title>

          <para>External worlds are those worlds that runs separately from JVM
          of your agents (if compared with Native worlds). Therefore they
          require some sort of communication between your agent and the world.
          It follows client-server paradigm, so we consider the the agent to
          be a client and the world to be a server. External worlds are
          connected through some sort of message communication (via socket
          communication for instance). This leads to question how those
          messages should look like and how to implement it's parser (into
          some sort of Java objects). Here comes the Pogamut base library that
          is defining it's own format how every text message looks like
          (inside one XML file) and gives you tools (a few xslt
          transformations) for transformation of this message definiton (XML
          file) into Java classes and a parser (Yylex generated usind
          JFlex).</para>

          <para>We think about external world as something that defines a text
          message protocol allowing a client to create a new bot inside the
          world (new body, avatar, entity, whatever you like) and then treats
          the client as the brain of the new bot. That means the world will
          feed the brain (client) with sensory informations and events what is
          happening around the bot inside the world and expects the brain
          (client) to send commands for the bot's body (what to do in the
          world). Note that this abstraction is not limited to 3D virtual
          worlds but applies to the internet as well (for instance) - the
          world may implement a search engine + provide commands for
          communication with other bots, bots may then connect to different
          HTTP server and communicate with them. So there are two types of
          messages in the protocol: information messages (that goes from the
          world to brain) and command messages (that goes from brain to the
          world).</para>

          <para>Note that it is teadious task to implement parser for
          information messages for yourself and write wrappers for commands
          that serialize the commands into Strings. This is were Pogamut XML
          pipeline will come at hand allowing you to define all protocol
          messages. Once the definition is complete you may transform it via
          Pogamut's XSLT files into Java wrappers (information messages as
          well as commands) + Yylex (parser of the information messages, uses
          JFlex). Even more it will create a DocBook documentation of those
          messages for you so you may keep your webpage about the project up
          to date with the last release.</para>

          <para>Types of the messages:</para>

          <variablelist>
            <varlistentry>
              <term>Text message</term>

              <listitem>
                <para>plain messages of the protocol</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>InfoMessageObject</term>

              <listitem>
                <para>Java wrappers of the plain text messages.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>CommandObject</term>

              <listitem>
                <para>Java wrappers for commands, implements serialization
                into Strings.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>WorldEvent</term>

              <listitem>
                <para>sometimes more info message objects are agregated into
                one WorldEvent (eg. path in the world is sent asi a sequence
                of respective navigation points of the navigation graph
                wrapped with messages path start and path end)</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>WorldViewEvent</term>

              <listitem>
                <para>Events that describe the world to the Agent. Only this
                type of events is accessible to the Agent</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <mediaobject>
            <imageobject>
              <imagedata fileref="../../../docs/documentation/architecture/WorldViewNative.svg"
                         format="SVG"></imagedata>
            </imageobject>
          </mediaobject>

          <section>
            <title>Text messages</title>

            <para>This is cruicial part of the Pogamut and serves for the
            definition of the format of text messages</para>

            <para></para>
          </section>

          <section>
            <title>XML pipeline</title>

            <para></para>

            <section>
              <title>XML Messages definition file</title>

              <para>File MessageObjectsList.xml defines all messages of the
              protocol. This file is transformated to Java objects, Yylex
              parser and DocBook documentation.</para>

              <para>The document starts by declaring that it's doctype is
              Messages.dtd. This DTD defines all elements that could be used
              for definitions of messages.</para>

              <para>The root node <code>&lt;messages&gt;</code> contains three
              main tags:</para>

              <para><variablelist>
                  <varlistentry>
                    <term>&lt;settings&gt;</term>

                    <listitem>
                      <para><variablelist>
                          <varlistentry>
                            <term>&lt;javasettings&gt;</term>

                            <listitem>
                              <para>Settings used for generation of Java sources
                              goes here.</para>

                              <para><variablelist>
                                  <varlistentry>
                                    <term>&lt;javapackageinfomessages
                                    package="..."/&gt;</term>

                                    <listitem>
                                      <para>Declares package for all info objects.</para>
                                    </listitem>
                                  </varlistentry>

                                  <varlistentry>
                                    <term>&lt;javapackagecommands
                                    package="..."/&gt;</term>

                                    <listitem>
                                      <para>Declares package for all command
                                      objects.</para>
                                    </listitem>
                                  </varlistentry>

                                  <varlistentry>
                                    <term>&lt;javaimport import="..." /&gt;</term>

                                    <listitem>
                                      <para>Imports a package/class to all objects.</para>
                                    </listitem>
                                  </varlistentry>
                                </variablelist></para>
                            </listitem>
                          </varlistentry>

                          <varlistentry>
                            <term>&lt;jflexsettings&gt;</term>

                            <listitem>
                              <para>Setting of the generated Yylex.java file.
                              There can be a list of <code>&lt;javaimport
                              ...&gt;</code> tags.</para>
                            </listitem>
                          </varlistentry>
                        </variablelist></para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>&lt;infomessages&gt;</term>

                    <listitem>
                      <para>Root tag for all info messages.</para>

                      <para><variablelist>
                          <varlistentry>
                            <term>&lt;messageobject&gt;</term>

                            <listitem>
                              <para>Tag representing one message of the protocol.
                              It's attributes are:</para>

                              <para><itemizedlist>
                                  <listitem>
                                    <para>extends - A Java class that will be used as
                                    aan ancestor of this message object</para>
                                  </listitem>

                                  <listitem>
                                    <para>message - Short abbreviation of the message,
                                    usually three or four uppercase letters</para>
                                  </listitem>

                                  <listitem>
                                    <para>name - Long name of the message, will be used
                                    as a class name</para>
                                  </listitem>
                                </itemizedlist><variablelist>
                                  <varlistentry>
                                    <term>&lt;documentation&gt;</term>

                                    <listitem>
                                      <para>Long description of the message and it's
                                      usage. It will be used for Javadoc and also
                                      standalone documentation of the protocol. DocBook
                                      tags can be for formatting the documentation.</para>

                                      <para><variablelist>
                                          <varlistentry>
                                            <term>&lt;meta&gt;</term>

                                            <listitem>
                                              <para>The meta tag can be used for various purposes.
                                              Eg. groups of messages can be defined this way. It
                                              is annotation that can be processed in user defined
                                              way.</para>

                                              <para><itemizedlist>
                                                  <listitem>
                                                    <para>name - name of the meta property</para>
                                                  </listitem>

                                                  <listitem>
                                                    <para>value - value of the property</para>
                                                  </listitem>
                                                </itemizedlist></para>
                                            </listitem>
                                          </varlistentry>
                                        </variablelist></para>
                                    </listitem>
                                  </varlistentry>

                                  <varlistentry>
                                    <term>&lt;implements&gt;</term>

                                    <listitem>
                                      <para><itemizedlist>
                                          <listitem>
                                            <para>interfaces - list of interfaces implemented by
                                            this message object</para>
                                          </listitem>
                                        </itemizedlist></para>
                                    </listitem>
                                  </varlistentry>

                                  <varlistentry>
                                    <term>&lt;property&gt;</term>

                                    <listitem>
                                      <para>Data field of the message. The
                                      &lt;property&gt; tag should contain nested
                                      &lt;documentation&gt; tag describing the semantics
                                      of this property.<itemizedlist>
                                          <listitem>
                                            <para>name - name of the property</para>
                                          </listitem>

                                          <listitem>
                                            <para>type - Java type of the property</para>
                                          </listitem>

                                          <listitem>
                                            <para>jflex - optional parameter, if it is present
                                            and set to value <code>NO</code> then no jflex code
                                            will be generated for this property and it's value
                                            won't be set by the parser. This parameter is
                                            usually used in conjuction with the
                                            <code>&lt;extra&gt;&lt;code&gt;&lt;java&gt;</code>
                                            where can be defined custom methods.</para>
                                          </listitem>
                                        </itemizedlist></para>
                                    </listitem>
                                  </varlistentry>

                                  <varlistentry>
                                    <term>&lt;extra&gt;</term>

                                    <listitem>
                                      <para></para>

                                      <para><variablelist>
                                          <varlistentry>
                                            <term>&lt;code&gt;</term>

                                            <listitem>
                                              <para></para>

                                              <para><variablelist>
                                                  <varlistentry>
                                                    <term>&lt;java&gt;</term>

                                                    <listitem>
                                                      <para>Code from this section will inserted into the
                                                      body of generated Java class.</para>
                                                    </listitem>
                                                  </varlistentry>
                                                </variablelist></para>
                                            </listitem>
                                          </varlistentry>
                                        </variablelist></para>
                                    </listitem>
                                  </varlistentry>
                                </variablelist></para>

                              <para></para>
                            </listitem>
                          </varlistentry>
                        </variablelist></para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>&lt;commandmessages&gt;</term>

                    <listitem>
                      <para>Root tag for all command messages.</para>

                      <para><variablelist>
                          <varlistentry>
                            <term>&lt;messageobject&gt;</term>

                            <listitem>
                              <para>The same tag is used for describing the
                              messageobjects and commandobjects. The only
                              difference is that property@jflex attribute has no
                              meaning since the command aren't parsed by the
                              jflex.</para>
                            </listitem>
                          </varlistentry>
                        </variablelist></para>
                    </listitem>
                  </varlistentry>
                </variablelist></para>

              <para></para>

              <para>Example of one simple XML protocol definition
              follows:<code></code></para>

              <para><programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE gbmessages SYSTEM "Messages.dtd"&gt;

&lt;!-- List of all GB messages and commands !--&gt;
&lt;messages&gt;
    &lt;!-- List of settings for the tools / output --&gt;
    &lt;settings&gt;
        &lt;!-- settings for the Java part of the messages --&gt;
        &lt;javasettings&gt;
            &lt;!-- package where the message objects belong to --&gt;
            &lt;javapackageinfomessages package="cz.cuni.pogamut.example.messages.infomessages" /&gt;
            &lt;javapackagecommands package="cz.cuni.pogamut.example.messages.commands" /&gt;

            &lt;!-- follows the list of classes that will be imported for each message --&gt;
            &lt;javaimport import="java.util.*" /&gt;
        &lt;/javasettings&gt;

        &lt;!-- settings for the JFlex part of the messages --&gt;
        &lt;jflexsettings&gt;
            &lt;!-- follows the list of classes that will be imported to Yylex.java --&gt;
            &lt;javaimport import="java.util.*" /&gt;
            &lt;javaimport import="javax.vecmath.*" /&gt;
        &lt;/jflexsettings&gt;
    &lt;/settings&gt;

    &lt;!-- Info messages are comming from the server to the client. !--&gt;
    &lt;infomessages&gt;
        &lt;messageobject extends="InfoObject" message="INF"
                   name="Info"&gt;                   
            &lt;!-- DocBook tags can be used inside &lt;documentation&gt; tag. If you arent familiar
            with DocBook then refere to www.docbook.org !--&gt;
            &lt;documentation&gt;
                Simple message with id and text data.
                &lt;meta name="msgtype" value="Configure"/&gt;
                &lt;meta name="section" value="Client"/&gt;
            &lt;/documentation&gt;
      
            &lt;!-- List of implemented interfaces. --&gt;
            &lt;implements interfaces="IWorldEvent, IWorldViewEvent"/&gt;

            &lt;!-- List of all properties of this message. !--&gt;
            &lt;property name="id" type="int"&gt;
                &lt;documentation&gt;Unique message ID.&lt;/documentation&gt;
            &lt;/property&gt;
            &lt;property name="text" type="String"&gt;
                &lt;documentation&gt;The text carried by this message.&lt;/documentation&gt;
            &lt;/property&gt;

            &lt;!-- Extra information used by different modules of the Pogamut platform. !--&gt;
            &lt;extra&gt;
                &lt;code /&gt;
            &lt;/extra&gt;
        &lt;/messageobject&gt;
    &lt;/infomessages&gt;
    
    &lt;commandmessages&gt;
        &lt;commandobject command="ACK" extends="CommandObject" name="Acknowledge"&gt;
            &lt;documentation&gt;
                Acknowledge that a message was received.
                &lt;meta name="msgtype" value=""/&gt;
                &lt;meta name="section" value="Server"/&gt;
            &lt;/documentation&gt;

            &lt;!-- List of all properties of this command. !--&gt;
            &lt;property name="id" type="int"&gt;
                &lt;documentation&gt;ID of a message that was received.&lt;/documentation&gt;
            &lt;/property&gt;
         

            &lt;!-- Extra information used by different modules of the Pogamut platform. !--&gt;
            &lt;extra&gt;
                &lt;code /&gt;
            &lt;/extra&gt;
        &lt;/commandobject&gt;
    &lt;/commandmessages&gt;
&lt;/messages&gt;
        </programlisting>This example shows protocol with two commands that
              can be used to build simple reliable communication chanel. The
              <code>INF</code> is used for sending information from the server
              to the client and the <code>ACK</code> message is used by the
              client to acknowledge, that he has received the message. For now
              will we be interested only in the XML definition of these
              messages.</para>
            </section>
          </section>
        </section>
      </section>

      <section>
        <title>Agent's Memory</title>

        <para>The basic class for perceiving the world is the WorldView.
        However this object shows only the current state of the world. In
        order to remember the past state you can:</para>

        <para><itemizedlist>
            <listitem>
              <para>Use custom mechanism - store information to internal
              variables of the agent, this approach is best for simple or
              nonstandard tasks</para>
            </listitem>

            <listitem>
              <para>Use utility memory classes - "memory object" accustomed to
              specific needs (eg. in PogamutUT2004 there is a CTFMemory,
              DOMMemory ...), memory objects provide utility methods for
              specific problem domains</para>
            </listitem>
          </itemizedlist></para>
      </section>

      <section>
        <title>Navigation</title>

        <para>Navigation is achieved through two levels of abstraction:</para>

        <variablelist>
          <varlistentry>
            <term>Path finding</term>

            <listitem>
              <para>High level planning of the path. For this purpose the
              Pogamut provides integration with a JGraphT library (set of
              graph algorithms).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Steering</term>

            <listitem>
              <para>Low level mechanism ensuring, that the pre-planned path
              will be followed.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para></para>
      </section>
    </section>

    <section>
      <title>Agent remote management</title>

      <para>It is often convenient to be able to control the agent instance
      from outside the JVM where it is running. Possible use cases are:</para>

      <itemizedlist>
        <listitem>
          <para>debugging</para>
        </listitem>

        <listitem>
          <para>distributed experiments with agents running on multiple
          computers</para>
        </listitem>
      </itemizedlist>

      <para>The Pogamut platform provides standard way for managing the agents
      from outside the JVM or even from remote computer over TCP/IP.
      Communication between the agent and the controller (or observer) is
      mediated through the JMX (Java Management Extension) which is a standard
      API for remote management of Java applications. JMX makes it possible to
      use standard client programms (eg. JConsole) that are not aware of the
      internal logic of the program. On the other hand the JMX can be used
      only as a transport layer and the agent can be controlled from custom
      code (see AgentMBeanAdapterTest test case for example usage).</para>

      <para>To provide the full functionality it is important that the client
      program (JConsole or custom program) has access to all classes exposed
      through the JMX. This means that the:<itemizedlist>
          <listitem>
            <para>client has all the necessary classes on it's classpath,
            or</para>
          </listitem>

          <listitem>
            <para>client's SecurityManager is setted up to allow class
            downloading through RMI</para>
          </listitem>
        </itemizedlist></para>

      <para>If none of this conditions holds then some classes in the JMX
      interface may not be accessible from the client program.</para>
    </section>

    <section id="platform.config">
      <title>Platform configuration</title>

      <para>Pogamut platform provides unified way for specifiing and
      retreiving program parameters. The entry point to this mechanism
      represents the <code>Pogamut.getPlatform()</code> method returning a
      <code>PogamutPlatform</code> implementation. The purpose of the
      PogamutPlatform object is to provide objects and properties that are
      commonly needed in the code (eg. MBeanServer, properties specifiing
      adresses of the servers where agents will connect etc.). In the next
      paragraph a <code>DefaultPogamutPlatform</code> will be described, but
      the design pattern used makes it possible to introduce new
      implementations of the platform in the future without need of changing
      the existing code (eg. imagine <code>RemotePogamutPlatform</code>
      implementation that will load the properties from one central server
      thus make it much easier to manage cluster of computers ...).</para>

      <para>Let's examine the way property values are obtained in the
      <code>DefaultPogamutPlatform</code>. The algorithm is:</para>

      <para><orderedlist>
          <listitem>
            <para>look for the property on command line supplied by the
            <code>-D</code> option (eg. <code>java -jar myAgent.jar
            -Dpogamut.my.property=myValue</code>), if the property is not
            found then</para>
          </listitem>

          <listitem>
            <para>try to load property from
            <emphasis>PogamutPlatformCustom.properties</emphasis> files
            located in the working directory, if the property was not found
            then</para>
          </listitem>

          <listitem>
            <para>load the property from default poperty file located inside
            the PogamutBASE.jar, if the property is not present then raise
            <code>PropertyNotFoundException</code></para>
          </listitem>

          <listitem>
            <para>get the property from system properties (eg. specified by
            <code>c:\&gt; set pogamut.my.property=hello</code>)</para>
          </listitem>
        </orderedlist>Accessing properties inside the user code is done by the
      <code>Pogamut.getPlatform().getProperty("pogamut.my.property")</code>
      call.</para>
    </section>
  </chapter>

  <chapter>
    <title>mishmash</title>

    <para></para>

    <section>
      <title>TODO</title>

      <para><itemizedlist>
          <listitem>
            <para>reprezent messages as OWL triples</para>
          </listitem>

          <listitem>
            <para>connect OWL reasoner to the platform</para>
          </listitem>

          <listitem>
            <para></para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <title>Things we believe that have to change in Java</title>

      <para>Type system - introduce runtime generics!!!
      http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5098163, hopefuly it
      will be in Java 7 (http://tech.puredanger.com/java7/)</para>
    </section>
  </chapter>
</book>
