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 &quot;AS IS&quot;, 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