001: /*
002: * Copyright 2000,2005 wingS development team.
003: *
004: * This file is part of wingS (http://wingsframework.org).
005: *
006: * wingS is free software; you can redistribute it and/or modify
007: * it under the terms of the GNU Lesser General Public License
008: * as published by the Free Software Foundation; either version 2.1
009: * of the License, or (at your option) any later version.
010: *
011: * Please see COPYING for the complete licence.
012: */
013: package org.wings;
014:
015: /**
016: * For components that take part in the event dispatching process.
017: * <p/>
018: * WingS event dispatching is complex. This is because we have to process many
019: * requests at once (asynchronous user interaction). There are three levels of
020: * dispatching:
021: * <ol>
022: * <li>process http requests ({@link #processLowLevelEvent}): If a component is
023: * registered at the session specific
024: * {@link org.wings.session.LowLevelEventDispatcher} it gets all the
025: * parameters is is registered for. This parameter consists of a name-value
026: * pair. Most time the component itself has encoded this parameter, so it is
027: * able to decode it and change its internal state. This should be done in
028: * {@link #processLowLevelEvent}. Be careful, the change of the internal state shold
029: * not trigger any events, because in case of a form request, many requests are
030: * processed and many states of components are changed, so if you trigger an
031: * event, the listener may access a component which has not yet processed its
032: * request parameters and so it is in an inconsistent state.
033: * </li>
034: * <li>fire intermediate events: fire events which describes a "in progress"
035: * state change, like TreeWillExpand, or ListSelectionEvent with
036: * getIsAdjusting() true, ...
037: * After this level are components must be in a consistant state
038: * </li>
039: * <li>fire final events: fire remaining events. In this level all events, which
040: * are important to an application should be fired. All listeners, which are
041: * notified in this level can assume that the components are in a consistent
042: * (considering user interaction) state.
043: * </li>
044: * </ol>
045: *
046: * @author <a href="mailto:haaf@mercatis.de">Armin Haaf</a>
047: */
048: public interface LowLevelEventListener {
049: /**
050: * Deliver low level/http events (parameters).
051: * The name-value-pairs of the HTTPRequest are considered low level events.
052: *
053: * @param name the name-value-pair's name
054: * @param values the name-value-pair's values
055: */
056: void processLowLevelEvent(String name, String[] values);
057:
058: /**
059: * The id of an event which will be forwarded by the dispatcher to this
060: * component for processing. A component is registered at the
061: * {@link org.wings.session.LowLevelEventDispatcher dispatcher}. This
062: * dispatcher forwards servlet parameters (low level events) to each
063: * LowLevelEventListener registered for this event. A LowLevelEventListener
064: * is registered for an event, if the event id is equals to the result of
065: * this method.
066: */
067: String getLowLevelEventId();
068:
069: /**
070: * If the dispatcher is configured to use named event, the return value of
071: * this method is used to identiy a LowLevelEventListener by name. E.g. in a
072: * http request you might give an action a special name, like
073: * "ActivateUpload" to make uploads possible. This action is a SButton in
074: * wings with the name "ActivateUpload" and an ActionListener which make the
075: * upload form visible. A designer might call your servlet with
076: * "servlet/_?ActivateUpload=1" to make the upload form visible by hand. Be
077: * careful, this so called "Named Events" are not under control of wings, so
078: * they will no be outtimed and might lead to strange effects.
079: */
080: String getName();
081:
082: /**
083: * fire events which describes a "in progress"
084: * state change, like TreeWillExpand, or ListSelectionEvent with
085: * getIsAdjusting() true, ...
086: */
087: void fireIntermediateEvents();
088:
089: /**
090: * fire remaining events. In this level all events, which
091: * are important to an application should be fired. All listeners, which are
092: * notified in this level can assume that the components are in a consistent
093: * (considering user interaction) state.
094: */
095: void fireFinalEvents();
096:
097: /**
098: * SCompontents are typically implemntors of this interface. No disabled component
099: * should receive any event.
100: * @return <code>true</code>, if LowLevelEventListener should be addressed
101: */
102: boolean isEnabled();
103:
104: /**
105: * Asks the low-level event listener if epoch checking should be perfomed on it.
106: * If <code>true</code> the Dispatcher will ignore request originating from old views
107: * (typically iniated by triggering browser back and clicking somewhere.)
108: * @return <code>true</code> if epoch checking should be perfomed, <code>false</code>
109: * if all request for this component should be processed.
110: */
111: boolean isEpochCheckEnabled();
112: }
|