001 package org.LiveGraph.events;
002
003 import org.LiveGraph.LiveGraph;
004
005
006 /**
007 * The system level event types of the LiveGraph event engine are defined here.
008 *
009 * <p>
010 * <strong>LiveGraph</strong>
011 * (<a href="http://www.live-graph.org" target="_blank">http://www.live-graph.org</a>).
012 * </p>
013 * <p>Copyright (c) 2007-2008 by G. Paperin.</p>
014 * <p>File: SystemEvent.java</p>
015 * <p style="font-size:smaller;">Redistribution and use in source and binary forms, with or
016 * without modification, are permitted provided that the following terms and conditions are met:
017 * </p>
018 * <p style="font-size:smaller;">1. Redistributions of source code must retain the above
019 * acknowledgement of the LiveGraph project and its web-site, the above copyright notice,
020 * this list of conditions and the following disclaimer.<br />
021 * 2. Redistributions in binary form must reproduce the above acknowledgement of the
022 * LiveGraph project and its web-site, the above copyright notice, this list of conditions
023 * and the following disclaimer in the documentation and/or other materials provided with
024 * the distribution.<br />
025 * 3. All advertising materials mentioning features or use of this software or any derived
026 * software must display the following acknowledgement:<br />
027 * <em>This product includes software developed by the LiveGraph project and its
028 * contributors.<br />(http://www.live-graph.org)</em><br />
029 * 4. All advertising materials distributed in form of HTML pages or any other technology
030 * permitting active hyper-links that mention features or use of this software or any
031 * derived software must display the acknowledgment specified in condition 3 of this
032 * agreement, and in addition, include a visible and working hyper-link to the LiveGraph
033 * homepage (http://www.live-graph.org).
034 * </p>
035 * <p style="font-size:smaller;">THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY
036 * OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
037 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
038 * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
039 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
040 * IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
041 * </p>
042 *
043 * @author Greg Paperin (<a href="http://www.paperin.org" target="_blank">http://www.paperin.org</a>)
044 * @version {@value org.LiveGraph.LiveGraph#version}
045 *
046 */
047 public enum SystemEvent implements EventType {
048
049
050 /**
051 * <p>Events of this type are <strong>raised</strong> by {@link EventManager} when an
052 * exception occurs during the processing of a LiveGraph event; events of this type
053 * are never <strong>validated</strong>.</p>
054 *
055 * <p>If an {@code Exception} occurs during the normal processing of an event by
056 * any {@code EventListener}, the exception is caught, saved, and the processing of the event
057 * by other listeners is continued. After <em>all</em> {@code EventListener}s have been invoked
058 * for any given event, and if any exceptions have occured during the processing of that event,
059 * all of these exceptions are wrapped into a single instance of {@link EventProcessingException}.
060 * That {@code EventProcessingException} is passed to the {@code EventProducer} that fired the
061 * event responsible for the exception using the
062 * {@link EventProducer#eventProcessingException(Event, EventProcessingException)}-callback. The
063 * producer may consume the exception (by returning {@code true} from the
064 * {@code eventProcessingException}-call) or ignore it (by returning {@code false}). If the
065 * exception is consumed, it will no longer be processed. If the exception is not consumed, the
066 * {@code EventManager} will print it to {@code System.err} and then raise an event of
067 * type {@code SYS_EventProcessingException} in a normal manner with
068 * the {@code EventProcessingException} as the event's {@code getInfoObject()}-parameter.<br />
069 * The purpose of this whole procedure is to make sure that the event dispathing does not break if
070 * an exception occurs and that the application has sufficient oportunity to handle exceptions.</p>
071 *
072 * <p>If an {@code Error} (rather than an {@code Exception}) occurs during the normal processing
073 * of an event by any {@code EventListener}, the processing of that event is <em>not</em> continued
074 * by other listeners, as in the case of {@code Exception}s and {@code RuntimeException}s.
075 * Instead, the processing of the current event is terminated, the error is wrapped in an instance
076 * of {@link EventProcessingException}, and then processed as described above.</p>
077 *
078 * <p>If an exception or error occurs during the processing of
079 * a {@code SYS_EventProcessingException}-event, the {@code EventManager} will behave as described
080 * above, with the difference that no additional {@code SYS_EventProcessingException}-event will be
081 * raised.</p>
082 *
083 * <p>The main event diapatching loop is protected by a try-catch-all block. It cannot be reminated by
084 * an event or by an exception/error in an event handler. If the application wishes to terminate the
085 * event dispatcher it must call {@link EventManager#shutDownWhenFinished()}
086 * or {@link EventManager#shutDownImmediately()}. However, in most cases the event dispatcher should
087 * never be accessed by an application directly (other than to raise events). API users should
088 * use {@link LiveGraph#disposeGUIAndExit()} to correctly free LiveGraph resources.</p>
089 *
090 * <p>When issuing events of type {@code SYS_EventProcessingException},
091 * {@code EventManager} initialises the event info parameters as follows:
092 * <table>
093 * <tr><th>Info parameter</th> <th>Value</th></tr>
094 * <tr><td>{@code getInfoBoolean()}</td> <td><em>unspecified</em></td></tr>
095 * <tr><td>{@code getInfoLong()}</td> <td><em>unspecified</em></td></tr>
096 * <tr><td>{@code getInfoDouble()}</td> <td><em>unspecified</em></td></tr>
097 * <tr><td>{@code getInfoObject()}</td> <td>The {@code EventProcessingException} object</td></tr>
098 * </table>
099 * </p>
100 */
101 SYS_EventProcessingException,
102
103 /**
104 * Events if this type should not cause any action; such events may be used for housekeeping purposes
105 * such as to notifying the listeners that the event manager is active, pooling the event queue,
106 * measuring the event turnaround time, making sure that all events enqueued up to a certain point
107 * are processed or others.
108 * <table>
109 * <tr><th>Info parameter</th> <th>Value</th></tr>
110 * <tr><td>{@code getInfoBoolean()}</td> <td><em>unspecified</em></td></tr>
111 * <tr><td>{@code getInfoLong()}</td> <td><em>unspecified</em></td></tr>
112 * <tr><td>{@code getInfoDouble()}</td> <td><em>unspecified</em></td></tr>
113 * <tr><td>{@code getInfoObject()}</td> <td><em>unspecified</em></td></tr>
114 * </table>
115 */
116 @Validation(Validation.Requirement.NEVER_VALIDATE)
117 SYS_NoOp,
118
119 } // public enum SystemEvent