pyspresso.debug_interface

class pyspresso.debug_interface.Class
generic_signature = ''

The generic signature of the loaded reference type or an empty string if there is none.

ref_type_tag = ''

Kind of reference type; one of any TypeTag values.

signature = ''

The JNI signature of the loaded reference type.

status = 0

The current class status; one of any ClassStatus values.

type_id = 0

Matching loaded reference type.

class pyspresso.debug_interface.DebugInterface(transport=None, server=False, address=None)

The DebugInterface class provides a debug interface on top of DebugTransport.

The DebugInterface constructor initializes member variables and creates a DebugTransport object accessible as the transport member variable. It also creates the xdebug_arg member variable to be used when running the Java target with the "-Xdebug" command line argument.

The transport value should be "memory" for a shared-memory-based transport or "socket" for a socket-based transport.

If the server value is True then the debugger acts as the server and the debuggee acts as the client. Otherwise, the debuggee acts as the server and the debugger acts as the client.

The address value should be in the format "hostname:port" for socket-based transport, or should be the shared file mapping name for shared-memory-based transport.

class StructSizes

JDWP object sizes.

See details at http://docs.oracle.com/javase/8/docs/technotes/guides/jpda/jdwp-spec.html

field_id = ''

Size of a JDWP fieldID value in the form of a struct format character ("B", "I", "Q", etc.).

frame_id = ''

Size of a JDWP frameID value in the form of a struct format character ("B", "I", "Q", etc.).

method_id = ''

Size of a JDWP methodID value in the form of a struct format character ("B", "I", "Q", etc.).

object_id = ''

Size of a JDWP objectID value in the form of a struct format character ("B", "I", "Q", etc.).

reference_type_id = ''

Size of a JDWP referenceTypeID value in the form of a struct format character ("B", "I", "Q", etc.).

class DebugInterface.Utilities(di)

Utility functions.

attach()

Attach to the Java process launced with this DebugInterface object’s xdebug_arg command line switch.

get_method(reference_type_id=0, method_id=0)

Returns a Method object from a given numeric reference_type_id and a given numeric method_id.

get_method_arguments(thread_id, parameters, mod_bits)

Get the list of method arguments in a given thread’s stack frame.

get_string_representation_of_value(value=None)

Get a string representation of value, a Value value.

parse_events(data)

Extract all events from an event CommandPacket object’s data buffer.

Returns a tuple. The first value in the tuple is a list of pyspresso.events.Event objects; the second value in the tuple is the composite event’s SuspendPolicy.

parse_jni(jni)

Parse a JNI type signature string, such as "(ILjava/lang/String;[I)J". For details, see https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html#type_signatures

Returns a two-value tuple. The first value is a list of method Parameter objects; the second value is a single Parameter representing the method’s return type.

wait_for_event()

Wait for the next debug event from the debuggee and return the event’s CommandPacket.

DebugInterface.connected = False

Boolean that specifies whether or not this DebugInterface is connected to the target JVM.

DebugInterface.event_classes = {}

Mapping of EventKind to pyspresso.events.Event class.

DebugInterface.jni_tags = {}

Mapping of JNI tags to names and sizes.

DebugInterface.transport = None

A DebugTransport object, initialized by the DebugInterface constructor.

DebugInterface.utils = <pyspresso.debug_interface.Utilities instance>

Utility functions. Updated by the DebugInterface constructor with the actual DebugInterface object.

DebugInterface.xdebug_arg = ''

Command line switch to be used when running the Java target with the "-Xdebug" command line argument.

class pyspresso.debug_interface.Field
field_id = 0

Field ID.

generic_signature = ''

The generic signature of the field, or an empty string if there is none.

mod_bits = 0

The modifier bit flags (also known as access flags) which provide additional information on the field declaration. Individual flag values are defined in Chapter 4 of The Java Virtual Machine Specification. In addition, The 0xf0000000 bit identifies the field as synthetic, if the synthetic attribute capability (capabilities) is available.

name = ''

Name of field.

signature = ''

JNI Signature of field.

class pyspresso.debug_interface.JdwpCommand

This class contains Python-wrappers for JDWP commands.

Most of the docstrings in the subclasses are copied from http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html

class ArrayReference(di)
get_length(array_object_id=0)

Returns the number of components in a given array.

get_values(array_object_id=0, first_index=0, length=0)

Returns a range of array components. The specified range must be within the bounds of the array.

set_values(array_object_id=0, first_index=0, values=[])

Sets a range of array components. The specified range must be within the bounds of the array. For primitive values, each value’s type must match the array component type exactly. For object values, there must be a widening reference conversion from the value’s type to the array component type and the array component type must be loaded.

class JdwpCommand.ArrayType(di)
create_new_instance(array_type=0, length=0)

Creates a new array object of this type with a given length.

class JdwpCommand.ClassLoaderReference(di)
get_visible_classes(class_loader_id=0)

Returns a list of all classes which this class loader has been requested to load. This class loader is considered to be an initiating class loader for each class in the returned list. The list contains each reference type defined by this loader and any types for which loading was delegated by this class loader to another class loader.

The visible class list has useful properties with respect to the type namespace. A particular type name will occur at most once in the list. Each field or variable declared with that type name in a class defined by this class loader must be resolved to that single type.

No ordering of the returned list is guaranteed.

class JdwpCommand.ClassObjectReference(di)
get_reflected_type(class_object_id=0)

Returns the reference type reflected by this class object.

class JdwpCommand.ClassType(di)
create_new_instance(class_=0, thread=0, method_id=0, arguments=[], options=0)

Creates a new object of this type, invoking the specified constructor.

For more information, see http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_ClassType_NewInstance

Returns a 2-tuple: (new_object, exception), where new_object is a TaggedObjectId and exception is a TaggedObjectId.

get_superclass(class_=0)

Returns the immediate superclass of a class.

invoke_method(class_=0, thread=0, method_id=0, arguments=[], options=0)

Invokes a static method.

For more information, see http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_ClassType_InvokeMethod

Returns a 2-tuple: (return_value, exception), where value is a Value and exception is a TaggedObjectId.

set_values(class_=0, values=[])

Sets the value of one or more static fields. Each field must be a member of the class type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, the values of private fields can be set. Final fields cannot be set. For primitive values, the value’s type must match the field’s type exactly. For object values, there must exist a widening reference conversion from the value’s type to the field’s type and the field’s type must be loaded.

The values list should be a list of objects, where each object has attributes field_id (the field to set) and value (the value to put in the field).

class JdwpCommand.EventRequest(di)
clear(event_kind=0, request_id=0)

Clear an event request. See JDWP.EventKind (http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_EventKind) for a complete list of events that can be cleared. Only the event request matching the specified event kind and requestID is cleared. If there isn’t a matching event request the command is a no-op and does not result in an error. Automatically generated events do not have a corresponding event request and may not be cleared using this command.

clear_all_breakpoints()

Removes all set breakpoints, a no-op if there are no breakpoints set.

set(event_kind=0, suspend_policy=2, modifiers=[])

Set an event request. When the event described by this request occurs, an event (http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_Event) is sent from the target VM. If an event occurs that has not been requested then it is not sent from the target VM. The two exceptions to this are the VM Start Event and the VM Death Event which are automatically generated events - see Composite Command (http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_Event_Composite) for further details.

The event_kind value should be a defined EventKind value.

The suspend_policy value should be a defined SuspendPolicy value.

The modifiers value should be a list of event modifier objects, whose classes are in event_modifiers.py.

The return value is a 32-bit signed request ID.

class JdwpCommand.InterfaceType(di)
invoke_method(class_=0, thread=0, method_id=0, arguments=[], options=0)

Invokes a static method.

For more information, see http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_InterfaceType_InvokeMethod

Returns a 2-tuple: (return_value, exception), where value is a Value and exception is a TaggedObjectId.

class JdwpCommand.Method(di)
class VariableTable
class Slot
code_index = 0

First code index at which the variable is visible (unsigned). Used in conjunction with length. The variable can be get or set only when the current codeIndex <= current frame code index < codeIndex + length.

generic_signature = ''

The variable type’s generic signature or an empty string if there is none.

length = 0

Unsigned value used in conjunction with codeIndex. The variable can be get or set only when the current codeIndex <= current frame code index < code index + length.

name = ''

The variable’s name.

signature = ''

The variable type’s JNI signature.

slot = 0

The local variable’s index in its frame.

JdwpCommand.Method.VariableTable.arg_cnt = 0

The number of words in the frame used by arguments. Eight-byte arguments use two words; all others use one.

JdwpCommand.Method.VariableTable.slots = []

List of Slot values.

JdwpCommand.Method.get_bytecodes(ref_type=0, method_id=0)

Retrieve the method’s bytecodes as defined in The Java Virtual Machine Specification. Requires can_get_bytecodes capability - see capabilities_new.

JdwpCommand.Method.get_line_table(ref_type=0, method_id=0)

Returns line number information for the method, if present. The line table maps source line numbers to the initial code index of the line. The line table is ordered by code index (from lowest to highest). The line number information is constant unless a new class definition is installed using redefine_classes.

JdwpCommand.Method.get_variable_table(ref_type=0, method_id=0)

Returns variable information for the method. The variable table includes arguments and locals declared within the method. For instance methods, the “this” reference is included in the table. Also, synthetic variables may be present.

JdwpCommand.Method.get_variable_table_with_generic(ref_type=0, method_id=0)

Returns variable information for the method, including generic signatures for the variables. The variable table includes arguments and locals declared within the method. For instance methods, the “this” reference is included in the table. Also, synthetic variables may be present. Generic signatures are described in the signature attribute section in The Java Virtual Machine Specification. Since JDWP version 1.5.

JdwpCommand.Method.is_obsolete(ref_type=0, method_id=0)

Determine if this method is obsolete. A method is obsolete if it has been replaced by a non-equivalent method using the redefine_classes command. The original and redefined methods are considered equivalent if their bytecodes are the same except for indices into the constant pool and the referenced constants are equal.

class JdwpCommand.ObjectReference(di)
disable_collection(object_id=0)

Prevents garbage collection for the given object. By default all objects in back-end replies may be collected at any time the target VM is running. A call to this command guarantees that the object will not be collected. The enable_collection command can be used to allow collection once again.

Note that while the target VM is suspended, no garbage collection will occur because all threads are suspended. The typical examination of variables, fields, and arrays during the suspension is safe without explicitly disabling garbage collection.

This method should be used sparingly, as it alters the pattern of garbage collection in the target VM and, consequently, may result in application behavior under the debugger that differs from its non-debugged behavior.

enable_collection(object_id=0)

Permits garbage collection for this object. By default all objects returned by JDWP may become unreachable in the target VM, and hence may be garbage collected. A call to this command is necessary only if garbage collection was previously disabled with the disable_collection command.

get_monitor_info(object_id=0)

Returns monitor information for an object. All threads in the VM must be suspended. Requires can_get_monitor_info capability - see capabilities_new.

get_reference_type(object_id=0)

Returns the runtime type of the object. The runtime type will be a class or an array.

get_referring_objects(object_id=0, max_referrers=0)

Returns objects that directly reference this object. Only objects that are reachable for the purposes of garbage collection are returned. Note that an object can also be referenced in other ways, such as from a local variable in a stack frame, or from a JNI global reference. Such non-object referrers are not returned by this command.

Since JDWP version 1.6. Requires can_get_instance_info capability - see capabilities_new.

get_values(object_id=0, fields=[])

Returns the value of one or more instance fields. Each field must be member of the object’s type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, the values of private fields can be obtained.

invoke_method(object_id=0, thread=0, class_=0, method_id=0, arguments=[], options=0)

Invokes a static method.

For more information, see http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_ObjectReference_InvokeMethod

Returns a 2-tuple: (return_value, exception), where value is a Value and exception is a TaggedObjectId.

is_collected(object_id=0)

Determines whether an object has been garbage collected in the target VM.

set_values(object_id=0, values=[])

Sets the value of one or more instance fields. Each field must be member of the object’s type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, the values of private fields can be set. For primitive values, the value’s type must match the field’s type exactly. For object values, there must be a widening reference conversion from the value’s type to thefield’s type and the field’s type must be loaded.

The values list should be a list of objects, where each object has attributes field_id (the field to set) and value (the value to put in the field).

class JdwpCommand.ReferenceType(di)
get_class_file_version(ref_type=0)

Returns the class file major and minor version numbers, as defined in the class file format of the Java Virtual Machine specification.

Since JDWP version 1.6.

Returns a 2-tuple: (major_version, minor_version)

get_class_loader(ref_type=0)

Returns the instance of java.lang.ClassLoader which loaded a given reference type. If the reference type was loaded by the system class loader, the returned object ID is null.

get_class_object(ref_type=0)

Returns the class object corresponding to this type.

get_constant_pool(ref_type=0)

Return the raw bytes of the constant pool in the format of the constant_pool item of the Class File Format in The Java Virtual Machine Specification.

Since JDWP version 1.6. Requires can_get_constant_pool capability - see capabilities_new.

Returns the 2-tuple (count, cpbytes), where count is the total number of constant pool entries plus one (this corresponds to the constant_pool_count item of the Class File Format in The Java Virtual Machine Specification) and cpbytes contains the raw bytes of the constant pool.

get_fields(ref_type=0)

Returns information for each field in a reference type. Inherited fields are not included. The field list will include any synthetic fields created by the compiler. Fields are returned in the order they occur in the class file.

get_fields_with_generic(ref_type=0)

Returns information, including the generic signature if any, for each field in a reference type. Inherited fields are not included. The field list will include any synthetic fields created by the compiler. Fields are returned in the order they occur in the class file. Generic signatures are described in the signature attribute section in The Java Virtual Machine Specification. Since JDWP version 1.5.

get_instances(ref_type=0, max_instances=0)

Returns instances of this reference type. Only instances that are reachable for the purposes of garbage collection are returned.

Since JDWP version 1.6. Requires can_get_instance_info capability - see capabilities_new.

get_interfaces(ref_type=0)

Returns the interfaces declared as implemented by this class. Interfaces indirectly implemented (extended by the implemented interface or implemented by a superclass) are not included.

get_methods(ref_type=0)

Returns information for each method in a reference type. Inherited methods are not included. The list of methods will include constructors (identified with the name “<init>”), the initialization method (identified with the name “<clinit>”) if present, and any synthetic methods created by the compiler. Methods are returned in the order they occur in the class file.

get_methods_with_generic(ref_type=0)

Returns information, including the generic signature if any, for each method in a reference type. Inherited methodss are not included. The list of methods will include constructors (identified with the name “<init>”), the initialization method (identified with the name “<clinit>”) if present, and any synthetic methods created by the compiler. Methods are returned in the order they occur in the class file. Generic signatures are described in the signature attribute section in The Java Virtual Machine Specification. Since JDWP version 1.5.

get_modifiers(ref_type)

Returns the modifiers (also known as access flags) for a reference type. The returned bit mask contains information on the declaration of the reference type. If the reference type is an array or a primitive class (for example, java.lang.Integer.TYPE), the value of the returned bit mask is undefined.

get_nested_types(ref_type=0)

Returns the classes and interfaces directly nested within this type. Types further nested within those types are not included.

get_signature(ref_type=0)

Returns the JNI signature of a reference type. JNI signature formats are described in the Java Native Inteface Specification (http://java.sun.com/products/jdk/1.2/docs/guide/jni/index.html).

For primitive classes the returned signature is the signature of the corresponding primitive type; for example, “I” is returned as the signature of the class represented by java.lang.Integer.TYPE.

get_signature_with_generic(ref_type=0)

Returns the JNI signature of a reference type along with the generic signature if there is one. Generic signatures are described in the signature attribute section in The Java Virtual Machine Specification. Since JDWP version 1.5.

Returns a 2-tuple: (signature, generic_signature)

get_source_debug_extension(ref_type=0)

Returns the value of the SourceDebugExtension attribute. Since JDWP version 1.4. Requires can_get_source_debug_extension capability - see capabilities_new.

get_source_file(ref_type=0)

Returns the name of source file in which a reference type was declared.

get_status(ref_type=0)

Returns the current status of the reference type. The status indicates the extent to which the reference type has been initialized, as described in section 2.1.6 of The Java Virtual Machine Specification. If the class is linked the PREPARED and VERIFIED bits in the returned status bits will be set. If the class is initialized the INITIALIZED bit in the returned status bits will be set. If an error occured during initialization then the ERROR bit in the returned status bits will be set. The returned status bits are undefined for array types and for primitive classes (such as java.lang.Integer.TYPE).

get_values(ref_type=0, fields=[])

Returns the value of one or more static fields of the reference type. Each field must be member of the reference type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, the values of private fields can be obtained.

class JdwpCommand.StackFrame(di)
get_this_object(thread_id=0, frame_id=0)

Returns the value of the ‘this’ reference for this frame. If the frame’s method is static or native, the reply will contain the null object reference.

The returned value is a TaggedObjectId.

get_values(thread_id=0, frame_id=0, slots=[])

Returns the value of one or more local variables in a given frame. Each variable must be visible at the frame’s code index. Even if local variable information is not available, values can be retrieved if the front-end is able to determine the correct local variable index. (Typically, this index can be determined for method arguments from the method signature without access to the local variable table information.)

pop_frames(thread_id=0, frame_id=0)

Pop the top-most stack frames of the thread stack, up to, and including ‘frame’. The thread must be suspended to perform this command. The top-most stack frames are discarded and the stack frame previous to ‘frame’ becomes the current frame. The operand stack is restored – the argument values are added back and if the invoke was not invokestatic, objectref is added back as well. The Java virtual machine program counter is restored to the opcode of the invoke instruction.

Since JDWP version 1.4. Requires can_pop_frames capability - see capabilities_new.

set_values(thread_id=0, frame_id=0, slot_values=[])

Sets the value of one or more local variables. Each variable must be visible at the current frame code index. For primitive values, the value’s type must match the variable’s type exactly. For object values, there must be a widening reference conversion from the value’s type to thevariable’s type and the variable’s type must be loaded.

Even if local variable information is not available, values can be set, if the front-end is able to determine the correct local variable index. (Typically, thisindex can be determined for method arguments from the method signature without access to the local variable table information.)

class JdwpCommand.StringReference(di)
get_value(string_object_id=0)

Returns the characters contained in the string.

class JdwpCommand.ThreadGroupReference(di)
get_children(thread_group_id=0)

Returns the live threads and active thread groups directly contained in this thread group. Threads and thread groups in child thread groups are not included. A thread is alive if it has been started and has not yet been stopped. See java.lang.ThreadGroup (http://docs.oracle.com/javase/8/docs/api/java/lang/ThreadGroup.html) for information about active ThreadGroups.

Returns a 2-tuple: (child_threads, child_groups), where child_threads is a list of direct child thread IDs, and child_groups is a list of direct child thread group IDs.

get_name(thread_group_id=0)

Returns the thread group name.

get_parent(thread_group_id=0)

Returns the thread group, if any, which contains a given thread group.

class JdwpCommand.ThreadReference(di)
force_early_return(thread_id=0, value=None)

Force a method to return before it reaches a return statement.

For more information, see http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_ThreadReference_ForceEarlyReturn

get_current_contended_monitor(thread_id=0)

Returns the object, if any, for which this thread is waiting. The thread may be waiting to enter a monitor, or it may be waiting, via the java.lang.Object.wait method, for another thread to invoke the notify method. The thread must be suspended, and the returned information is relevant only while the thread is suspended. Requires can_get_current_contended_monitor capability - see capabilities_new.

get_frame_count(thread_id=0)

Returns the count of frames on this thread’s stack. The thread must be suspended, and the returned count is valid only while the thread is suspended. Returns JDWP.Error.errorThreadNotSuspended if not suspended.

get_frames(thread_id=0, start_frame=0, length=0)

Returns the current call stack of a suspended thread. The sequence of frames starts with the currently executing frame, followed by its caller, and so on. The thread must be suspended, and the returned frameID is valid only while the thread is suspended.

get_name(thread_id=0)

Returns the thread name.

get_owned_monitors(thread_id=0)

Returns the objects whose monitors have been entered by this thread. The thread must be suspended, and the returned information is relevant only while the thread is suspended. Requires can_get_owned_monitor_info capability - see capabilities_new.

get_owned_monitors_stack_depth_info(thread_id=0)

Returns monitor objects owned by the thread, along with stack depth at which the monitor was acquired. Returns stack depth of -1 if the implementation cannot determine the stack depth (e.g., for monitors acquired by JNI MonitorEnter).The thread must be suspended, and the returned information is relevant only while the thread is suspended. Requires can_get_monitor_frame_info capability - see capabilities_new.

Since JDWP version 1.6.

get_status(thread_id=0)

Returns the current status of a thread. The thread status reply indicates the thread status the last time it was running. The suspend status provides information on the thread’s suspension, if any.

Returns a 2-tuple: (thread_status, suspend_status), where thread_status is of type ThreadStatus and suspend_status is of type SuspendStatus.

get_suspend_count(thread_id=0)

Get the suspend count for this thread. The suspend count is the number of times the thread has been suspended through the thread-level or VM-level suspend commands without a corresponding resume.

get_thread_group(thread_id=0)

Returns the thread group that contains a given thread.

interrupt(thread_id=0)

Interrupt the thread, as if done by java.lang.Thread.interrupt.

resume(thread_id=0)

Resumes the execution of a given thread. If this thread was not previously suspended by the front-end, calling this command has no effect. Otherwise, the count of pending suspends on this thread is decremented. If it is decremented to 0, the thread will continue to execute.

stop(thread_id=0, throwable=0)

Stops the thread with an asynchronous exception, as if done by java.lang.Thread.stop.

suspend(thread_id=0)

Suspends the thread.

Unlike java.lang.Thread.suspend(), suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed the same number of times it has been suspended.

Suspending single threads with command has the same dangers java.lang.Thread.suspend(). If the suspended thread holds a monitor needed by another running thread, deadlock is possible in the target VM (at least until the suspended thread is resumed again).

The suspended thread is guaranteed to remain suspended until resumed through one of the JDI resume methods mentioned above; the application in the target VM cannot resume the suspended thread through {@link java.lang.Thread#resume}.

Note that this doesn’t change the status of the thread (see the get_status command.) For example, if it was Running, it will still appear running to other threads.

class JdwpCommand.VirtualMachine(di)
all_classes

Returns reference types for all classes currently loaded by the target VM.

all_classes_with_generic

Returns reference types for all classes currently loaded by the target VM. Both the JNI signature and the generic signature are returned for each class. Generic signatures are described in the signature attribute section in The Java Virtual Machine Specification. Since JDWP version 1.5.

all_threads

Returns all threads currently running in the target VM. The returned list contains threads created through java.lang.Thread, all native threads attached to the target VM through JNI, and system threads created by the target VM. Threads that have not yet been started and threads that have completed their execution are not included in the returned list.

capabilities

Retrieve this VM’s capabilities. The capabilities are returned as booleans, each indicating the presence or absence of a capability. The commands associated with each capability will return the NOT_IMPLEMENTED error if the cabability is not available.

capabilities_new

Retrieve all of this VM’s capabilities. The capabilities are returned as booleans, each indicating the presence or absence of a capability. The commands associated with each capability will return the NOT_IMPLEMENTED error if the cabability is not available. Since JDWP version 1.4.

class_paths

Retrieve the classpath and bootclasspath of the target VM. If the classpath is not defined, returns an empty list. If the bootclasspath is not defined returns an empty list.

Returns a 3-tuple of (base_directory, class_paths, boot_class_paths).

create_string(string='')

Creates a new UTF-8 string object in the target VM and returns its id.

default_stratum

Set the default stratum. Requires can_set_default_stratum capability - see capabilities_new.

Note that this is a write-only attribute.

dispose()

Invalidates this virtual machine mirror. The communication channel to the target VM is closed, and the target VM prepares to accept another subsequent connection from this debugger or another debugger.

dispose_objects(objects=[])

Releases a list of object IDs. For each object in the list, the following applies. The count of references held by the back-end (the reference count) will be decremented by refCnt. If thereafter the reference count is less than or equal to zero, the ID is freed. Any back-end resources associated with the freed ID may be freed, and if garbage collection was disabled for the object, it will be re-enabled. The sender of this command promises that no further commands will be sent referencing a freed ID.

Use of this command is not required. If it is not sent, resources associated with each ID will be freed by the back-end at some time after the corresponding object is garbage collected. It is most useful to use this command to reduce the load on the back-end if a very large number of objects has been retrieved from the back-end (a large array, for example) but may not be garbage collected any time soon.

IDs may be re-used by the back-end after they have been freed with this command.This description assumes reference counting, a back-end may use any implementation which operates equivalently.

exit(exit_code=0)

Terminates the target VM with the given exit_code. On some platforms, the exit code might be truncated, for example, to the low order 8 bits. All ids previously returned from the target VM become invalid. Threads running in the VM are abruptly terminated. A thread death exception is not thrown and finally blocks are not run.

get_classes_by_signature(signature='')

Returns reference types for all the classes loaded by the target VM which match the given signature. Multple reference types will be returned if two or more class loaders have loaded a class of the same name. The search is confined to loaded classes only; no attempt is made to load a class of the given signature.

The signature value is the JNI signature of the class to find (for example, "Ljava/lang/String;").

get_instance_counts(reference_types=[])

Returns the number of instances of each reference type in the input list. Only instances that are reachable for the purposes of garbage collection are counted. If a reference type is invalid, eg. it has been unloaded, zero is returned for its instance count.

Since JDWP version 1.6. Requires can_get_instance_info capability - see capabilities_new.

hold_events()

Tells the target VM to stop sending events. Events are not discarded; they are held until a subsequent ReleaseEvents command is sent. This command is useful to control the number of events sent to the debugger VM in situations where very large numbers of events are generated. While events are held by the debugger back-end, application execution may be frozen by the debugger back-end to prevent buffer overflows on the back end. Responses to commands are never held and are not affected by this command. If events are already being held, this command is ignored.

id_sizes

Returns the sizes of variably-sized data types in the target VM.The returned values indicate the number of bytes used by the identifiers in command and reply packets.

redefine_classes(classes=[])

Installs new class definitions. If there are active stack frames in methods of the redefined classes in the target VM then those active frames continue to run the bytecodes of the original method. These methods are considered obsolete - see is_obsolete. The methods in the redefined classes will be used for new invokes in the target VM. The original method ID refers to the redefined method. All breakpoints in the redefined classes are cleared. If resetting of stack frames is desired, the pop_frames command can be used to pop frames with obsolete methods.

Requires can_redefine_classes capability - see capabilities_new. In addition to the canRedefineClasses capability, the target VM must have the canAddMethod capability to add methods when redefining classes, or the canUnrestrictedlyRedefineClasses to redefine classes in arbitrary ways.

release_events()

Tells the target VM to continue sending events. This command is used to restore normal activity after a HoldEvents command. If there is no current HoldEvents command in effect, this command is ignored.

resume()

Resumes execution of the application after the suspend command or an event has stopped it. Suspensions of the Virtual Machine and individual threads are counted. If a particular thread is suspended n times, it must resumed n times before it will continue.

suspend()

Suspends the execution of the application running in the target VM. All Java threads currently running will be suspended.

Unlike java.lang.Thread.suspend, suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed through the VM-level resume (http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_VirtualMachine_Resume) command or the thread-level resume (http://docs.oracle.com/javase/8/docs/platform/jpda/jdwp/jdwp-protocol.html#JDWP_ThreadReference_Resume) command the same number of times it has been suspended.

top_level_thread_groups

Returns all thread groups that do not have a parent. This command may be used as the first step in building a tree (or trees) of the existing thread groups.

version

The JDWP version implemented by the target VM. The version string format is implementation dependent.

exception pyspresso.debug_interface.JdwpCommandError(*args, **kwargs)
class pyspresso.debug_interface.JniTag(tag, name, size)

https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/types.html

name = ''

Human-readable Java type string.

size = ''

The size of the type as a struct format character.

tag = ''

Single-character type signature representation.

class pyspresso.debug_interface.Location(di, type=0, class_id=0, method_id=0, index=0, location='')

An executable location as defined by JDWP. For details, see http://docs.oracle.com/javase/8/docs/technotes/guides/jpda/jdwp-spec.html

The Location constructor constructs a Location object from either a location byte string or from a type, class_id, method_id, and index.

The di value must be a reference to a DebugInterface object.

class_id = 0

A JDWP classID value.

index = 0

An index that identifies a location within the method.

location = ''

The raw interpretation of this location as a JDWP byte string.

method_id = 0

A JDWP methodID value.

type = 0

A TypeTag value.

class pyspresso.debug_interface.Method

The Method class defines a Java method.

generic_signature = ''

The generic signature of the method, or an empty string if there is none.

method_id = 0

Method ID.

mod_bits = 0

The modifier bit flags (also known as access flags) which provide additional information on the field declaration. Individual flag values are defined in Chapter 4 of The Java Virtual Machine Specification. In addition, The 0xf0000000 bit identifies the field as synthetic, if the synthetic attribute capability (capabilities) is available.

name = ''

Name of method.

signature = ''

JNI signature of method.

class pyspresso.debug_interface.Parameter(tag=None, name=None)

A method parameter.

name = None

A string that represents the name of the parameter, or None if no name can be determined.

tag = None

The parameter’s JniTag.

class pyspresso.debug_interface.ReferenceType
ref_type_tag = 0

TypeTag of following reference type.

type_id = 0

Reference type ID.

class pyspresso.debug_interface.TaggedObjectId
object_id = 0

Object ID.

tag = ''

Single-character type signature representation.

class pyspresso.debug_interface.Value(tag='', value=0)

A value retrieved from the target VM.

tag = ''

Single-character type signature representation.

value = 0

An object ID or a primitive value.