Specyfikacja pliku konfiguracyjnego

Konfiguracja obliczenia dla platformy jAgE przechowywana jest w postaci pliku XML. Na niniejszej stronie znajduje się dokładna specyfikacja format pliku konfiguracyjnego utworzona na podstawie XML Schema dostępnej na http://age.iisg.agh.edu.pl/xsd/age-2.3.xsd. Każdy plik konfiguracyjny powinien zawierać preambułę określającą lokalizację XML schema oraz domyślny namespace:

<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://age.iisg.agh.edu.pl/AgE/2.5"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://age.iisg.agh.edu.pl/AgE/2.5 http://age.iisg.agh.edu.pl/xsd/age-2.5.xsd">
  ...
</configuration>

Poniższa tabela zawiera spis wszystkich możliwych tagów:

Opis znaczników

constructor-arg

Elementy <constructor-arg/> służą do określenia, jakie wartości należy przekazać do konstruktora obiektu. W przeciwieństwie do wszystkich innych elementów konfiguracji, kolejność zdefiniowania elementów <constructor-arg/> jest istotna, gdyż argumenty zostaną przekazane w takiej kolejności, w jakiej wystąpiły w konfiguracji. Podobnie jak w przypadku <property/>, jedynym elementem potomnym musi być element <value/> lub <reference/>.

Do góry

include

The <include/> element can be used to insert another XML document in the place it is located. It allows to split a single configuration into many files. It has one required attribute: file that defines a name of the XML resource to load. The content of the root element (<configuration/>) of the pointed document is inserted in the place of the <include/> and not the root element itself.

Example:

<configuration>
	<include file="file:agents.xml"/>
</configuration>

Do góry

list

Element <list/> jest definicją listy obiektów dowolnego typu.

Elementami potomnymi mogą być <value/> oraz <reference/>, które określają, jakie obiekty ma zawierać lista, a także definicje innych obiektów.

Przykład definicji listy wypełnionej 10 obiektami (4 obiekty object1, 5 obiektów object2 i jeden obiekt object3):

<list name="myList" type="org.example.MyClass">
	<reference target="object1" count="4"/>
	<reference target="object2" count="5"/>
	<reference target="object3"/>
</list>

Do góry

array

The <array/> element defines an Java array of any type.

Allowed children components of the <array/> can be both <value/> and <reference/> that describes what objects the array will contain. Definitions of other components are also allowed.

An example of the definition of a llist that contains 3 objects of type java.lang.Long:

<array name="long-example" type="Long">
	<value class="Long" value="2" />
	<value class="Long" value="4" />
	<value class="Long" value="8" />
</array>

Up

map

Element <map/> jest definicją słownika obiektów dowolnego typu. Tak jak w przypadku list oraz zbiorów, element ten musi posiadać atrybut name oraz może posiadać atrybut isSingleton. Elementami potomnymi mogą być wyłącznie definicje innych obiektów i strategii lub elementy <item/>, określające obiekty wstawiane do słownika. Każdy z nich musi zawierać element <itemKey/>, określający klucz elementu listy, oraz <itemValue/>, określający wartość tego elementu.

Przykład dwuelementowej mapy:

<map name="myMap" isSingleton="true" keyType="java.lang.String" valueType="org.example.MyClass">
        <item>
		<itemKey><value class="String" value="2"/></itemKey>
		<itemValue><reference target="innerObject2"/></itemValue>
	</item>
	<item>
		<itemKey><value class="String" value="1"/></itemKey>
		<itemValue><reference target="innerObject1"/></itemValue>
	</item>
</map>

Do góry

component

Element <component/> jest definicją komponentu reprezentowanego przez obiekt dowolnego typu. Może on posiadać trzy atrybuty:

Dopuszcza się następujące elementy potomne opisywanego elementu:

1. Definicje innych komponentów (takie jak <component/>, <list/>, itp.). Komponenty zdefiniowane we wnętrzu innego komponentu nie są widoczne poza swoim rodzicem, mogą jednak korzystać ze wszystkich komponentów, które są widoczne dla jakiegokolwiek z ich przodków w hierarchii.
2. Elementy <property/>.
3. Elementy <constructor-arg/>.
4. Elementy <include/>.

Przykład definicji obiektu posiadającego trzy pola (a, b, list):

<component name="outerObject" class="org.jage.core.config.workplace.tests.ClassWithProperties" isSingleton="true">

	<component name="innerObject1"
	 	class="org.jage.core.config.workplace.tests.ClassWithProperties" isSingleton="false"/>

        	<constructor-arg><value class="String" value="ABC"/></constructor-arg>
	        <constructor-arg><value class="Integer" value="123"/></constructor-arg>
	</component>
	<list name="myList" isSingleton="true">
	     <reference target="innerObject1"/>
	     <reference target="innerObject1"/>
	</list>

	<property name="a"><value class="Integer" value="4"/></property>
	<property name="b"><value class="Float" value="3.14"/></property>
	<property name="list"><reference target="myList"/></property>
</component>

Do góry

property

Element <property/> służy do ustawienia właściwości obiektu. Musi on posiadać atrybut name, określający nazwę właściwości. Jedynym elementem potomnym musi być element <value/> lub <reference/>, który definiuje przypisywaną wartość.

Do góry

reference

Element <reference/>, podobnie do elementu <value/>, jest używany do uzyskania pewnej wartości potrzebnej do stworzenia obiektu. Zwraca on referencję do innego zdefiniowanego w konfiguracji obiektu. Musi on posiadać pojedynczy atrybut target, który określa nazwę obiektu, do którego się odwołuje. Jeśli tag <reference/> definiuje elementy listy lub zbioru (patrz opis poniżej) może posidać opcjonalny atrybut count określający krotność opisywanych obiektów w kolekcji. Atrybut ten jest zabroniony jeśli element <reference/> występuje poza definicją kolekcji.

Do góry

set

Element <set/> jest definicją zbioru obiektów dowolnego typu.

Elementami potomnymi mogą być <value/> oraz <reference/>, które określają, jakie obiekty ma zawierać zbiór, a także definicje innych obiektów.

Przykład definicji zbrioru zawierającego dwa obiekty typu String z wartościami "1" i "2":

<set name="mySet" type="org.example.MyClass">
        <value class="String" value="2"/>
	<value class="String" value="1"/>
</set>

Do góry

agent

Element <agent/> opisuje pojedynczy typ agenta. Jest aliasem do elementu <component/> z atrybutem isSingleton ustawionym na false.

Wszystkie elementy potomne i atrybuty dostępne dla elementu <component/> mogą być również wykorzystane w elemencie <agent/>. Wyjątek stanowi atrybut isSingleton, którego użycie jest zabronione.

strategy

Element <strategy/> opisuje strategie, czyli komponenty reprezentowane przez obiekty o zasięgu singleton - jest równoznaczny elementowi <component/> z atrybutem isSingleton ustawioną na true. Wszystkie elementy potomne i atrybuty dostępne dla elementu <component/> mogą być również wykorzystane w elemencie <strategy/>. Wyjątek stanowi atrybut isSingleton, którego użycie jest zabronione.

Strategie mogą być definiowane na różnych poziomach w pliku konfiguracyjnym XML (co przekłada się w analogiczny sposób na hierarchię w modelu konfiguracji). Strategie (dot. to wszystkich komponentów - component) są dziedziczone w hierarchii modelu konfiguracyjnego, tzn:

• strategia jest widoczna (dostępna) tylko z poziomu, na którym jest zdefiniowana oraz na wszystkich poniższych poziomiach - w dół hierarchii (patrz przykład 2)
• nie można się odwołać do strategii, która jest zdefiniowana na niższym poziomie
• możliwe jest przesłanienia implementacji strategii tego samego typu - (patrz przykład 3)

Przykład 1 - definicja strategii

<strategy name="echo123Strategy"
	    class="org.jage.app.example.strategy.Echo123Strategy"/>

Przykład 2 - dziedziczenie strategii

<configuration>
	<strategy name="strategiaNaPoziomie1" class="org.jage.sample.StrategyA" >
		<strategy name="strategiaNaPoziomie2" class="org.jage.sample.StrategyB" />

		<component name="innerAgent" class="org.jage.sample.SampleAgent">
			<property name="strategyA"><reference target="strategiaNaPoziomie1"</property>
			<property name="strategyB"><reference target="strategiaNaPoziomie2"</property>
		</component>

	</strategy>
	<component name="outerAgent" class="org.jage.sample.SampleAgent">
		<property name="strategyA"><reference target="strategiaNaPoziomie1"</property>
	</component>

</configuration>

Obiekt outerAgent ma dostęp jedynie do strategii typu StrategyA, która jest zdefiniowana na tym samym poziomie w konfiguracji. Natomiast obiekt innerAgent może posiadać zależności do obu strategii: zdefiniowanej na tym samym poziomie (StrategyB) oraz na wyższych poziomach (StrategyB).

Przykład 3 - przesłanianie strategii

<configuration>
	<strategy name="strategiaNaPoziomie1" class="org.jage.sample.SampleStrategyImplA" >
		<strategy name="strategiaNaPoziomie2" class="org.jage.sample.SampleStrategyImplB" />

		<component name="innerAgent" class="org.jage.sample.SampleAgent" />

	</strategy>
	<component name="outerAgent" class="org.jage.sample.SampleAgent">

</configuration>

Zakłada się, że obiekty typu SampleAgent posiadają zależność od strategii typu ISampleStrategy. Natomiast klasy SampleStrategyImplA oraz SampleStrategyImplB są implementacjami interfejsu ISampleStrategy.

W tym przypadku obiekt outerAgent będzie posiadał wskazanie na obiekt typu SampleStrategyImplA ponieważ jest on jedyną widoczną implementacją. Natomiast z poprzedniego przykładu wynika, że obiekt innerAgent ma dostęp do obu strategii. Ponieważ są one tego samego typu, to do obiektu innerAgent jest wstrzykiwany obiekt typu, który zarejestrowany najbliżej w hierarchii (idąc w górę).

Do góry

value

Element <value/> jest używany do uzyskania pewnej wartości potrzebnej do stworzenia obiektu i za jego pomocą można określić konkretną wartość jednego z kilku typów prostych. Musi on posiadać dwa atrybuty: class, określający typ wartości, oraz value, zawierający zakodowaną w postaci łańcucha tekstowego wartość.

Do góry