Modular.xml

Greta Modular is a program which implements an agent without coding, but graphically.

Table of Contents Configuration Add a library Add a module Add a connector Add an item in the menu Add a style gretaModular.xsd

Configuration

All menus, modules, connectors and styles are defined in an XML file named gretaModular.xml (defined by this XSD).
The base content of this file is (in any order) :

<greta_modular>
	<!-- menu gives access to modules from the GUI -->
	<menus/>

	<!-- list of all modules that can be used -->
	<modules/>

	<!-- list of libraries and their dependencies -->
	<libs/>

	<!-- list of how to connect and disconnect modules -->
	<connectors/>

	<!-- list of styles -->
	<styles/>
</greta_modular>

Add a library

Simply add a new markup <lib> in <libs>.
This markup needs 2 attributes :

• id : an unique identifier inside <libs>
• path : the relative path of the library from gretaModular

exemple :

<lib id="greta_util" path="./Common/Lib/Internal/Util.jar" />

In case your library has one or more dependency on another library, you must add one or more <depends> markup in <lib>.
Only one attribut :

• lib_id : the identifier of the library that it depends

exemple :

<lib id="greta_intentions" path="./Common/Lib/Internal/Intentions.jar" >
	<depends lib_id="greta_util" />
</lib>

A library and its dependencies are loaded only if a module or a connector needs it.

Add a module

First, if your module use a library that is not defined in <libs> you need to add it. A module is defined inside <modules> by a markup <module> :
3 attributs :

• name : an unique identifier inside <modules>.
• style : optional. the graphical style of the module. Default value is the style default.
• restrict : optional. the maximum occurence of this module, 0 means unbounded. Default value is 0.

<module> may contains one markup <description> that contains a brief description of this module.
<module> must contains one markup <object>
<object> :

• class : the full class name of the object.
• lib_id : the identifier of the library where the class is defined.

<module> may contains one markup <frame> that define a JFrame associated to the module.
<frame> :

• type : the type of the frame. Values are noFrame (permitted but <frame> is useless in this case), object (the object is also the JFrame) or frame (in this only case, the folowing attributs class and lib_id must be specified).
• class : the full class name of the frame. Required and used only when type="frame".
• lib_id : the identifier of the library where the class is defined. Required and used only when type="frame".
• windowed_only : optional. says if the frame must be always in an external window. Default value is false. Should be set to true in case of extreme necessity, otherwise don't use it.

<frame> may contains a <link> markup when type="frame".
<link>

• method : the name of the method that links object and frame.
• on : Defined the object on which the method is called. Values are object or frame. The other will be used as an implicit argument of the method.
  

<module> may contains an undefined number of markup <parameter>. They are used to save some usefull values.
<parameter> :

• name : the name of the parameter.
• type : the type of the parameter. Values are boolean, byte, short, integer, long, float, double or string.
• default : the default value. It must be consistent with the type.
• set_method : the name of the method by which the parameter is set.
• set_on : the object on which the set method is called. Values are object or frame.
• get_method : the name of the method by which the parameter is get.
• get_on : the object on which the get method is called. Values are object or frame.

exemple 1 :

<module name="LogPrinter" style="DEFAULT" restrict="1" >
	<object class="greta.core.util.log.LogPrinter" lib_id="greta_modular" />
</module>

This module, named LogPrinter can be instanciated only once (restrict="1"). When it is instancated, two objects are created :

• an instance of the class greta.core.util.log.LogPrinter defined in the library called greta_modular.
• a cell in the graph with the style called DEFAULT.

No frame and no parameter are used with this module.

exemple 2 :

<module name="LogFrame" style="DEFAULT" >
	<description>Displays the logs in a window.</description>
	<object class="greta.application.modular.controls.DocOutput" lib_id="greta_modular" />
	<frame type="frame" class="greta.application.modular.controls.DocOutputFrame" lib_id="greta_modular">
		<link method="setDocOutput" on="frame" />
	</frame>
	<parameter type="boolean" name="blackBackground" default="false"
		set_on="frame" set_method="setBlack"
		get_on="frame" get_method="isBlack" />
</module>

This module, named LogFrame can be instanciated as many times as it is desired (implicit restrict="0"). When it is instancated, three objects are created :

• an instance of the class greta.application.modular.controls.DocOutput defined in the library called greta_modular. Used as the main object.
• an instance of the class greta.application.modular.controls.DocOutputFrame defined in the library called greta_modular. Used as a frame.
• a cell in the graph with the style called DEFAULT.

After instanciations, the program will execute the equivalent of this code:

frame.setDocOutput(object);
boolean blackBackground = false;

// blackBackground is modified by a saved value, if there is

frame.setBlack(blackBackground);

And when you save, the value of blackBackground is get like that:

boolean blackBackground = frame.isBlack();

Limitations :

• The object and the frame must have a constructor without argue.
• The frame must extends the javax.swing.JFrame class.
• link and set methods, must have only one argue, no more no less.
• get methods must have no argue.

Add a connector

Connectors describe how to connect two modules.
They must be added in <connectors> by the markup <connector> that contains two attributes :

• id : an unique identifier inside <connectors>
• unique : Optional. says if this connector can be used only once with a specific input module. Values are true or false. Default value is false.

<connector> contains four markups:
<input> :

• class : the full class name of the input object (inheritance is supported).
• lib_id : the identifier of the library where the class is defined.

<output> :

• class : the full class name of the output object (inheritance is supported).
• lib_id : the identifier of the library where the class is defined.

<connect> :

• method : the name of the method of the obect specified by from that connects from and to.
• from : the object where the method is called. Permitted values are input, output and null (the method will not be called in this case).
• to : the object passed in method parameter. Permitted values are input, output and null.

<disconnect> :

• method : the name of the method of the obect specified by from that disconnects from and to.
• from : the object where the method is called. Permitted values are input, output and null (the method will not be called in this case).
• to : the object passed in method parameter. Permitted values are input, output and null.

exemple :

<connector id="addLogOutput" >
	<input class="greta.application.modular.controls.LogsController" lib_id="greta_modular" />
	<output class="greta.core.util.log.LogOutput" lib_id="greta_util" />
	<connect from="input" method="addLogOutput" to="output" />
	<disconnect from="input" method="removeLogOutput" to="output" />
</connector>

In this exemple, if you try to connect a module module1 that extends greta.application.modular.controls.LogsController with an other module module2 that extends greta.core.util.log.LogOutput the program will call :

module1.addLogOutput(module2);

Limitation : the two methods must have one parameter, no more no less.

Add an item in the menu

The "file" menu is not editable and contains base functionalities (new, open, save, save as).
Other menus are defined in <menus>. A menu is represented by the markup <menu> One attribut :

• name : the visible name of this menu.
  

This markup must contains at least one other markup <menu> or <item>. It makes no sense to have an empty menu.

The markup <item> has 2 attributs :

• name : the visible name of this menu item.
• module : the identifier of a module.

Click on this item in !GretaModular will create an instance of the module.
If the identifier is wrong or if the module is not loaded (missing library, error in module definition etc.) this item will be disable.

exemple of menu :

<menu name="Add">
	<menu name="Logs">
		<item module="Logs" name="Controller" />
		<item module="LogPrinter" name="Log Printer" />
		<item module="LogFile" name="Log File" />
	</menu>
	<item module="BehaviorPlanner" name="Behavior Planner" />
</menu>

Add a style

Styles are the color of the cell represening a module. They are all stored in <styles>.
The default style is define in the markup <default>.

• color : Optional. the color in hexadecimal. the default value is 0xFDFDFD.

exemple :

<default color="0xFFFFFF" />

You can add an other style adding a markup <style> in <styles>. 2 attributs :

• name : an unique identifier inside <styles>. The value default is not permited (used by the style <default>).
• color : Optional. the color in hexadecimal. the default value is 0xFDFDFD.

exemple :

<style name="DEFAULT" color="0xCCCCFF" />

gretaModular.xsd

This file is used by GretaModular.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

	<xs:complexType name="libdependent" >
		<xs:attribute name="lib_id" type="xs:string" use="required"/>
	</xs:complexType>

	<xs:complexType name="objecttype">
		<xs:complexContent>
			<xs:extension base="libdependent">
				<xs:attribute name="class" type="class_name" use="required"/>
			</xs:extension>
		</xs:complexContent>
	</xs:complexType>

	<xs:element name="style">
		<xs:complexType>
			<xs:attribute name="name" type="xs:string" use="required"/>
			<xs:attribute name="color" type="xs:string" default="0xFDFDFD" />
		</xs:complexType>
	</xs:element>

	<xs:element name="menu">
		<xs:complexType>
			<xs:sequence>
				<xs:choice minOccurs="1" maxOccurs="unbounded">
					<xs:element name="item">
						<xs:complexType>
							<xs:attribute name="name" type="xs:string" use="required"/>
							<xs:attribute name="module" type="xs:string" use="required"/>
						</xs:complexType>
					</xs:element>
					<xs:element ref="menu" />
				</xs:choice>
			</xs:sequence>
			<xs:attribute name="name" type="xs:string" use="required"/>
		</xs:complexType>
	</xs:element>

	<xs:simpleType name="fromto">
		<xs:restriction base="xs:string">
			<xs:enumeration value="null"/>
			<xs:enumeration value="input"/>
			<xs:enumeration value="output"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="setongeton">
		<xs:restriction base="xs:string">
			<xs:enumeration value="object"/>
			<xs:enumeration value="frame"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:complexType name="connectionmethodtype" >
		<xs:attribute name="from" type="fromto" use="required"/>
		<xs:attribute name="to" type="fromto" use="required"/>
		<xs:attribute name="method" type="method_name" use="required"/>
	</xs:complexType>

	<xs:simpleType name="parametertype">
		<xs:restriction base="xs:string">
			<xs:enumeration value="boolean"/>
			<xs:enumeration value="byte"/>
			<xs:enumeration value="short"/>
			<xs:enumeration value="integer"/>
			<xs:enumeration value="long"/>
			<xs:enumeration value="float"/>
			<xs:enumeration value="double"/>
			<xs:enumeration value="string"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="frametype">
		<xs:restriction base="xs:string">
			<xs:enumeration value="object"/>
			<xs:enumeration value="frame"/>
			<xs:enumeration value="noFrame"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="method_name" >
		<xs:restriction base="xs:string">
			<xs:pattern value="([a-zA-Z_$]([0-9])*)*"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:simpleType name="class_name" >
		<xs:restriction base="xs:string">
			<xs:pattern value="([a-zA-Z_$]([0-9])*)+([.]([a-zA-Z_$]([0-9])*)+)*"/>
		</xs:restriction>
	</xs:simpleType>

	<xs:element name="greta_modular">
		<xs:complexType>
			<xs:all>
				<xs:element name="menus">
					<xs:complexType>
						<xs:sequence>
							<xs:element ref="menu" maxOccurs="unbounded"/>
						</xs:sequence>
					</xs:complexType>
				</xs:element>
				<xs:element name="modules" >
					<xs:complexType>
						<xs:sequence>
							<xs:element name="module" maxOccurs="unbounded">
								<xs:complexType>
									<xs:sequence>
										<xs:element name="description" minOccurs="0" maxOccurs="1" />
										<xs:element name="object" type="objecttype" />
										<xs:element name="frame" minOccurs="0">
											<xs:complexType>
												<xs:sequence>
													<xs:element name="link" minOccurs="0">
														<xs:complexType>
															<xs:attribute name="on" type="setongeton" use="required"/>
															<xs:attribute name="method" type="method_name" use="required"/>
														</xs:complexType>
													</xs:element>
												</xs:sequence>
												<xs:attribute name="type" type="frametype" use="required"/>
												<xs:attribute name="class" type="class_name" />
												<xs:attribute name="lib_id" type="xs:string" />
												<xs:attribute name="windowed_only" type="xs:boolean" default="false"/>
											</xs:complexType>
										</xs:element>
										<xs:element name="parameter" minOccurs="0" maxOccurs="unbounded">
											<xs:complexType>
												<xs:attribute name="name" type="xs:string" use="required"/>
												<xs:attribute name="type" type="parametertype" use="required"/>
												<xs:attribute name="default" type="xs:string" use="required"/>
												<xs:attribute name="set_on" type="setongeton" use="required"/>
												<xs:attribute name="get_on" type="setongeton" use="required"/>
												<xs:attribute name="get_method" type="method_name" use="required"/>
												<xs:attribute name="set_method" type="method_name" use="required"/>
											</xs:complexType>
										</xs:element>
									</xs:sequence>
									<xs:attribute name="name" type="xs:string" use="required"/>
									<xs:attribute name="style" type="xs:string" default="default"/>
									<xs:attribute name="restrict" type="xs:nonNegativeInteger" default="0"/>
								</xs:complexType>
							</xs:element>
						</xs:sequence>
					</xs:complexType>
					<xs:key name="modulename" >
						<xs:selector xpath="module"/>
						<xs:field xpath="@name"/>
					</xs:key>
				</xs:element>
				<xs:element name="libs" >
					<xs:complexType>
						<xs:sequence>
							<xs:element name="lib" maxOccurs="unbounded">
							<xs:complexType>
								<xs:sequence>
									<xs:element name="depends" type="libdependent" minOccurs="0" maxOccurs="unbounded"/>
								</xs:sequence>
								<xs:attribute name="id" type="xs:string" use="required"/>
								<xs:attribute name="path" type="xs:string" use="required"/>
							</xs:complexType>
						</xs:element>
						</xs:sequence>
					</xs:complexType>
					<xs:key name="libid" >
						<xs:selector xpath="lib"/>
						<xs:field xpath="@id"/>
					</xs:key>
				</xs:element>
				<xs:element name="connectors">
					<xs:complexType>
						<xs:sequence>
							<xs:element name="connector" maxOccurs="unbounded" >
								<xs:complexType>
									<xs:all>
										<xs:element name="input" type="objecttype"/>
										<xs:element name="output" type="objecttype"/>
										<xs:element name="connect" type="connectionmethodtype"/>
										<xs:element name="disconnect" type="connectionmethodtype"/>
									</xs:all>
									<xs:attribute name="id" type="xs:string" use="required"/>
									<xs:attribute name="unique" type="xs:boolean" default="false"/>
									<xs:attribute name="ordered" type="xs:boolean" default="false"/><!-- TODO -->
								</xs:complexType>
							</xs:element>
						</xs:sequence>
					</xs:complexType>
					<xs:key name="connectionid" >
						<xs:selector xpath="connection"/>
						<xs:field xpath="@id"/>
					</xs:key>
				</xs:element>
				<xs:element name="styles" >
					<xs:complexType>
						<xs:sequence>
							<xs:sequence>
								<xs:element ref="style" minOccurs="0" maxOccurs="unbounded"/>
							</xs:sequence>
							<xs:element name="default">
								<xs:complexType>
									<xs:attribute name="name" type="xs:string" fixed="default"/>
									<xs:attribute name="color" type="xs:string" default="0xFDFDFD" />
								</xs:complexType>
							</xs:element>
							<xs:sequence>
								<xs:element ref="style" minOccurs="0" maxOccurs="unbounded"/>
							</xs:sequence>
						</xs:sequence>
					</xs:complexType>
					<xs:key name="stylename" >
						<xs:selector xpath="./*"/>
						<xs:field xpath="@name"/>
					</xs:key>
				</xs:element>
			</xs:all>
		</xs:complexType>
		<xs:keyref name="lib_id" refer="libid">
			<xs:selector xpath=".//*"/>
			<xs:field xpath="@lib_id"/>
		</xs:keyref>
		<xs:keyref name="moduleref" refer="modulename">
			<xs:selector xpath=".//*"/>
			<xs:field xpath="@module"/>
		</xs:keyref>
		<xs:keyref name="style" refer="stylename">
			<xs:selector xpath=".//module"/>
			<xs:field xpath="@style"/>
		</xs:keyref>
	</xs:element>

	<xs:element name="greta_modulated">
		<xs:complexType>
			<xs:all>
				<xs:element name="elements">
					<xs:complexType>
						<xs:sequence>
							<xs:element name="element" minOccurs="0" maxOccurs="unbounded">
								<xs:complexType>
									<xs:sequence>
										<xs:element name="parameter" minOccurs="0" maxOccurs="unbounded">
											<xs:complexType>
												<xs:attribute name="name" type="xs:string" use="required"/>
												<xs:attribute name="value" type="xs:string" use="required"/>
											</xs:complexType>
										</xs:element>
										<xs:element name="window" minOccurs="0" maxOccurs="1">
											<xs:complexType>
												<xs:attribute name="visible" type="xs:boolean" use="required"/>
												<xs:attribute name="x" type="xs:integer" use="required"/>
												<xs:attribute name="y" type="xs:integer" use="required"/>
												<xs:attribute name="w" type="xs:integer" use="required"/>
												<xs:attribute name="h" type="xs:integer" use="required"/>
											</xs:complexType>
										</xs:element>
									</xs:sequence>
									<xs:attribute name="id" type="xs:string" use="required"/>
									<xs:attribute name="module" type="xs:string" use="required"/>
									<xs:attribute name="name" type="xs:string" use="required"/>
									<xs:attribute name="x" type="xs:decimal" use="required"/>
									<xs:attribute name="y" type="xs:decimal" use="required"/>
									<xs:attribute name="w" type="xs:decimal" use="required"/>
									<xs:attribute name="h" type="xs:decimal" use="required"/>
								</xs:complexType>
							</xs:element>
						</xs:sequence>
					</xs:complexType>
					<xs:key name="elementid" >
						<xs:selector xpath="element"/>
						<xs:field xpath="@id"/>
					</xs:key>
				</xs:element>
				<xs:element name="connections" >
					<xs:complexType>
						<xs:sequence>
							<xs:element name="connection" minOccurs="0" maxOccurs="unbounded">
								<xs:complexType>
									<xs:attribute name="connector" type="xs:string" use="required"/>
									<xs:attribute name="source" type="xs:string" use="required"/>
									<xs:attribute name="target" type="xs:string" use="required"/>
								</xs:complexType>
							</xs:element>
						</xs:sequence>
					</xs:complexType>
				</xs:element>
			</xs:all>
		</xs:complexType>
		<xs:keyref name="elementidsource" refer="elementid">
			<xs:selector xpath=".//connection"/>
			<xs:field xpath="@source"/>
		</xs:keyref>
		<xs:keyref name="elementidtarget" refer="elementid">
			<xs:selector xpath=".//connection"/>
			<xs:field xpath="@target"/>
		</xs:keyref>
	</xs:element>
</xs:schema>