01: /*
02: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
03: * Distributed under the terms of either:
04: * - the common development and distribution license (CDDL), v1.0; or
05: * - the GNU Lesser General Public License, v2.1 or later
06: * $Id: ElementAware.java 3634 2007-01-08 21:42:24Z gbevin $
07: */
08: package com.uwyn.rife.engine;
09:
10: import com.uwyn.rife.engine.exceptions.EngineException;
11:
12: /**
13: * This interface contains all the methods that a class must implement to
14: * become an element for the web engine.
15: * <p>For convenience, you can also extend the abstract {@link Element} class
16: * which gives you the benefit of having local access to all its methods and
17: * having no abstract methods to implement.
18: * <p>Elements are the smallest logical building blocks of a RIFE web
19: * application. They are declared in the site structure and when a request
20: * arrives that maps to an element declaration, a new instance of the
21: * implementation is created. Element instances are thus never shared amongst
22: * requests, unless you are into a continuation tree that is set up to not
23: * clone its variable stack. This makes the logic inside elements fully
24: * thread-safe.
25: * <p>The {@link #processElement} method is the default entry point and will
26: * be called when a request arrives.
27: * <p>You're free to add any other method to this class. RIFE provides a
28: * convention syntax for methods that are supposed to handle submissions. The
29: * name of the submission is capitalized and the "<code>do</code>" literal is
30: * prepended. RIFE then looks for a method with that name, the <code>public
31: * void</code> modifiers and no arguments. When such a method is found, it is
32: * executed instead of <code>processElement()</code>. Nothing prevents you
33: * however from handling submissions conditionally in the
34: * <code>processElement()</code> method though, without isolating the logic in
35: * a separate method. For example, when a submission arrives with the name "<code>storeUser</code>",
36: * RIFE will look for the method:
37: * <pre>public void doStoreUser()</pre>
38: * If it's present, it will be called instead of <code>processElement()</code>.
39: * <p>Often you want to initialize common data structures, both for regular
40: * requests as for submissions. The {@link ElementSupport#initialize()} method
41: * can be used for that. It will be the first element's method that is called
42: * in a fully setup element context. When extending {@link Element}, the
43: * easiest is to simply overload the {@link ElementSupport#initialize()}
44: * method, otherwise an {@link ElementInitializer} has to be registered in the
45: * {@link #noticeElement} method.
46: * <p>RIFE also supports setter-based dependency injection for element
47: * properties, inputs, global variables and submission parameters. If setter
48: * methods are present that correspond to declared variable names, they will
49: * be automatically invoked with the available values. Of course, you can
50: * always retrieve values through the dedicated ElementSupport methods for
51: * {@link ElementSupport#getProperty properties}, {@link
52: * ElementSupport#getInput inputs} and {@link ElementSupport#getParameter
53: * submission parameters}.
54: *
55: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
56: * @version $Revision: 3634 $
57: * @since 1.0
58: */
59: public interface ElementAware {
60: /**
61: * This method is called immediately after the instantiation of the
62: * element to provide the support object that allows the element to
63: * function in the current context. Note that the context is not setup
64: * yet, the bridge object is merely provided at this stage.
65: * <p>It's good practice to store the <code>elementSupport</code>
66: * parameter in a member variable of the element, making it possible to
67: * use it from any method in the element.
68: * <p>This method should also be used to provide the elementSupport
69: * instance with an {@link ElementDeployer}, an {@link ElementInitializer}
70: * and an {@link ElementChildTrigger}, if they are needed.
71: *
72: * @param elementSupport the <code>ElementSupport</code> instance for this
73: * request and this element
74: * @see ElementSupport
75: * @since 1.0
76: */
77: public void noticeElement(ElementSupport elementSupport);
78:
79: /**
80: * The default entry point that will be called when a request arrives.
81: *
82: * @since 1.0
83: */
84: public void processElement() throws EngineException;
85: }
|