001: /*
002: * Jacareto Copyright (c) 2002-2005
003: * Applied Computer Science Research Group, Darmstadt University of
004: * Technology, Institute of Mathematics & Computer Science,
005: * Ludwigsburg University of Education, and Computer Based
006: * Learning Research Group, Aachen University. All rights reserved.
007: *
008: * Jacareto is free software; you can redistribute it and/or
009: * modify it under the terms of the GNU General Public
010: * License as published by the Free Software Foundation; either
011: * version 2 of the License, or (at your option) any later version.
012: *
013: * Jacareto is distributed in the hope that it will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016: * General Public License for more details.
017: *
018: * You should have received a copy of the GNU General Public
019: * License along with Jacareto; if not, write to the Free
020: * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
021: *
022: */
023:
024: package jacareto.catching;
025:
026: import jacareto.eventmask.AWTEventMask;
027: import jacareto.eventmask.EmptyEventMask;
028: import jacareto.system.Environment;
029: import jacareto.system.EnvironmentMember;
030:
031: import java.util.EventObject;
032:
033: /**
034: * Abstract superclass for classes which want to get system-wide dispatched events from the {@link
035: * jacareto.catching.EventListener} instance during a capture process. Events can be either AWT
036: * events or other events. Catchers mustn't handle all types of events. They decide which AWT
037: * events they want to handle by defining an AWT event mask, and which other events to handle by
038: * overwriting the method {@link #handlesEventObject(EventObject)}.
039: *
040: * @author Thomas Leonhard, <a href="mailto:cspannagel@web.de">Christian Spannagel</a> (Version
041: * 1.7)
042: * @version 1.8
043: */
044: public abstract class Catcher extends EnvironmentMember {
045: /** Indicates whether this is instance is catching events or not. */
046: private boolean isRunning;
047:
048: /** The event mask of this catcher. */
049: private AWTEventMask eventMask;
050:
051: /** Indicates if the catcher can be stopped or not. */
052: private boolean isStoppable;
053:
054: /**
055: * Creates a new catcher which is not running with the specified env and event mask. The
056: * catcher can be stopped.
057: *
058: * @param env DOCUMENT ME!
059: * @param eventMask DOCUMENT ME!
060: */
061: public Catcher(Environment env, AWTEventMask eventMask) {
062: super (env);
063: isRunning = false;
064: setAWTEventMask(eventMask);
065: setStoppable(true);
066: }
067:
068: /**
069: * Creates a new catcher which is not running with the specified env and an empty event mask.
070: *
071: * @param env DOCUMENT ME!
072: */
073: public Catcher(Environment env) {
074: this (env, new EmptyEventMask(env));
075: }
076:
077: /**
078: * Starts the catching of events.
079: */
080: public void start() {
081: if (!isRunning()) {
082: isRunning = true;
083: getLogger().debug(
084: getLanguage().getString(
085: "Catching.Catcher.Msg.Start")
086: + " " + getClass().getName());
087: }
088: }
089:
090: /**
091: * Stops catching if the catcher can be stopped.
092: */
093: public void stop() {
094: if (isStoppable() && isRunning()) {
095: isRunning = false;
096: getLogger().debug(
097: getLanguage()
098: .getString("Catching.Catcher.Msg.Stop")
099: + " " + getClass().getName());
100: }
101: }
102:
103: /**
104: * Returns whether this catcher is catching or not
105: *
106: * @return <code>true</code> if the object is catching events
107: */
108: public boolean isRunning() {
109: return isRunning;
110: }
111:
112: /**
113: * Returns whether this catcher can be stopped or not (in the latter case the method {@link
114: * #stop()} does noting).
115: *
116: * @return <code>true</code> if the catcher can be stopped, otherwise <code>false</code>
117: */
118: public boolean isStoppable() {
119: return isStoppable;
120: }
121:
122: /**
123: * Sets whether this catcher can be stopped or not (in the latter case the method {@link
124: * #stop()} does noting).
125: *
126: * @param isStoppable <code>true</code> if the catcher can be stopped, otherwise
127: * <code>false</code>
128: */
129: public void setStoppable(boolean isStoppable) {
130: this .isStoppable = isStoppable;
131: }
132:
133: /**
134: * This method will be invoked by the <code>EventListener</code> instance this catcher is
135: * registered at. The methods in subclasses can be sure that this method will only be called
136: * when their event mask includes the specified event and when they are running.
137: *
138: * @param event the dispatched event
139: *
140: * @return <code>true</code> if other catchers coming later should get the event, too;
141: * otherwise <code>false</code>
142: */
143: public abstract boolean handleEvent(EventObject event);
144:
145: /**
146: * Returns the AWT event mask for the events this catcher is interested in.
147: *
148: * @return the AWT event mask
149: */
150: public AWTEventMask getAWTEventMask() {
151: return eventMask;
152: }
153:
154: /**
155: * Specified the AWT event mask for this listener.
156: *
157: * @param eventMask the AWT event mask
158: */
159: public void setAWTEventMask(AWTEventMask eventMask) {
160: this .eventMask = eventMask;
161: }
162:
163: /**
164: * Returns whether or not this catcher is interested in the given event object which is not an
165: * AWT event. This method returns <code>false</code> by default and can be overwritten in
166: * subclasses.
167: *
168: * @param event EventObject
169: *
170: * @return true, if Catcher handles event
171: */
172: public boolean handlesEventObject(EventObject event) {
173: return false;
174: }
175: }
|