01: package org.jicengine.element;
02:
03: import org.jicengine.operation.Context;
04:
05: /**
06: * <p>
07: * ActionElements can execute an action on request. The request is made by
08: * the client or user of the ActionElement, which is usually the parent element.
09: * </p>
10: * <p>
11: * Typically, ActionElement modify global objects or the instance of the parent
12: * element by setting the values of some properties or by calling some methods.
13: * ActionElements might also call some static methods.
14: * </p>
15: * <p>
16: * Design-note: ActionElements don't return any value. the ActionElement-interface
17: * is otherwise similar to the ValueElement-interface. The two interfaces could
18: * have been put under a common interface, but in that case the action should
19: * have returned value. it was essential that action-elements don't return
20: * a value. a null-value could have been used for signalling "no value", but
21: * that approach works only if we don't use null-values otherwise..
22: * </p>
23: *
24: * <p>
25: * Elements with the 'action'-attribute are compiled into ActionElements. However,
26: * also elements without the attribute may end up as ActionElements.
27: * </p>
28: * <p>
29: * Copyright (C) 2004 Timo Laitinen
30: * </p>
31: * @author Timo Laitinen
32: * @created 2004-09-20
33: * @since JICE-0.10
34: *
35: */
36:
37: public interface ActionElement extends Element {
38:
39: /**
40: * <p>
41: * Executes the action of this element. The operation doesn't return any
42: * value to its caller, although it can internally produce a value.
43: * </p>
44: * <p>
45: * The client/user of this element will call this method. currently, the method
46: * is called only once. However, the action should be able to be executed
47: * multiple times.
48: * </p>
49: * <p>
50: * in general, the execution consists of the following steps:
51: * </p>
52: *
53: * <ol>
54: * <li> if the element has an instance, it is created first (with parameters)</li>
55: * <li> if the element has other ActionElements as children, they are executed next </li>
56: * <li> finally, the actual action is executed (with parameters) </li>
57: * </ol>
58: *
59: * @param globalContext a Context where the instances marked with the 'id'-attribute
60: * are put.
61: *
62: * @param parentInstance the instance of the parent element. NOTE: null-value means
63: * that the value of the parent is not available (not yet
64: * or never), not that the instance of the parent is null!
65: *
66: * @throws ElementException if any part of the execution of the action fails.
67: */
68: public void execute(Context globalContext, Object parentInstance)
69: throws ElementException;
70: }
|