/*
* Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
* Distributed under the terms of either:
* - the common development and distribution license (CDDL), v1.0; or
* - the GNU Lesser General Public License, v2.1 or later
* $Id: ElementAware.java 3634 2007-01-08 21:42:24Z gbevin $
*/
package com.uwyn.rife.engine;
import com.uwyn.rife.engine.exceptions.EngineException;
/**
* This interface contains all the methods that a class must implement to
* become an element for the web engine.
* <p>For convenience, you can also extend the abstract {@link Element} class
* which gives you the benefit of having local access to all its methods and
* having no abstract methods to implement.
* <p>Elements are the smallest logical building blocks of a RIFE web
* application. They are declared in the site structure and when a request
* arrives that maps to an element declaration, a new instance of the
* implementation is created. Element instances are thus never shared amongst
* requests, unless you are into a continuation tree that is set up to not
* clone its variable stack. This makes the logic inside elements fully
* thread-safe.
* <p>The {@link #processElement} method is the default entry point and will
* be called when a request arrives.
* <p>You're free to add any other method to this class. RIFE provides a
* convention syntax for methods that are supposed to handle submissions. The
* name of the submission is capitalized and the "<code>do</code>" literal is
* prepended. RIFE then looks for a method with that name, the <code>public
* void</code> modifiers and no arguments. When such a method is found, it is
* executed instead of <code>processElement()</code>. Nothing prevents you
* however from handling submissions conditionally in the
* <code>processElement()</code> method though, without isolating the logic in
* a separate method. For example, when a submission arrives with the name "<code>storeUser</code>",
* RIFE will look for the method:
* <pre>public void doStoreUser()</pre>
* If it's present, it will be called instead of <code>processElement()</code>.
* <p>Often you want to initialize common data structures, both for regular
* requests as for submissions. The {@link ElementSupport#initialize()} method
* can be used for that. It will be the first element's method that is called
* in a fully setup element context. When extending {@link Element}, the
* easiest is to simply overload the {@link ElementSupport#initialize()}
* method, otherwise an {@link ElementInitializer} has to be registered in the
* {@link #noticeElement} method.
* <p>RIFE also supports setter-based dependency injection for element
* properties, inputs, global variables and submission parameters. If setter
* methods are present that correspond to declared variable names, they will
* be automatically invoked with the available values. Of course, you can
* always retrieve values through the dedicated ElementSupport methods for
* {@link ElementSupport#getProperty properties}, {@link
* ElementSupport#getInput inputs} and {@link ElementSupport#getParameter
* submission parameters}.
*
* @author Geert Bevin (gbevin[remove] at uwyn dot com)
* @version $Revision: 3634 $
* @since 1.0
*/
public interface ElementAware
{
/**
* This method is called immediately after the instantiation of the
* element to provide the support object that allows the element to
* function in the current context. Note that the context is not setup
* yet, the bridge object is merely provided at this stage.
* <p>It's good practice to store the <code>elementSupport</code>
* parameter in a member variable of the element, making it possible to
* use it from any method in the element.
* <p>This method should also be used to provide the elementSupport
* instance with an {@link ElementDeployer}, an {@link ElementInitializer}
* and an {@link ElementChildTrigger}, if they are needed.
*
* @param elementSupport the <code>ElementSupport</code> instance for this
* request and this element
* @see ElementSupport
* @since 1.0
*/
public void noticeElement(ElementSupport elementSupport);
/**
* The default entry point that will be called when a request arrives.
*
* @since 1.0
*/
public void processElement() throws EngineException;
}
|