LowLevelEventListener


1   /*
2    * $Id: LowLevelEventListener.java,v 1.6 2005/04/08 15:05:18 blueshift Exp $
3    * Copyright 2000,2005 wingS development team.
4    *
5    * This file is part of wingS (http://www.j-wings.org).
6    *
7    * wingS is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU Lesser General Public License
9    * as published by the Free Software Foundation; either version 2.1
10   * of the License, or (at your option) any later version.
11   *
12   * Please see COPYING for the complete licence.
13   */
14  package org.wings;
15  
16  /**
17   * The LowLevelEventListener interface is implemented by all components
18   * that take part at the event dispatching process.
19   * WingS event dispatching is complex. This is because we have to process many
20   * requests at once (asynchronous user interaction). There are three levels of
21   * dispatching:
22   * <ol>
23   * <li>process http requests ({@link #processLowLevelEvent}): If a component is
24   * registered at the session specific
25   * {@link org.wings.session.LowLevelEventDispatcher} it gets all the
26   * parameters is is registered for. This parameter consists of a name-value
27   * pair. Most time the component itself has encoded this parameter, so it is
28   * able to decode it and change its internal state. This should be done in
29   * {@link #processLowLevelEvent}. Be careful, the change of the internal state shold
30   * not trigger any events, because in case of a form request, many requests are
31   * processed and many states of components are changed, so if you trigger an
32   * event, the listener may access a component which has not yet processed its
33   * request parameters and so it is in an inconsistent state.
34   * </li>
35   * <li>fire intermediate events: fire events which describes a "in progress"
36   * state change, like TreeWillExpand, or ListSelectionEvent with
37   * getIsAdjusting() true, ...
38   * After this level are components must be in a consistant state
39   * </li>
40   * <li>fire final events: fire remaining events. In this level all events, which
41   * are important to an application should be fired. All listeners, which are
42   * notified in this level can assume that the components are in a consistent
43   * (considering user interaction) state.
44   * </li>
45   * </ol>
46   *
47   * @author <a HREF="mailto:haaf@mercatis.de">Armin Haaf</a>
48   * @version $Revision: 1.6 $
49   */
50  public interface LowLevelEventListener {
51      /**
52       * Deliver low level/http events (parameters).
53       * The name-value-pairs of the HTTPRequest are considered low level events.
54       *
55       * @param name  the name-value-pair's name
56       * @param values the name-value-pair's values
57       */
58      void processLowLevelEvent(String   name, String  [] values);
59  
60      /**
61       * The id of an event which will be forwarded by the dispatcher to this
62       * component for processing. A component is registered at the
63       * {@link org.wings.session.LowLevelEventDispatcher dispatcher}. This
64       * dispatcher forwards servlet parameters (low level events) to each
65       * LowLevelEventListener registered for this event. A LowLevelEventListener
66       * is registered for an event, if the event id is equals to the result of
67       * this method.
68       */
69      String   getLowLevelEventId();
70  
71      /**
72       * Get the encoded low level event id. This is a convenience method for
73       * SComponent.encodeLowLevelEventId(getLowLevelEventId());
74       * Encodes a low level event id for using it in a request parameter. Every
75       * {@link LowLevelEventListener} should encode its LowLevelEventId before
76       * using it in a request parameter. This encoding adds consistency checking
77       * for outtimed requests ("Back Button"). Mainly used in CG's
78       */
79      String   getEncodedLowLevelEventId();
80  
81      /**
82       * If the dispatcher is configured to use named event, the return value of
83       * this method is used to identiy a LowLevelEventListener by name. E.g. in a
84       * http request you might give an action a special name, like
85       * "ActivateUpload" to make uploads possible. This action is a SButton in
86       * wings with the name "ActivateUpload" and an ActionListener which make the
87       * upload form visible. A designer might call your servlet with
88       * "servlet/_?ActivateUpload=1" to make the upload form visible by hand. Be
89       * careful, this so called "Named Events" are not under control of wings, so
90       * they will no be outtimed and might lead to strange effects.
91       */
92      String   getName();
93  
94      /**
95       * fire events which describes a "in progress"
96       * state change, like TreeWillExpand, or ListSelectionEvent with
97       * getIsAdjusting() true, ...
98       */
99      void fireIntermediateEvents();
100 
101     /**
102      * fire remaining events. In this level all events, which
103      * are important to an application should be fired. All listeners, which are
104      * notified in this level can assume that the components are in a consistent
105      * (considering user interaction) state.
106      */
107     void fireFinalEvents();
108 
109     /**
110      * SCompontents are typically implemntors of this interface. No disabled component
111      * should receive any event.
112      * @return <code>true</code>, if LowLevelEventListener should be addressed
113      */
114     boolean isEnabled();
115 
116     /**
117      * Asks the low-level event listener if epoch checking should be perfomed on it.
118      * If <code>true</code> the Dispatcher will ignore request originating from old views
119      * (typically iniated by triggering browser back and clicking somewhere.)
120      * @return <code>true</code> if epoch checking should be perfomed, <code>false</code>
121      * if all request for this component should be processed.
122      */
123     boolean isEpochCheckEnabled();
124 }
125
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags