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