Javadoc fixes to o.e.jdi.hcr

Contributes to
eclipse-platform/eclipse.platform.releng.aggregator#1531

org.eclipse.jdt.debug/jdi/org/eclipse/jdi/hcr/ReferenceType.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2011 IBM Corporation and others.
+ * Copyright (c) 2000, 2023 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -18,45 +18,35 @@
  */
 public interface ReferenceType {
 	/**
-	 * An HCR-eligible class file may now be loaded and reloaded at some later
-	 * point(s). Methods on the stack may come from any of several versions of
-	 * the same HCR-eligible class. The debugger can query any class file
-	 * related object (class, method, or field) for information about the
-	 * version of the class file from which it came.
+	 * An HCR-eligible class file may now be loaded and reloaded at some later point(s). Methods on the stack may come from any of several versions of
+	 * the same HCR-eligible class. The debugger can query any class file related object (class, method, or field) for information about the version
+	 * of the class file from which it came.
 	 * <p>
-	 * Classes loaded by a cooperating class loader are flagged as HCR-eligible
-	 * for hot code replacement.
+	 * Classes loaded by a cooperating class loader are flagged as HCR-eligible for hot code replacement.
+	 * </p>
 	 * <p>
-	 * Class file versions are identified by the CRC-32 of the entire class file
-	 * contents.
-	 * <p>
-	 * The VM typically computes and remembers the CRC when it digests a class
-	 * file. Note this behavior is optional; VM need not retain any CRCs. A
+	 * Class file versions are identified by the CRC-32 of the entire class file contents.
+	 * </p>
+	 * The VM typically computes and remembers the CRC when it digests a class file. Note this behavior is optional; VM need not retain any CRCs. A
 	 * debugger can query any class for its class CRC and eligibility:
 	 * <ul>
 	 * <li>The query can be made at at time.
 	 * <li>This is not directed to any specific thread.
 	 * <li>Threads may be running at the time; they are not stopped.
 	 * <li>Other JDI-level operations may be in progress.
-	 * <li>If a debugger knows only about a method or a field, it must first
-	 * query its defining class first to find out what is the CRC for this
+	 * <li>If a debugger knows only about a method or a field, it must first query its defining class first to find out what is the CRC for this
 	 * method or field.
 	 * </ul>
-	 * All information returned does not change over the lifetime of the
-	 * reference type object (replacing the class results in a new reference
-	 * type object). This info can therefore be cached client-side with
-	 * impunity.
-	 * <p>
-	 * This simple mechanism allows the IDE to detect that an object does not
-	 * belong to the current class file base (debugger computes CRC of current
-	 * class file and queries VM and compares to its CRC). It also allows the
-	 * debugger to quickly detect whether two objects come from the same class
-	 * file (debugger queries VM and compares CRCs). By checking the
-	 * HCR-eligibility bit, the debugger can determine whether the class could
-	 * be hot replaced in principle.
+	 * All information returned does not change over the lifetime of the reference type object (replacing the class results in a new reference type
+	 * object). This info can therefore be cached client-side with impunity.
 	 * <p>
-	 * @return the CRC-32 of the entire class file contents for this reference
-	 * type.
+	 * This simple mechanism allows the IDE to detect that an object does not belong to the current class file base (debugger computes CRC of current
+	 * class file and queries VM and compares to its CRC). It also allows the debugger to quickly detect whether two objects come from the same class
+	 * file (debugger queries VM and compares CRCs). By checking the HCR-eligibility bit, the debugger can determine whether the class could be hot
+	 * replaced in principle.
+	 * </p>
+	 *
+	 * @return the CRC-32 of the entire class file contents for this reference type.
 	 *
 	 * @see org.eclipse.jdi.hcr.VirtualMachine#classesHaveChanged
 	 */

org.eclipse.jdt.debug/jdi/org/eclipse/jdi/hcr/ThreadReference.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2011 IBM Corporation and others.
+ * Copyright (c) 2000, 2023 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -20,69 +20,51 @@
  */
 public interface ThreadReference {
 	/**
-	 * Resumes the execution of this thread as if the next instruction was a
-	 * return instruction with the given value. This causes the top stack frame
+	 * Resumes the execution of this thread as if the next instruction was a return instruction with the given value. This causes the top stack frame
 	 * to be popped with the given value.
 	 * <p>
-	 * A breakpoint instruction at the current instruction is not triggered that
-	 * is, this operation takes precedence over breakpoints.
-	 * <code>try-finally</code> blocks enclosing the current location will be
-	 * triggered in due course.
-	 * <p>
-	 * The triggerFinallyAndSynchronizedBlocks option on this operation controls
-	 * whether <code>try-finally</code> and <code>synchronized</code> blocks
+	 * A breakpoint instruction at the current instruction is not triggered that is, this operation takes precedence over breakpoints.
+	 * <code>try-finally</code> blocks enclosing the current location will be triggered in due course.
+	 * </p>
+	 * The triggerFinallyAndSynchronizedBlocks option on this operation controls whether <code>try-finally</code> and <code>synchronized</code> blocks
 	 * enclosing the current location should be triggered:
 	 * <ul>
-	 * <li>If no, the stack frame is popped, the return value is returned, and
-	 * execution continues back in the caller. Note that <code>finally</code>
-	 * blocks are not run, and that if the code is nested within a
-	 * <code>synchronized</code> statement, the monitor lock is not released
-	 * (however, if the method is </code>synchronized</code> the monitor lock
-	 * will be properly released). This mechanism is sure-fire, but at the risk
-	 * of not letting the target program clean itself up (e.g., close its
-	 * files).
-	 * <li>If yes, the VM checks to see whether there might be a
-	 * <code>finally</code> or <code>synchronized</code> block enclosing the
-	 * current instruction.
+	 * <li>If no, the stack frame is popped, the return value is returned, and execution continues back in the caller. Note that <code>finally</code>
+	 * blocks are not run, and that if the code is nested within a <code>synchronized</code> statement, the monitor lock is not released (however, if
+	 * the method is <code>synchronized</code> the monitor lock will be properly released). This mechanism is sure-fire, but at the risk of not
+	 * letting the target program clean itself up (e.g., close its files).
+	 * <li>If yes, the VM checks to see whether there might be a <code>finally</code> or <code>synchronized</code> block enclosing the current
+	 * instruction.
 	 * <ul>
-	 * <li>If there is no enclosing <code>finally</code> block, the operation
-	 * reduces to the above case.
-	 * <li>If there is an enclosing <code>finally</code> block, the VM creates a
-	 * VM exception and activates the <code>finally</code> block with it. If
-	 * this exception eventually causes the stack frame to be popped, the
-	 * exception is caught by the VM itself, the return value is returned, and
+	 * <li>If there is no enclosing <code>finally</code> block, the operation reduces to the above case.
+	 * <li>If there is an enclosing <code>finally</code> block, the VM creates a VM exception and activates the <code>finally</code> block with it. If
+	 * this exception eventually causes the stack frame to be popped, the exception is caught by the VM itself, the return value is returned, and
 	 * execution continues back in the caller.
 	 * <ul>
 	 * </ul>
-	 * <p>
-	 * Note that a <code>finally</code> block manifests itself as (and is
-	 * indistinguishable from) a <code>catch Throwable</code> block.
-	 * <code>synchronized</code> statements also compile to a
-	 * <code>catch Throwable</code> block. The target program may inadventently
-	 * end up catching this exception.
+	 * <br/>
+	 * Note that a <code>finally</code> block manifests itself as (and is indistinguishable from) a <code>catch Throwable</code> block.
+	 * <code>synchronized</code> statements also compile to a <code>catch Throwable</code> block. The target program may inadventently end up catching
+	 * this exception.
 	 *
-	 * Since the choices each have their pros and cons, making the decision
-	 * is left to the debugger. However the later option is the  recommended choice.
-	 * <p>
-	 * The reply to the operation contains a flag indicating whether any <code>finally</code>
-	 * or <code>synchronized</code> blocks are enclosing the current
-	 * instruction.
-	 * <p>
-	 * This operation is ignored if the thread was not suspended. If the thread
-	 * was suspended multiple times, wait for the same number of resumes before
-	 * executing the return instruction.
-	 * <p>
-	 * The returned value is ignored if the method returns void.
-	 * <p>
-	 * Throws an <code>OperationRefusedException</code> if the VM refused to
-	 * perform this operation. This in recognition that the VM may be in an
+	 * Since the choices each have their pros and cons, making the decision is left to the debugger. However the later option is the recommended
+	 * choice. <br/>
+	 * The reply to the operation contains a flag indicating whether any <code>finally</code> or <code>synchronized</code> blocks are enclosing the
+	 * current instruction. <br/>
+	 * This operation is ignored if the thread was not suspended. If the thread was suspended multiple times, wait for the same number of resumes
+	 * before executing the return instruction. <br/>
+	 * The returned value is ignored if the method returns void. <br/>
+	 * Throws an <code>OperationRefusedException</code> if the VM refused to perform this operation. This in recognition that the VM may be in an
 	 * awkward state and unable to comply:
 	 * <ul>
 	 * <li>for example, execution is suspended in a native method,
 	 * <li>for example, execution is suspended during class preparation.
 	 * </ul>
-	 * @param returnValue the value to return from the thread with
-	 * @param triggerFinallyAndSynchronizedBlocks if finally / synchronization blocks should be executed before resuming
+	 *
+	 * @param returnValue
+	 *            the value to return from the thread with
+	 * @param triggerFinallyAndSynchronizedBlocks
+	 *            if finally / synchronization blocks should be executed before resuming
 	 * @return if the forced return was successful
 	 */
 	public boolean doReturn(Value returnValue,

org.eclipse.jdt.debug/jdi/org/eclipse/jdi/hcr/VirtualMachine.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2011 IBM Corporation and others.
+ * Copyright (c) 2000, 2023 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -60,44 +60,31 @@ public interface VirtualMachine {
 	public boolean canReloadClasses();
 
 	/**
-	 * Notifies the VM that the class file base that it is running from has
-	 * changed. Classes are given by their names.
-	 * <p>
-	 * The class file base is the collection of class files available on the
-	 * various VM's class paths consulted by the class loaders that are integral
-	 * to the system. In JDK 1.2, these would include all files on the boot
-	 * class path (used by the bootstrap class loader), the extension directory
-	 * (used by the extension class loader), and the regular class path (used by
-	 * the application class loader). The notion is important because only those
-	 * classes that the VM knows to be in the class file base will be eligible
-	 * for hot code replacement. Classes that are actually loaded by
-	 * non-standard class loaders cannot be replaced on the fly (because the VM
-	 * has no way of asking non-standard class loaders to reload them). Classes
-	 * loaded from the class file base by cooperating class loaders are said to
-	 * be HCR-eligible.
+	 * Notifies the VM that the class file base that it is running from has changed. Classes are given by their names.
 	 * <p>
+	 * The class file base is the collection of class files available on the various VM's class paths consulted by the class loaders that are integral
+	 * to the system. In JDK 1.2, these would include all files on the boot class path (used by the bootstrap class loader), the extension directory
+	 * (used by the extension class loader), and the regular class path (used by the application class loader). The notion is important because only
+	 * those classes that the VM knows to be in the class file base will be eligible for hot code replacement. Classes that are actually loaded by
+	 * non-standard class loaders cannot be replaced on the fly (because the VM has no way of asking non-standard class loaders to reload them).
+	 * Classes loaded from the class file base by cooperating class loaders are said to be HCR-eligible.
+	 * </p>
 	 * The VM is expected to:
 	 * <ol>
 	 * <li>Suspend all running threads.
-	 * <li>For a given JNI signature, try to find the definition of the
-	 * corresponding class.
+	 * <li>For a given JNI signature, try to find the definition of the corresponding class.
 	 * <ul>
-	 * <li>If the class definition can be found then it replaces the previous
-	 * definition for that class.
+	 * <li>If the class definition can be found then it replaces the previous definition for that class.
 	 * <li>If a definition for the class is not found, then it is unloaded.
 	 * <ul>
-	 * <li>This operation returns only when the classes have been reloaded
-	 * and/or deleted.
-	 * <li>If the suspend policy of the class unload event is not to suspend the
-	 * VM, then the VM resumes all the threads that it has suspended.
+	 * <li>This operation returns only when the classes have been reloaded and/or deleted.
+	 * <li>If the suspend policy of the class unload event is not to suspend the VM, then the VM resumes all the threads that it has suspended.
 	 * <li>Finally for each class that has been reloaded, the VM is expected to
 	 * <ul>
 	 * <li>send a class unload event,
-	 * <li>note the VM is already suspended if the suspend policy of class
-	 * unload event said so,
+	 * <li>note the VM is already suspended if the suspend policy of class unload event said so,
 	 * <li>when the frontend resumes the VM, send a class prepare event,
-	 * <li>suspend the VM according to the suspend policy of the class prepare
-	 * event request.
+	 * <li>suspend the VM according to the suspend policy of the class prepare event request.
 	 * </ul>
 	 * <li>For each class that has been unloaded, the VM is expected to
 	 * <ul>
@@ -106,47 +93,38 @@ public interface VirtualMachine {
 	 * </ul>
 	 * </ol>
 	 * <p>
-	 * Subsequent references to classes will work with the new class definition.
-	 * Note the existing <code>com.sun.jdi.ReferenceType</code>,
-	 * <code>com.sun.jdi.Method</code> and <code>com.sun.jdi.Field</code> still
-	 * refer to the old class definition. So they should be discarded when the
-	 * class unload event come in.
-	 * <p>
+	 * Subsequent references to classes will work with the new class definition. Note the existing <code>com.sun.jdi.ReferenceType</code>,
+	 * <code>com.sun.jdi.Method</code> and <code>com.sun.jdi.Field</code> still refer to the old class definition. So they should be discarded when
+	 * the class unload event come in.
+	 * </p>
 	 * The VM does not discard stack frames automatically:
 	 * <ul>
-	 * <li>methods on the stack are not affected, and could therefore be
-	 * referencing obsolete code
+	 * <li>methods on the stack are not affected, and could therefore be referencing obsolete code
 	 * <li>replacing a class does not affect anything on the stack
 	 * <li>subsequent class and method lookups find the replacements
 	 * </ul>
-	 * <p>
-	 * Installed breakpoints are not automatically carried over to the reloaded
-	 * class:
+	 *
+	 * Installed breakpoints are not automatically carried over to the reloaded class:
 	 * <ul>
-	 * <li>breakpoints are resolved to particular locations in particular
-	 * classes and methods
-	 * <li>the VM must clear breakpoints to methods in classes that have been
-	 * reloaded or unloaded (the debugger will reinstall them when it gets the
+	 * <li>breakpoints are resolved to particular locations in particular classes and methods
+	 * <li>the VM must clear breakpoints to methods in classes that have been reloaded or unloaded (the debugger will reinstall them when it gets the
 	 * class prepare event.)
 	 * </ul>
 	 * <p>
-	 * A change notice encompasses changes to the content of a class file in the
-	 * base, the addition of a class files to the base, and the removal of a
+	 * A change notice encompasses changes to the content of a class file in the base, the addition of a class files to the base, and the removal of a
 	 * class file from the base.
+	 * </p>
 	 * <p>
-	 * Change notices apply to all classes that are HCR-eligible (i.e., loaded
-	 * by one of the cooperative system class loaders); other classes are never
-	 * affected.
+	 * Change notices apply to all classes that are HCR-eligible (i.e., loaded by one of the cooperative system class loaders); other classes are
+	 * never affected.
 	 * <p>
-	 * Returns whether the operation could be completed as specified above,
-	 * whether it was ignored (for example if the VM doesn't support this kind
-	 * of replacement), or whether the operation failed and the VM should be
-	 * restarted.
-	 * @param arg1 the names of the classes that have changed
-	 * @return whether the operation could be completed as specified above,
-	 * whether it was ignored (for example if the VM doesn't support this kind
-	 * of replacement), or whether the operation failed and the VM should be
-	 * restarted
+	 * Returns whether the operation could be completed as specified above, whether it was ignored (for example if the VM doesn't support this kind of
+	 * replacement), or whether the operation failed and the VM should be restarted.
+	 *
+	 * @param arg1
+	 *            the names of the classes that have changed
+	 * @return whether the operation could be completed as specified above, whether it was ignored (for example if the VM doesn't support this kind of
+	 *         replacement), or whether the operation failed and the VM should be restarted
 	 */
 	public int classesHaveChanged(String[] arg1);
 }