Package com._1c.g5.v8.dt.debug.core.runtime.client

Interface IRuntimeDebugClient

  • public interface IRuntimeDebugClient
    Describes a 1C:Enterprise runtime debug client. 1C:Enterprise runtime debug clients are defined by extensions. An 1C:Enterprise runtime debug client is defined in plugin.xml.

    Following is an example definition of an 1C:Enterprise runtime debug client extension: 

     <extension point="com._1c.g5.v8.dt.debug.core.runtimeDebugClients">
   <client
      class="com.example.ExampleRuntimeDebugClient"
   <supportedDebugServers
         version="com._1c.g5.v8.dt.debug.core.debugServerVersions.8.3.9"></supportedDebugServers>
   </client>
 </extension>

    Performs debug actions and requests on 1C:Enterprise runtime debug server. Also can be used to receive debug events from 1C:Enterprise runtime debug server, see ping() method.

    Next flow of execution is intended:

    • configure client with target debug server
    • connect client with this server
    • perform debug requests and event dispatching
    • disconnect client from target debug server
    • dispose client (if no longer needed)

    This interface is intended to be implemented and registered by clients.

    Clients may use IRuntimeDebugClientProvider to get instances of runtime debug client by the target debug sever URL with the appropriate version.

    See Also:
    IDebugServerVersion, IRuntimeDebugClientProvider

    • Method Detail

      • configure

        void configure​(String debugServerUrl,
               UUID debugServerUuid,
               String infobaseAlias)
        throws RuntimeDebugClientException
        Configure this 1C:Enterprise runtime debug client connection with target debug server by given host and port.

        Clients should call this method before all other debug client usage.

        Parameters:
        debugServerUrl - the debug server URL to configure connection, cannot be null
        debugServerUuid - the debug server UUID to configure connection, cannot be null
        infobaseAlias - the infobase alias, cannot be null
        Throws:
        RuntimeDebugClientException - if the request fails

      • dispose

        void dispose()
      throws RuntimeDebugClientException
        Disposes this 1C:Enterprise runtime client. This causes the client to cleanup any resources that it maintains.

        Clients should call this method, when they are finished performing 1C:Enterprise runtime debug sessions with this 1C:Enterprise runtime debug client.

        Throws:
        RuntimeDebugClientException - if the request fails

      • connect

        AttachDebugUIResult connect​(String password)
                     throws RuntimeDebugClientException
        Connect this 1C:Enterprise runtime debug client to 1C:Enterprise runtime with configured debug server URL and UUID.

        Returns connection state - whether debug client was connected to debug server, not connected or whether authorization is required for this debug server.

        After method successful execution client can start perform debug requests and event dispatching.

        Parameters:
        password - the password to use for debug server connection, can be null if not needed
        Returns:
        connection state result - whether debug client was connected to debug server, not connected or authorization is required for this debug server, never null
        Throws:
        RuntimeDebugClientException - if the request fails

      • disconnect

        boolean disconnect()
            throws RuntimeDebugClientException
        Disconnect this 1C:Enterprise runtime debug client from current configured debug server.

        After method successful execution client can no longer perform debug requests and event dispatching.

        Throws:
        RuntimeDebugClientException - if the request fails

      • initSettings

        void initSettings​(boolean suspend)
           throws RuntimeDebugClientException
        Initialize the debug session with given settings with remote debug server.
        Parameters:
        suspend - whether need to suspend all 1C:Enterprise debug targets on next line, when they entering 1C:Enterprise runtime
        Throws:
        RuntimeDebugClientException - if the request fails

      • attachRuntimeDebugTargets

        void attachRuntimeDebugTargets​(Collection<UUID> debugTargets)
                        throws RuntimeDebugClientException
        Attach a collection of 1C:Enterprise runtime debug targets to current debug process.
        Parameters:
        debugTargets - a collection of 1C:Enterprise runtime debug targets UUIDs to attach, cannot be null
        Throws:
        RuntimeDebugClientException - if the request fails

      • detachRuntimeDebugTargets

        void detachRuntimeDebugTargets​(Collection<UUID> debugTargets)
                        throws RuntimeDebugClientException
        Detach a collection of 1C:Enterprise runtime debug targets with current debug process.
        Parameters:
        debugTargets - a collection of 1C:Enterprise runtime debug targets UUIDs to detach, cannot be null
        Throws:
        RuntimeDebugClientException - if the request fails

      • setLineBreakpoints

        void setLineBreakpoints​(Map<com._1c.g5.v8.dt.internal.debug.core.model.breakpoints.BslModuleInformation,​List<com._1c.g5.v8.dt.internal.debug.core.model.breakpoints.BslLineBreakpointInformation>> modulesBreakpoints)
                 throws RuntimeDebugClientException
        Sets a collection of line breakpoints to the provided BSL modules.
        Parameters:
        modulesBreakpoints - a map of BSL-modules breakpoints, key is BslModuleId, value is BslLineBreakpointInformation, cannot be null
        Throws:
        RuntimeDebugClientException - if the request fails

      • setExceptionBreakpoints

        void setExceptionBreakpoints​(boolean enabled,
                             Iterable<String> exceptions)
                      throws RuntimeDebugClientException
        Set exception breakpoints in 1C:Enterprise runtime.
        Parameters:
        enabled - enable or disable 1C:Eneteprise runtime exception suspending
        exceptions - a list of exceptions, can be null, then 1C:Eneteprise runtime will suspend on any exception
        Throws:
        RuntimeDebugClientException - if the request fails

      • ping

        List<? extends DBGUIExtCmdInfoBase> ping()
                                  throws RuntimeDebugClientException
        Pings 1C:Eneteprise runtime to get current events. 1C:Enterprise runtime debug client must periodically perform this request to inform 1C:Eneteprise runtime, that debug client is still alive.

        Also client will receive list of actual debug process events.

        Returns:
        a list of events, never null
        Throws:
        RuntimeDebugClientException - if the request fails

      • getRuntimeDebugTargets

        List<DebugTargetId> getRuntimeDebugTargets​(String debugAreaName)
                                    throws RuntimeDebugClientException
        Gets 1C:Enterprise runtime debug targets for the provided debug area name. Current client 1C:Enterprise untime debug area name must be provided if there was selected one in current debug process or can be null if wasn't.
        Parameters:
        debugAreaName - the 1C:Enterprise runtime debug area name, can be null if none
        a - list of 1C:Enterprise runtime debug targets for current debug area, never null
        Throws:
        RuntimeDebugClientException - if the request fails

      • getRuntimeTargetStackFrames

        List<StackItemViewInfoData> getRuntimeTargetStackFrames​(DebugTargetId debugTarget)
                                                 throws RuntimeDebugClientException
        Gets a list of stack frames items by the provided 1C:Enterprise runtime debug target.
        Parameters:
        debugTarget - the 1C:Enterprise debug target, cannot be null
        Returns:
        a list of stack frames, direction of list elements is from lower level to higher, never null
        Throws:
        RuntimeDebugClientException - if the request fails

      • evaluateExpression

        CalculationResultBaseData evaluateExpression​(DebugTargetId debugTarget,
                                             int waitTime,
                                             RuntimeEvaluationRequest request)
                                      throws RuntimeDebugClientException
        Evaluate the given expression in the 1C:Enterprise runtime debug server. Can return no actual results, then actual result will be returned and dispatched with ping() response event.
        Parameters:
        debugTarget - 1C:Enterprise runtime debug target to perform evaluation for, cannot be null
        waitTime - max response waiting time
        requests - the evaluation request to evaluate, cannot be null
        Returns:
        the evaluation result, or null, then actual result will be returned with ping() response
        Throws:
        RuntimeDebugClientException - if the request fails

      • evaluateExpressions

        Collection<CalculationResultBaseData> evaluateExpressions​(DebugTargetId debugTarget,
                                                          int waitTime,
                                                          Collection<RuntimeEvaluationRequest> requests)
                                                   throws RuntimeDebugClientException
        Evaluates the provided evaluation requests in 1C:Enterprise runtime. Can return no actual results, then actual result will be returned and dispatched with ping() response event.
        Parameters:
        debugTarget - 1C:Enterprise runtime debug target to perform evaluation for, cannot be null
        waitTime - the max response waiting time
        requests - a collection of requests to evaluate, cannot be null
        Returns:
        the evaluation result, or null, then actual result will be returned with ping() response
        Throws:
        RuntimeDebugClientException - if the request fails

      • evaluateVariables

        CalculationResultBaseData evaluateVariables​(DebugTargetId debugTarget,
                                            int stackLevel,
                                            int maxSize,
                                            boolean isMultiLine,
                                            int waitTime,
                                            UUID expressionUuid,
                                            UUID evaluationUuid)
                                     throws RuntimeDebugClientException
        Evaluates the stack frame variables in 1C:Enterprise runtime. Returns only local stack frame variables.
        Parameters:
        debugTarget - 1C:Enterprise runtime debug target, to perform evaluation for, cannot be null
        stackLevel - stack frames level of evaluation
        maxSize - max size of response value string representation
        isMultiLine - whether text result may contain multiple lines. If false then miltiple line text will be cut at first line break
        waitTime - max response waiting time
        expressionUuid - variables-container UUID, cannot be null
        evaluationUuid - result of evaluation UUID, this UUID is needed for event checking, cannot be null
        Returns:
        evaluation result never null
        Throws:
        RuntimeDebugClientException - if the request fails

      • modifyExpression

        RDBGModifyValueResponse modifyExpression​(BslValuePath expressionPath,
                                         String expression,
                                         DebugTargetId runtimeDebugTarget,
                                         int stackLevel,
                                         int maxSize,
                                         boolean isMultiLine,
                                         int waitTime,
                                         UUID expressionUuid,
                                         UUID evaluationUuid)
                                  throws RuntimeDebugClientException
        Modifies expression on stack frame in 1C:Enterprise runtime. Returns new evaluated value. Method will modify target path expression to given expression resulting value.
        Parameters:
        expressionPath - path of expression, instance of BslValuePath, cannot be null
        expression - an expression to generate a new value, cannot be null
        runtimeDebugTarget - 1C:Enterprise runtime debug target, to perform evaluation for, cannot be null
        stackLevel - stack frames level of evaluation
        maxSize - max size of response value string representation
        isMultiLine - whether text result may contain multiple lines. If false then miltiple line text will be cut at first line break
        waitTime - max response waiting time
        expressionUuid - variables-container UUID, cannot be null
        evaluationUuid - result of evaluation UUID, this UUID is needed for event checking, cannot be null
        Returns:
        evaluation result, can be null if request timed out
        Throws:
        RuntimeDebugClientException - if the request fails

      • modifyExpressionTyped

        <T> RDBGModifyValueResponse modifyExpressionTyped​(BslValuePath expressionPath,
                                                  T value,
                                                  DebugTargetId runtimeDebugTarget,
                                                  int stackLevel,
                                                  int maxSize,
                                                  boolean isMultiLine,
                                                  int waitTime,
                                                  UUID expressionUuid,
                                                  UUID evaluationUuid)
                                           throws RuntimeDebugClientException
        Modifies expression on stack frame in 1C:Enterprise runtime. Returns new evaluated value. Method can modify type and value of given expression.
        Parameters:
        expressionPath - path of expression, instance of BslValuePath, cannot be null
        typedModification - typed modification of expression, cannot be null
        runtimeDebugTarget - 1C:Enterprise runtime debug target, to perform evaluation for, cannot be null
        stackLevel - stack frames level of evaluation
        maxSize - max size of response value string representation
        isMultiLine - whether text result may contain multiple lines. If false then miltiple line text will be cut at first line break
        waitTime - max response waiting time
        expressionUuid - variables-container UUID, cannot be null
        evaluationUuid - result of evaluation UUID, this UUID is needed for event checking, cannot be null
        Returns:
        evaluation result, can be null if request timed out
        Throws:
        RuntimeDebugClientException - if the request fails

      • setAutoconnectDebugTargets

        void setAutoconnectDebugTargets​(List<String> debugAreaNames,
                                List<DebugTargetType> debugTargets)
                         throws RuntimeDebugClientException
        Sets 1C:Enterprise runtime debug targets for auto-connection with debug client.

        Client 1C:Enterprise runtime debug area names must be provided if there was selected one (or several) in current debug process or can be null if wasn't.

        Parameters:
        debugAreaNames - list of 1C:Enterprise runtime debug area names, can be null if none
        debugTargets - list of 1C:Enterprise runtime debug targets for auto-connection, cannot be null
        Throws:
        RuntimeDebugClientException - if the request fails

      • toggleProfiling

        void toggleProfiling​(UUID uuid)
              throws RuntimeDebugClientException
        Turns profiling mode of debug server on if it's off or turns it off if it's on.
        Parameters:
        uuid - the UUID of profiling session to turn profiling mode on or IDebugConstants.NULL_UUID to turn off
        Throws:
        RuntimeDebugClientException - if the request fails

      • notifyInfobaseUpdateStart

        boolean notifyInfobaseUpdateStart()
                           throws RuntimeDebugClientException
        Notifies the 1C:Enterprise debug server and all connected 1C:Enterprise runtime debug targets about infobase update start. Retuns whether all debug targets are successfully notified.
        Returns:
        whether all debug targets are successfully notified
        Throws:
        RuntimeDebugClientException - if the request fails

      • notifyInfobaseUpdateFinish

        boolean notifyInfobaseUpdateFinish()
                            throws RuntimeDebugClientException
        Notifies the 1C:Enterprise debug server and all connected 1C:Enterprise runtime debug targets about infobase update stop. Retuns whether all debug targets are successfully notified.
        Returns:
        whether all debug targets are successfully notified
        Throws:
        RuntimeDebugClientException - if the request fails

      • restartRuntimeDebugTarget

        void restartRuntimeDebugTarget​(Collection<DebugTargetId> debugTargets)
                        throws RuntimeDebugClientException
        Restarts a collection of provided 1C:Enterprise runtime debug targets. Not all types of 1C:Enterprise runtime debug targets may be restarted.
        Parameters:
        debugTargets - a collection of 1C:Enterprise runtime debug targets, cannot be null
        Throws:
        RuntimeDebugClientException - if the request fails