KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > wings > 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 JavaDoc name, String JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags