path: root/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/IBreakpoints.java

/*******************************************************************************
 * Copyright (c) 2007, 2013 Wind River Systems, Inc. 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.tcf.services;

import java.util.Map;

import org.eclipse.tcf.protocol.IService;
import org.eclipse.tcf.protocol.IToken;


/**
 * Breakpoint is represented by unique identifier and set of properties.
 * Breakpoint identifier (String id) needs to be unique across all hosts and targets.
 *
 * Breakpoint properties (Map<String,Object>) is extendible collection of named attributes,
 * which define breakpoint location and behavior. This module defines some common
 * attribute names (see PROP_*), host tools and target agents may support additional attributes.
 *
 * For each breakpoint a target agent maintains another extendible collection of named attributes:
 * breakpoint status (Map<String,Object>, see STATUS_*). While breakpoint properties are
 * persistent and represent user input, breakpoint status reflects dynamic target agent reports
 * about breakpoint current state, like actual addresses where breakpoint is planted or planting errors.
 *
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IBreakpoints extends IService {

    /**
     * Service name.
     */
    static final String NAME = "Breakpoints";

    /**
     * Breakpoint property names.
     */
    static final String
        PROP_ID = "ID",                           // String
        PROP_ENABLED = "Enabled",                 // Boolean
        PROP_TYPE = "BreakpointType",             // String
        PROP_CONTEXT_NAMES = "ContextNames",      // Array
        PROP_CONTEXT_IDS = "ContextIds",          // Array
        PROP_EXECUTABLE_PATHS = "ExecPaths",      // Array
        PROP_CONTEXT_QUERY = "ContextQuery",      // String, see IContextQuery
        PROP_LOCATION = "Location",               // String
        PROP_SIZE = "Size",                       // Number
        PROP_ACCESS_MODE = "AccessMode",          // Number
        PROP_FILE = "File",                       // String
        PROP_LINE = "Line",                       // Number
        PROP_COLUMN = "Column",                   // Number
        PROP_PATTERN = "MaskValue",               // Number
        PROP_MASK = "Mask",                       // Number
        PROP_STOP_GROUP = "StopGroup",            // Array
        PROP_IGNORE_COUNT = "IgnoreCount",        // Number
        PROP_TIME = "Time",                       // Number
        PROP_SCALE = "TimeScale",                 // String
        PROP_UNITS = "TimeUnits",                 // String
        PROP_CONDITION = "Condition",             // String
        PROP_TEMPORARY = "Temporary",             // Boolean
        PROP_EVENT_TYPE = "EventType",            // String
        PROP_EVENT_ARGS = "EventArgs",            // String or Object
        PROP_CLIENT_DATA = "ClientData",          // Object
        PROP_ACTION = "Action";                   // String - expression or script

    /**
     * @deprecated
     */
    static final String
        PROP_CONTEXTNAMES = "ContextNames",       // Array
        PROP_CONTEXTIDS = "ContextIds",           // Array
        PROP_EXECUTABLEPATHS = "ExecPaths",       // Array
        PROP_ACCESSMODE = "AccessMode",           // Number
        PROP_IGNORECOUNT = "IgnoreCount";         // Number

    /**
     * BreakpointType values
     */
    static final String
        TYPE_SOFTWARE = "Software",
        TYPE_HARDWARE = "Hardware",
        TYPE_AUTO = "Auto";

    /**
     * AccessMode values
     */
    static final int
        ACCESSMODE_READ    = 0x01,
        ACCESSMODE_WRITE   = 0x02,
        ACCESSMODE_EXECUTE = 0x04,
        ACCESSMODE_CHANGE  = 0x08;

    /**
     * TimeScale values
     */
    static final String
        TIMESCALE_RELATIVE = "Relative",
        TIMESCALE_ABSOLUTE = "Absolute";

    /**
     * TimeUnits values
     */
    static final String
        TIMEUNIT_NSECS = "Nanoseconds",
        TIMEUNIT_CYCLE_COUNT = "CycleCount",
        TIMEUNIT_INSTRUCTION_COUNT = "InstructionCount";

    /**
     * Breakpoint status field names.
     */
    static final String
        STATUS_INSTANCES = "Instances",         // Array of Map<String,Object>
        STATUS_ERROR = "Error",                 // String
        STATUS_FILE = "File",                   // String
        STATUS_LINE = "Line",                   // Number
        STATUS_COLUMN = "Column";               // Number

    /**
     * Breakpoint instance field names.
     */
    static final String
        INSTANCE_ERROR = "Error",               // String
        INSTANCE_CONTEXT = "LocationContext",   // String
        INSTANCE_ADDRESS = "Address",           // Number
        INSTANCE_SIZE = "Size",                 // Number
        INSTANCE_TYPE = "BreakpointType",       // String
        INSTANCE_MEMORY_CONTEXT = "MemoryContext",// String
        INSTANCE_HIT_COUNT = "HitCount";         // Number

    /**
     * Breakpoint service capabilities.
     */
    static final String
        CAPABILITY_CONTEXT_ID = "ID",                   // String
        CAPABILITY_HAS_CHILDREN = "HasChildren",        // Boolean
        CAPABILITY_BREAKPOINT_TYPE = "BreakpointType",  // Boolean
        CAPABILITY_LOCATION = "Location",               // Boolean
        CAPABILITY_CONDITION = "Condition",             // Boolean
        CAPABILITY_FILE_LINE = "FileLine",              // Boolean
        CAPABILITY_FILE_MAPPING = "FileMapping",        // Boolean
        CAPABILITY_CONTEXT_IDS = "ContextIds",          // Boolean
        CAPABILITY_CONTEXT_NAMES = "ContextNames",      // Boolean
        CAPABILITY_CONTEXT_QUERY = "ContextQuery",      // Boolean
        CAPABILITY_STOP_GROUP = "StopGroup",            // Boolean
        CAPABILITY_TEMPORARY = "Temporary",             // Boolean
        CAPABILITY_IGNORE_COUNT = "IgnoreCount",        // Boolean
        CAPABILITY_ACCESS_MODE = "AccessMode",          // Number
        CAPABILITY_CLIENT_DATA = "ClientData";          // Boolean

    /**
     * @deprecated
     */
    static final String
        CAPABILITY_CONTEXTNAMES = "ContextNames",
        CAPABILITY_CONTEXTIDS = "ContextIds",
        CAPABILITY_IGNORECOUNT = "IgnoreCount",
        CAPABILITY_ACCESSMODE = "AccessMode";

    /**
     * Call back interface for breakpoint service commands.
     */
    interface DoneCommand {
        /**
         * Called when command is done.
         * @param token - command handle.
         * @param error - error object or null.
         */
        void doneCommand(IToken token, Exception error);
    }

    /**
     * Download breakpoints data to target agent.
     * The command is intended to be used only to initialize target breakpoints table
     * when communication channel is open. After that, host should
     * notify target about (incremental) changes in breakpoint data by sending
     * add, change and remove commands.
     *
     * @param properties - array of breakpoints.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken set(Map<String,Object>[] properties, DoneCommand done);

    /**
     * Called when breakpoint is added into breakpoints table.
     * @param properties - breakpoint properties.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken add(Map<String,Object> properties, DoneCommand done);

    /**
     * Called when breakpoint properties are changed.
     * @param properties - breakpoint properties.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken change(Map<String,Object> properties, DoneCommand done);

    /**
     * Tell target to change (only) PROP_ENABLED breakpoint property to 'true'.
     * @param ids - array of enabled breakpoint identifiers.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken enable(String[] ids, DoneCommand done);

    /**
     * Tell target to change (only) PROP_ENABLED breakpoint property to 'false'.
     * @param ids - array of disabled breakpoint identifiers.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken disable(String[] ids, DoneCommand done);

    /**
     * Tell target to remove breakpoints.
     * @param id - unique breakpoint identifier.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken remove(String[] ids, DoneCommand done);

    /**
     * Upload IDs of breakpoints known to target agent.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken getIDs(DoneGetIDs done);

    /**
     * Call back interface for 'getIDs' command.
     */
    interface DoneGetIDs {
        /**
         * Called when 'getIDs' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param ids - IDs of breakpoints known to target agent.
         */
        void doneGetIDs(IToken token, Exception error, String[] ids);
    }

    /**
     * Upload properties of given breakpoint from target agent breakpoint table.
     * @param id - unique breakpoint identifier.
     * @param done - command result call back object.
     */
    IToken getProperties(String id, DoneGetProperties done);

    /**
     * Call back interface for 'getProperties' command.
     */
    interface DoneGetProperties {
        /**
         * Called when 'getProperties' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param properties - properties of the breakpoint.
         */
        void doneGetProperties(IToken token, Exception error, Map<String,Object> properties);
    }

    /**
     * Upload status of given breakpoint from target agent.
     * @param id - unique breakpoint identifier.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken getStatus(String id, DoneGetStatus done);

    /**
     * Call back interface for 'getStatus' command.
     */
    interface DoneGetStatus {
        /**
         * Called when 'getStatus' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param status - status of the breakpoint.
         */
        void doneGetStatus(IToken token, Exception error, Map<String,Object> status);
    }

    /**
     * Report breakpoint service capabilities to clients so they
     * can adjust to different implementations of the service.
     * When called with a null ("") context ID the global capabilities are returned,
     * otherwise context specific capabilities are returned.  A special capability
     * property is used to indicate that all child contexts have the same
     * capabilities.
     * @param id - a context ID or null.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken getCapabilities(String id, DoneGetCapabilities done);

    /**
     * Call back interface for 'getCapabilities' command.
     */
    interface DoneGetCapabilities {
        /**
         * Called when 'getCapabilities' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param capabilities - breakpoints service capabilities description.
         */
        void doneGetCapabilities(IToken token, Exception error, Map<String,Object> capabilities);
    }

    /**
     * Breakpoints service events listener.
     * Note that contextAdded, contextChanged and contextRemoved events carry exactly same set
     * of breakpoint properties that was sent by a client to a target. The purpose of these events is to
     * let all clients know about breakpoints that were created by other clients.
     */
    interface BreakpointsListener {

        /**
         * Called when breakpoint status changes.
         * @param id - unique breakpoint identifier.
         * @param status - breakpoint status.
         */
        void breakpointStatusChanged(String id, Map<String,Object> status);

        /**
         * Called when a new breakpoints are added.
         * @param bps - array of breakpoints.
         */
        void contextAdded(Map<String,Object>[] bps);

        /**
         * Called when breakpoint properties change.
         * @param bps - array of breakpoints.
         */
        void contextChanged(Map<String,Object>[] bps);

        /**
         * Called when breakpoints are removed .
         * @param ids - array of breakpoint IDs.
         */
        void contextRemoved(String[] ids);
    }

    /**
     * Add breakpoints service event listener.
     * @param listener - object that implements BreakpointsListener interface.
     */
    void addListener(BreakpointsListener listener);

    /**
     * Remove breakpoints service event listener.
     * @param listener - object that implements BreakpointsListener interface.
     */
    void removeListener(BreakpointsListener listener);
}