/*******************************************************************************
* Copyright (c) 2000, 2011 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdt.debug.core;
import org.eclipse.debug.core.DebugException;
import org.eclipse.jdt.core.dom.Message;
/**
* Provides event and error notification for Java breakpoints. Listeners
* register with the <code>JDIDebugModel</code>.
* <p>
* Since 3.5, clients can also register breakpoint listeners using the
* <code>org.eclipse.jdt.debug.breakpointListeners</code> extension point. A
* listener can be contributed to receive notifications from all Java
* breakpoints or receive notifications about specific breakpoints by
* programmatically registering the extension with a breakpoint.
* </p>
* <p>
* Clients are intended to implement this interface.
* </p>
*
* @since 2.0
* @see JDIDebugModel
* @see IJavaBreakpoint
*/
public interface IJavaBreakpointListener {
/**
* Return code in response to a "breakpoint hit" notification, indicating a
* vote to suspend the associated thread.
*
* @since 3.0
*/
public static int SUSPEND = 0x0001;
/**
* Return code in response to a "breakpoint hit" notification, indicating a
* vote to not suspend (i.e. resume) the associated thread.
*
* @since 3.0
*/
public static int DONT_SUSPEND = 0x0002;
/**
* Return code in response to an "installing" notification, indicating a
* vote to install the associated breakpoint.
*
* @since 3.0
*/
public static int INSTALL = 0x0001;
/**
* Return code in response to an "installing" notification, indicating a
* vote to not install the associated breakpoint.
*
* @since 3.0
*/
public static int DONT_INSTALL = 0x0002;
/**
* Return code indicating that this listener should not be considered in a
* vote to suspend a thread or install a breakpoint.
*
* @since 3.0
*/
public static int DONT_CARE = 0x0004;
/**
* Notification that the given breakpoint is about to be added to the
* specified target. This message is sent before the breakpoint is actually
* added to the debut target (i.e. this is a pre-notification).
*
* @param target
* Java debug target
* @param breakpoint
* Java breakpoint
*/
public void addingBreakpoint(IJavaDebugTarget target,
IJavaBreakpoint breakpoint);
/**
* Notification that the given breakpoint is about to be installed in the
* specified target, in the specified type. Allows this listener to vote to
* determine if the given breakpoint should be installed in the specified
* type and target. If at least one listener votes to <code>INSTALL</code>,
* the breakpoint will be installed. If there are no votes to install the
* breakpoint, there must be at least one <code>DONT_INSTALL</code> vote to
* cancel the installation. If all listeners vote <code>DONT_CARE</code>,
* the breakpoint will be installed by default.
*
* @param target
* Java debug target
* @param breakpoint
* Java breakpoint
* @param type
* the type (class or interface) the breakpoint is about to be
* installed in or <code>null</code> if the given breakpoint is
* not installed in a specific type (one of
* <code>IJavaClassType</code>, <code>IJavaInterfaceType</code>,
* or <code>IJavaArrayType</code>)
* @return whether the the breakpoint should be installed in the given type
* and target, or whether this listener doesn't care - one of
* <code>INSTALL</code>, <code>DONT_INSTALL</code>, or
* <code>DONT_CARE</code>
* @since 3.0
*/
public int installingBreakpoint(IJavaDebugTarget target,
IJavaBreakpoint breakpoint, IJavaType type);
/**
* Notification that the given breakpoint has been installed in the
* specified target.
*
* @param target
* Java debug target
* @param breakpoint
* Java breakpoint
*/
public void breakpointInstalled(IJavaDebugTarget target,
IJavaBreakpoint breakpoint);
/**
* Notification that the given breakpoint has been hit in the specified
* thread. Allows this listener to vote to determine if the given thread
* should be suspended in response to the breakpoint. If at least one
* listener votes to <code>SUSPEND</code>, the thread will suspend. If there
* are no votes to suspend the thread, there must be at least one
* <code>DONT_SUSPEND</code> vote to avoid the suspension (resume). If all
* listeners vote <code>DONT_CARE</code>, the thread will suspend by
* default.
* <p>
* The thread the breakpoint has been encountered in is now suspended.
* Listeners may query thread state and perform evaluations. All subsequent
* breakpoints in this thread will be ignored until voting has completed.
* </p>
*
* @param thread
* Java thread
* @param breakpoint
* Java breakpoint
* @return whether the thread should suspend or whether this listener
* doesn't care - one of <code>SUSPEND</code>,
* <code>DONT_SUSPEND</code>, or <code>DONT_CARE</code>
* @since 3.0
*/
public int breakpointHit(IJavaThread thread, IJavaBreakpoint breakpoint);
/**
* Notification that the given breakpoint has been removed from the
* specified target.
*
* @param target
* Java debug target
* @param breakpoint
* Java breakpoint
*/
public void breakpointRemoved(IJavaDebugTarget target,
IJavaBreakpoint breakpoint);
/**
* Notification that the given breakpoint had runtime errors in its
* conditional expression.
*
* @param breakpoint
* the breakpoint
* @param exception
* the debug exception that occurred evaluating the breakpoint's
* condition
*/
public void breakpointHasRuntimeException(IJavaLineBreakpoint breakpoint,
DebugException exception);
/**
* Notification that the given breakpoint has compilation errors in its
* conditional expression.
*
* @param breakpoint
* the breakpoint
* @param errors
* the compilation errors in the breakpoint's condition
*/
public void breakpointHasCompilationErrors(IJavaLineBreakpoint breakpoint,
Message[] errors);
}