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.request;
021:
022: /**
023: * Represents a request for notification of an event.
024: * Examples include
025: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.BreakpointReachedRequest}
026: * and
027: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.ProcessInstanceCreatedRequest}.
028: * When an event occurs for which an enabled request is present,
029: * an
030: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventSet}
031: * will be placed on the
032: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventQueue}.
033: * The collection of existing event requests is managed
034: * by the
035: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.EventRequestManager}.
036: * <br><br>
037: * Any method on EventRequest or which takes EventRequest as an parameter may
038: * throw
039: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.BpelEngineDisconnectedException}
040: * if the target BPEL Engine is disconnected and the
041: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.BpelEngineDisconnectedEvent}
042: * has been or is available to be read from the
043: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.event.EventQueue}.
044: *
045: * @author Alexander Zgursky
046: */
047: public interface EventRequest {
048:
049: /**
050: * Enables or disables this event request.
051: * While this event request is disabled, the event request will be ignored
052: * by the target BPEL Engine. Disabled event requests still exist, and are
053: * included in
054: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.EventRequestManager#getAllRequests}.
055: *
056: * @param val true if the request is to be enabled; false otherwise.
057: *
058: * @throws InvalidRequestStateException
059: * if this request has been deleted
060: * @throws org.netbeans.modules.bpel.debugger.spi.plugin.IncompatibleProcessInstanceStateException
061: * if this is a
062: * {@link org.netbeans.modules.bpel.debugger.spi.plugin.request.StepCompletedRequest},
063: * val is <code>true</code>, and the process instance named in
064: * the request has completed
065: */
066: void setEnabled(boolean val);
067:
068: /**
069: * Determines if this event request is currently enabled.
070: *
071: * @return <code>true</code> if enabled; <code>false</code> otherwise
072: */
073: boolean isEnabled();
074:
075: /**
076: * Add an arbitrary key/value "property" to this request.
077: * The property can be used by the BPEL Debugger Core to associate
078: * its information with the request; these properties are not used
079: * internally by the BPEL Debugger Plugin.
080: * <br><br>
081: * The get/putProperty methods provide access to a small per-instance map.
082: * This is not to be confused with {@link java.util.Properties}.
083: * <br><br>
084: * If value is <code>null</code> this method will remove the property.
085: */
086: void putProperty(Object key, Object value);
087:
088: /**
089: * Returns the value of the property with the specified key.
090: * Only properties added with
091: * {@link #putProperty} will return a non-null value.
092: *
093: * @return the value of this property or <code>null</code>
094: */
095: Object getProperty(Object key);
096:
097: /**
098: * Determines the process instance to suspend when the requested event
099: * occurs in the target BPEL Engine.
100: *
101: * Use {@link SuspendPolicy#SUSPEND_ALL}
102: * to suspend all process instances in the target BPEL Engine.
103: * Use {@link SuspendPolicy#SUSPEND_EVENT_PROCESS_INSTANCE} to suspend only
104: * the process instance which generated the event (the default).
105: * Use {@link SuspendPolicy#SUSPEND_NONE} to suspend no process instances.
106: *
107: * @throws InvalidRequestStateException
108: * if this request is currently enabled or has been deleted.
109: * Suspend policy may only be set in disabled requests.
110: */
111: void setSuspendPolicy(SuspendPolicy policy);
112:
113: /**
114: * Returns a value which describes the process instances to suspend when
115: * the requested event occurs in the target BPEL Engine.
116: *
117: * @return the current suspend mode for this request
118: */
119: SuspendPolicy getSuspendPolicy();
120:
121: /**
122: * Defines the possible values for suspend policy.
123: */
124: enum SuspendPolicy {
125:
126: /**
127: * Suspend all process instances when the event occurs.
128: */
129: SUSPEND_ALL,
130:
131: /**
132: * Suspend only the process instance which generated
133: * the event when the event occurs.
134: */
135: SUSPEND_EVENT_PROCESS_INSTANCE,
136:
137: /**
138: * Suspend no process instances when the event occurs.
139: */
140: SUSPEND_NONE
141: }
142: }
|