Akcje

Introduction 

Akcje są to zadania, jakie agent może zlecić swojemu rodzicowi, które wykonywane są na agencie zlecającym akcję (np. migracja, klonowanie, śmierć itp.) albo na wybranym innym agencie (np. zmiana ilości zasobu). W systemie AgE zalecane jest, żeby każda zmiana konfiguracji drzewa obliczeń w trakcie działania systemu wykonywana była z użyciem mechanizmu akcji. Akcje rozważane są tylko w kontekście agentów lekkich. Realizowane są dwuetapowo:

• podczas wykonywania obliczenia agent lekki zleca wykonanie akcji swojemu rodzicowi (np. agent decyduje się na śmierć, co prowadzi do jego usunięcia z struktury obliczenia),
• rodzic agenta podczas przetwarzania kolejki zdarzeń wykonuje wszystkie akcje w kolejce (np. uśmierca agenta).

Możliwość wykonywania akcji jest udostępniania poprzez ich środowisko. Oznacza to, że agent może zlecać wykonanie różnych akcji swojemu rodzicowi, który jednocześnie jest jego środowiskiem. Domyślnymi akcjami są:

• dodanie nowego agenta - do agregatu wykonującego akcję zostanie dodany nowy agent,
• przeniesienie agenta - agent zlecający akcję zostanie przeniesiony w inne miejsce w systemie obliczeniowym (o ile otrzyma zezwolenie na taką migrację),
• śmierć agenta - agent zlecający akcję zostanie usunięty z systemu.
• klonowanie agenta - agregat tworzy kopię agenta zlecającego akcję nadając tworzonemu agentowi nowy adres

Ponadto użytkownik powinien mieć możliwość definiowania nowych akcji, nie ujętych w powyższym wykazie.

W systemie AgE istnieją dwa rodzaje akcji: proste i złożone.

• Akcje proste są odpowiedzialne za wykonanie pojedynczych zadań na jednym agencie (np. wspomniana wcześniej śmierć agenta, klonowanie, itp.). Zawierają one adres agenta, na którym akcja ma zostać wykonana oraz kontekst danej akcji. W kontekście akcji zawarte są wszystkie dodatkowe informacje potrzebne do wykonania akcji (np. ilość zasobów, która ma zostać przekazana agentowi). Informacje w nim zawarte są zależne od typu akcji jaki opisują.

• Akcje złożone nie zawierają same w sobie żadnych czynności do wykonania - są natomiast kontenerami grupującymi inne akcje (proste lub złożone). Akcje te tworzą strukturę drzewiastą, co zapewnia stałą kolejność wykonania akcji składowych oraz możliwość tworzenia dużych akcji z mniejszych. Przykładową akcją złożoną jest wymiana zasobów pomiędzy dwoma agentami, w zależności od parametrów agentów uczestniczących w wymianie - akcjami składowymi są w tym przypadku: wybranie agenta do wymiany zasobu, odjęcie pobranie zasobu z jednego agenta oraz oddanie go drugiemu agentowi.

Możliwa funkcjonalność akcji jest bardzo szeroka, dlatego utworzono dwa mechanizmy akcji, których użycie zaleca się w zależności od sytuacji.

• Pierwszym sposobem wykonania akcji jest wykonanie ich przez agregat (rodzica). Mechanizm ten przewiduje implementację akcji jako metody agregatu. Akcje realizowane w ten sposób powinny być stosowane tylko w przypadkach, kiedy ich wykonanie wymaga dostępu do prywatnych pól lub metod agregatu. Zmiana zachowania akcji wymaga rekompilacji klasy agregatu - wybór tego mechanizmu powinien więc dotyczyć akcji, które są ściśle związane z agregatem i mają niezmienną funkcjonalność, takich jak tworzenie czy usuwanie agentów.
• Akcje wykonywane przez strategie są realizowane przez zewnętrzne komponenty, zgodnie ze wzorcem projektowym ,,strategia''. Z racji przeniesienia wykonywania akcji poza agregat, nie ma ona dostępu do właściwości i metod prywatnych agregatu. Akcje wykonywane przez strategie są bardziej elastyczne niż te wykonywane jako metody agregatu, a zmiana zachowania nie wymaga rekompilacji agregatu. Ich użycie jest więc zalecane wszędzie tam, gdzie dostęp do pól i metod prywatnych agregatu nie jest konieczny.

Trzy fazy wykonania akcji

Każda akcja wykonywana jest w trzech kolejnych fazach:

• INIT inicjalizacji i sprawdzenie poprawności adresów. W tej fazie poza walidacją adresów mogą wystąpić dodatkowe czynności, jak np. dodanie nowego agenta. Dzięki temu na nowo dodanym agencie mogą zostać wykonane kolejne akcje wchodzące w skład jednej akcji prostej.
• MAIN główna faza wykonania akcji
• FINISH zakończenie akcji - faza ta może zawierać dodatkowe czynności wykonywane za zakończenie akcji. W tej fazie może być wykonane np. usunięcie agenta ze środowiska,dzieki temu uzyskamy pewność że agent nie zostanie usunięty podczas głownego przetwarzania akcji, w którym inne agenty mogą się do niego odwoływać.

W przypadku akcji złożonej, najpierw wykonywana jest faza INIT dla wszystkich akcji prostych, poźniej analogicznie faza MAIN i FINISH

Definiowanie akcji wykonywanej przez agregat

/**
 * Executes INIT action phase
 *
 * @param action
 *            action to perform
 * @return collection of agent addresses which are used by action "actionName"
 */
@AgentAction(name = "actionName", phase = ActionPhase.INIT)
protected Collection<IAgentAdddress> performInitActionName(SingleAction action) {
	// ...

}

/**
 * Executes MAIN action phase
 *
 * @param target
 *            agent on which action will be performed
 * @param context
 *            action context
 */
@AgentAction(name = "actionName", phase = ActionPhase.MAIN)
protected void performInitActionName(IAgent target, IActionContext context) {
	// ...

}

/**
 * Executes FINISH action phase
 *
 * @param target
 *            agent on which action will be performed
 * @param context
 *            action context
 */
@AgentAction(name = "actionName", phase = ActionPhase.FINISH)
protected void performFinishActionName(IAgent target, IActionContext context);
	// ...
}

Actions executed by strategies

Actions can be realized by external strategies and it's realization is independent from aggregate implementation.

To define actions executed by strategies follow the steps:

1. Define an action context with a specified id (let's say sampleAction).
2. Add implementation of the action by providing a class which implements IPerformActionStrategy - see API for more details.
3. Register the action implementation in configuration file by name given in action context:

   <strategy name="sampleAction" class="org.jage.examples.actions.SampleActionStrategy" />
   

Defining action context

Action context is a class which describes an action execution context and has two roles:

• defines action id,
• contains required data to perform an action.

The following snippet presents a sample action context which allows for getting:

@AgentActionContext("sendMessage")
public class SendMessageActionContext implements IActionContext {

	/**
	 * The message to send.
	 */
	private final Message _message;


	public SendMessageActionContext(Message message) {
		this._message = message;
	}


	public Message getMessage() {
		return _message;
	}

}

1. The context must be annotated by @AgentActionContext with a name of the action (see API for more details). The name is resolved during action execution depending on action type (realized by strategy or aggregate method).
2. The class must implement IActionContext.
3. If required, the class should define attributes needed during action execution. In example, the context contains a message to send.

How an agent creates an action?

To perform an action, an agent needs to call doAction method on AbstractAgent with:

• address selector which specifies target agent(s) on which the action will be executed,
• action context which specifies the action to be executed and contains required data (if needed).

The following snippet presents creating a sample action which will be executed on the action caller:

@Override
public void step() {
	log.info(getAddress() + " says Hello World from " + getParentAddress());
	try {
		doAction(new SingleAction(new UnicastSelector<IAgentAddress>(getAddress()), new SampleActionContext()));
	} catch (AgentException e) {
		log.error(e);
	        return;
	}
        // ...
}

Samples

Sample project which illustrates the action mechanism can be found in examples solutions and applications (https://herman.iisg.agh.edu.pl/svn/jage/trunk/examples/) in org.jage.examples.actions package.

TODO

• walidacja selektorow
• handleUnknownAction
• selectory