debug/org.eclipse.cdt.debug.core/src/org/eclipse/cdt/debug/core/model/ICLineBreakpoint2.java

/*******************************************************************************
 * Copyright (c) 2012 Wind River Systems 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:
 *     Wind River Systems - initial API and implementation
 *******************************************************************************/
package org.eclipse.cdt.debug.core.model;

import org.eclipse.core.resources.IMarker;
import org.eclipse.core.runtime.CoreException;

/**
 * Line breakpoint extension that allows a breakpoint to be relocated by a 
 * debugger to a valid source line.  
 * <p>Clients which can determine a valid source based on debuggers symbol 
 * information should call the various <code>setInstalled...</code> methods with 
 * the corrected location attributes. Note, there is no <code>setInstalledSourceHandle</code>, 
 * clients should call {@link ICBreakpoint#setSourceHandle(String)}.  If multiple
 * clients try to change the installed breakpoint location, the last call will 
 * take precedence.  This way debuggers may update the location upon active debug 
 * context change.  <br/>
 * The original breakpoint location as configured by the user can always be 
 * retrieved using the <code>getRequested...</code> methods.
 * </p>   
 * @since 7.2
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface ICLineBreakpoint2 extends ICLineBreakpoint, ICBreakpoint2 {

    /**
     * Breakpoint attribute storing the original requested line for this breakpoint
     * This attribute is a <code>int</code>.
     */
    public static final String REQUESTED_LINE = "requestedLine"; //$NON-NLS-1$

    /**
     * Breakpoint attribute storing the original requested column for this breakpoint
     * This attribute is a <code>int</code>.
     */
    public static final String REQUESTED_CHAR_START = "requestedCharStart"; //$NON-NLS-1$

    /**
     * Breakpoint attribute storing the original requested column for this breakpoint
     * This attribute is a <code>int</code>.
     */
    public static final String REQUESTED_CHAR_END = "requestedCharEnd"; //$NON-NLS-1$

    /**
     * Breakpoint attribute storing the original requested file name this breakpoint
     * is set in. 
     * This attribute is a <code>String</code>.
     */
    public static final String REQUESTED_SOURCE_HANDLE = "requestedSourceHandle"; //$NON-NLS-1$ 

    /**
     * Breakpoint attribute which is set if the installed line number of a
     * breakpoint is changed.
     * 
     * Triggers an update of the installed location, if set.
     * 
     * This attribute is a <code>Boolean</code>.
     * 
     * @since 8.0
     */
    public static final String RESET_INSTALLED_LOCATION = "resetInstalledLocation"; //$NON-NLS-1$

    /**
     * Returns the line number where the breakpoint was set before it was relocated to a 
     * valid source line.  
     * 
     * @return Returns the requested line number attribute.
     * @exception CoreException if unable to access the property on this breakpoint's
     *  underlying marker
     */
    public int getRequestedLine() throws CoreException;

    /**
     * Sets the line number where the breakpoint should be set.  
     * 
     * @param The requested line number attribute.
     * @exception CoreException if unable to access the property on this breakpoint's
     *  underlying marker
     */
    public void setRequestedLine(int line) throws CoreException;

    /**
     * Returns starting source index where the breakpoint was set before it 
     * was moved to a valid source location.  
     * 
     * @return Returns the requested start index attribute.
     * @exception CoreException if unable to access the property on this breakpoint's
     *  underlying marker
     */
    public int getRequestedCharStart() throws CoreException;


    /**
     * Sets the starting source index where the breakpoint should be set.
     * 
     * @param The requested start index attribute.
     * @exception CoreException if unable to access the property on this breakpoint's
     *  underlying marker
     */
    public void setRequestedCharStart(int charStart) throws CoreException;

    /**
     * Returns ending source index where the breakpoint was set before it 
     * was moved to a valid source location.  
     * 
     * @return Returns the requested end index attribute.
     * @exception CoreException if unable to access the property on this breakpoint's
     *  underlying marker
     */
    public int getRequestedCharEnd() throws CoreException;

    /**
     * Sets the staring source index where the breakpoint should be set.
     * 
     * @param The requested end index attribute.
     * @exception CoreException if unable to access the property on this breakpoint's
     *  underlying marker
     */
    public void setRequestedCharEnd(int charEnd) throws CoreException;
    
    /**
     * Returns the file name where the breakpoint was set before it was relocated to a 
     * valid file.
     * 
     * @return Returns the requested file name.
     * @exception CoreException if unable to access the property on this breakpoint's
     *  underlying marker
     */
    public String getRequestedSourceHandle() throws CoreException;

    /**
     * Sets the file name where the breakpoint should be set.  May be an empty string
     * if the file is not known.  
     * 
     * @param Requested file name.
     * @exception CoreException if unable to access the property on this breakpoint's
     *  underlying marker
     */
    public void setRequestedSourceHandle(String fileName) throws CoreException;

    /**
     * Sets the line number where the breakpoint is actually installed.   This 
     * method only updates the {@link IMarker#LINE_NUMBER} attribute and the 
     * breakpoint message. 
     * 
     * @param line Installed line number
     * @throws CoreException if unable to access the property 
     *  on this breakpoint's underlying marker
     */
    public void setInstalledLineNumber(int line) throws CoreException;    

    /**
     * Sets the start index where the breakpoint is actually installed. This method 
     * only updates the {@link IMarker#CHAR_START} attribute and the breakpoint 
     * message. 
     * 
     * @param charStart Installed char start
     * @throws CoreException
     */
    public void setInstalledCharStart(int charStart) throws CoreException;
    
    /**
     * Sets the end index where the breakpoint is actually installed.  This method 
     * only updates the {@link IMarker#CHAR_END} attribute and the breakpoint 
     * message. 
     * 
     * @param charEnd Installed char start
     * @throws CoreException
     */
    public void setInstalledCharEnd(int charStart) throws CoreException;
    
    /**
     * Resets the breakpoint location back to the values specified by the 
     * REQUESTED_* attributes.  This operation should be called automatically
     * by the implementation when the install count is reset to 0, and does
     * not need to be called by the client at that time.
     * 
     * @throws CoreException
     */
    public void resetInstalledLocation() throws CoreException;
}