001: /*
002: * The contents of this file are subject to the terms of the Common Development
003: * and Distribution License (the License). You may not use this file except in
004: * compliance with the License.
005: *
006: * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
007: * or http://www.netbeans.org/cddl.txt.
008: *
009: * When distributing Covered Code, include this CDDL Header Notice in each file
010: * and include the License file at http://www.netbeans.org/cddl.txt.
011: * If applicable, add the following below the CDDL Header, with the fields
012: * enclosed by brackets [] replaced by your own identifying information:
013: * "Portions Copyrighted [year] [name of copyright owner]"
014: *
015: * The Original Software is NetBeans. The Initial Developer of the Original
016: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
017: * Microsystems, Inc. All Rights Reserved.
018: */
019:
020: package org.netbeans.modules.bpel.debugger.spi.plugin.event;
021:
022: /**
023: * Manager of incoming debugger events for a target
024: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.BpelEngine}.
025: * Events are always grouped in
026: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}s.
027: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}s
028: * generated by the BPEL Debugger Plugin can be read here.
029: * There is one instance of EventQueue assigned to a particular
030: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.BpelEngine}. It's
031: * provided by the BPEL Debugger Plugin and can be obtained by invoking
032: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.BpelEngine#getEventQueue}.
033: * <br><br>
034: * Some events cause the suspension of process instances -
035: * those which are issued using
036: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.EventRequest}s
037: * with a
038: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.EventRequest.SuspendPolicy
039: * suspend policy} of
040: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.EventRequest.SuspendPolicy#SUSPEND_ALL}
041: * or
042: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.EventRequest.SuspendPolicy#SUSPEND_EVENT_PROCESS_INSTANCE}.
043: * If these suspensions are not resumed the corresponding process instances
044: * will hang. Thus, it is always good policy to
045: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventQueue#remove}
046: * every event set from the event queue until an
047: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}
048: * containing a
049: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.BpelEngineDisconnectedEvent}
050: * is read.
051: *
052: * @author Alexander Zgursky
053: */
054: public interface EventQueue {
055:
056: /**
057: * Waits forever for the next available
058: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}.
059: * When
060: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}
061: * becomes available, removes it from the EventQueue
062: * and returns as the result.
063: *
064: * @return the next
065: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}
066: *
067: * @throws InterruptedException
068: * if another thread has interrupted this thread
069: * @throws org.netbeans.modules.bpel.debugger.spi.plugin.BpelEngineDisconnectedException
070: * if the
071: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.BpelEngine}
072: * has been disconnected. Note this will always
073: * be preceded by a
074: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.BpelEngineDisconnectedEvent}.
075: */
076: EventSet remove() throws InterruptedException;
077:
078: /**
079: * Waits a specified time for the next available
080: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}.
081: * When
082: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}
083: * becomes available, removes it from the EventQueue
084: * and returns as the result.
085: *
086: * @return the next
087: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet},
088: * or <code>null</code> if there is a timeout.
089: *
090: * @throws InterruptedException
091: * if another thread has interrupted this thread
092: * @throws org.netbeans.modules.bpel.debugger.spi.plugin.BpelEngineDisconnectedException
093: * if the
094: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.BpelEngine}
095: * has been disconnected. Note this will always
096: * be preceded by a
097: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.BpelEngineDisconnectedEvent}.
098: * @throws IllegalArgumentException
099: * if the timeout argument contains an illegal value
100: */
101: EventSet remove(long timeout) throws InterruptedException;
102: }
|