review request: 6533010 SPEC: A few broken links in jvmti.html

Fri Oct 26 02:21:54 PDT 2012

On 10/26/12 12:28 AM, David Holmes wrote:
> Thanks Serguei,
>
> The specdiff output was not quite what I expected but it's been a long 
> time since I looked at it (and I don't know how to drive it). :)

Jim recommended to use this firefox extension to check links:
https://addons.mozilla.org/en-US/firefox/addon/linkchecker/

   It just colors links green or red.

Both Jim and I used it to verify the links and now all links are green.
I did not find any link in new jvmti.html colored red.

>
> I'm still unclear about the micro version changes. Maybe Dan, or 
> someone else, can comment on how JVMTI versioning works in terms of 
> "spec" version and what the runtime version reports.

BTW, Jim thinks it is probably Ok.
Let's check if anyone else shed a light on it.

Dan, do you have any opinion on this?

Thanks,
Serguei

>
> David
>
> On 26/10/2012 5:05 PM, serguei.spitsyn at oracle.com wrote:
>> David,
>>
>>
>> Thank you for reviewing it and sorry for the latency!
>> Had to learn how to use the specdiff tool.
>>
>> I run it this way:
>> % *java -Xss512m -jar
>> /java/re/specdiff/2.0/archive/fcs/binaries/specdiff.jar jvmti.html
>> new.jvmti.html --hu --config="plain" --out=specdiff-out*
>>
>> The specdiff result is:
>> http://cr.openjdk.java.net/~sspitsyn/webrevs/2012/6533010-JVMTI-doc/specdiff-out/diff.html 
>>
>>
>> I've not found how to get just jvmti.html differences without showing
>> the whole document.
>> Please, let me know if there is a way to generate better differences.
>>
>>
>> Also, this is a simple diff between old and new jvmti.html (please, let
>> me know if you prefer a ontextual diff):
>>
>> sspitsyn at sc11152541 diff jvmti.html new.jvmti.html
>> 5c5
>> < <title>JVM(TM) Tool Interface 1.2.1</title>
>> ---
>>  > <title>JVM(TM) Tool Interface 1.2.2</title>
>> 248c248
>> < <a href="http://java.sun.com/products/jpda/">Java
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">Java 
>>
>>
>> 569c569
>> < <a
>> href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#GetEnv">GetEnv</a>. 
>>
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv">GetEnv</a>. 
>>
>> 679c679
>> < <a
>> href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/types.html#wp16542"> 
>>
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542"> 
>>
>> 714c714
>> < <a
>> href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html">Java 
>>
>>
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java 
>>
>>
>> 809c809
>> < <a
>> href="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp18654">JNI 
>>
>> Documentation</a>).
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI 
>>
>> Documentation</a>).
>> 839c839
>> < <a
>> href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp770">Java 
>>
>> Exceptions</a>
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770">Java 
>>
>> Exceptions</a>
>> 4136c4136
>> < <a
>> href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#wp1060">Attaching 
>>
>> to the VM</a>.
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060">Attaching 
>>
>> to the VM</a>.
>> 8401c8401
>> < Set when the <a 
>> href="#.reference_kind"><code>reference_kind</code></a> is
>> ---
>>  > Set when the <a
>> href="#jvmtiHeapReferenceCallback.reference_kind">reference_kind</a> is
>> 8858c8858
>> < <a
>> href="#FollowReferences.array_primitive_value_callback"><code>array_primitive_value_callback</code></a> 
>>
>> and <code>klass</code>
>> ---
>>  > <a
>> href="#jvmtiHeapCallbacks.array_primitive_value_callback"><code>array_primitive_value_callback</code></a> 
>>
>> and <code>klass</code>
>> 8903c8903
>> < <a
>> href="#jvmtiHeapCallbacks.object_reference_callback"><code>object_reference_callback</code></a> 
>>
>> ---
>>  > <a
>> href="#jvmtiHeapCallbacks.array_primitive_value_callback"><code>array_primitive_value_callback</code></a> 
>>
>> 9182c9182
>> < <a
>> href="#IterateThroughHeap.array_primitive_value_callback"><code>array_primitive_value_callback</code></a> 
>>
>> and <code>klass</code>
>> ---
>>  > <a
>> href="#jvmtiHeapCallbacks.array_primitive_value_callback"><code>array_primitive_value_callback</code></a> 
>>
>> and <code>klass</code>
>> 9227c9227
>> < <a
>> href="#jvmtiHeapCallbacks.object_callback"><code>object_callback</code></a> 
>>
>> ---
>>  > <a
>> href="#jvmtiHeapCallbacks.array_primitive_value_callback"><code>array_primitive_value_callback</code></a> 
>>
>> 14577c14577
>> < <a
>> href="http://java.sun.com/javase/6/docs/guide/jni/spec/types.html#wp16432">JNI 
>>
>>
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI 
>>
>>
>> 20780c20780
>> < See <a
>> href="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html">JNI 
>>
>> ---
>>  > See <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI 
>>
>> 24347c24347
>> < path to a <a 
>> href="http://java.sun.com/javase/6/docs/guide/jar/jar.html">
>> ---
>>  > path to a <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html"> 
>>
>> 24463c24463
>> < In the live phase the <a
>> href="#AddToSystemClassLoaderSearch.segment"><code>segment</code></a> is
>> a platform-dependent path to a <a
>> href="http://java.sun.com/javase/6/docs/guide/jar/jar.html">JAR file</a>
>> to be
>> ---
>>  > In the live phase the <a
>> href="#AddToSystemClassLoaderSearch.segment"><code>segment</code></a> is
>> a platform-dependent path to a <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR 
>>
>> file</a> to be
>> 26775a26776,26781
>>  > <td><code>jchar</code></td><td><a name="jchar"></a>
>>  > Holds a Java programming language <code>char</code>.
>>  > Unsigned 16 bits.
>>  > </td>
>>  > </tr>
>>  > <tr>
>> 26967c26973
>> < <a
>> href="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp23720">JNI 
>>
>> Specification</a>.
>> ---
>>  > <a
>> href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI 
>>
>> Specification</a>.
>> 32210c32216
>> < Version: 1.2.1<p></p>
>> ---
>>  > Version: 1.2.2<p></p>
>> 33568a33575,33580
>>  > <tr>
>>  > <td><b>1.2.2</b>
>>  > <br>11 October 2012</td><td>
>>  > Fixed the "HTTP" and "Missing Anchor" errors reported by the
>> LinkCheck tool.
>>  > </td>
>>  > </tr>
>>
>>
>> My answers on your questions are inlined below.
>>
>>
>>
>> On 10/24/12 8:57 PM, David Holmes wrote:
>>> Serguei,
>>>
>>> Does the change to the micro version need to go through approval
>>> processes?
>>>
>>> That aside I don't quite understand how you can just bump the micro
>>> version for JDK7 when JDK 7 is already out there with a different
>>> micro version. The web version of the spec indicates it is 1.2.1 for
>>> JDK 7:
>>
>> I think, the micro-version must be bumped as it is next version of the
>> document.
>> The mini-version is not bumped because there are not real spec changes.
>> It is just link fixes.
>>
>> Have I answered your question?
>>
>>>
>>> http://docs.oracle.com/javase/7/docs/platform/jvmti/jvmti.html#ChangeHistory 
>>>
>>>
>>>
>>> (Though the change history has not been updated since 2006 :( )
>>
>> I believe, the document really has not been updated since 2006.
>>
>>
>>>
>>> This addition seems unrelated to LinkCheck:
>>>
>>> + <basetype id="jchar">
>>> + <description>
>>> + Holds a Java programming language <code>char</code>.
>>> + Unsigned 16 bits.
>>> + </description>
>>> + </basetype>
>>>
>>> Aside: it would be useful to see a blenderrev or specdiff version of
>>> the change to compare the before and after redndered html.
>>
>> It is a fix for this error reported by LinkCheck:
>> 8710:     <a href=..     Missing Anchor:     #jchar
>>
>>
>>
>>
>> The LinkCheck report:
>> http://javapubs.us.oracle.com/linkcheck_results/javase/7/Platform-Specs.html#platform/jvmti/ 
>>
>>
>>
>> Provided above.
>>
>>
>> Thanks,
>> Serguei
>>
>>>
>>> David
>>>
>>> On 25/10/2012 4:14 AM, serguei.spitsyn at oracle.com wrote:
>>>> Hello,
>>>>
>>>>
>>>> Please, review the fix for (preliminary reviewed by
>>>> james.holmlund at oracle.com) :
>>>> http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6533010
>>>>
>>>> Open webrev:
>>>> http://cr.openjdk.java.net/~sspitsyn/webrevs/2012/6533010-JVMTI-doc
>>>>
>>>> Generated jvmti.html:
>>>> http://javaweb.sfbay.sun.com/java/svc/ss45998/webrevs/2012/hotspot/6533010-JVMTI-doc/jvmti.html 
>>>>
>>>>
>>>>
>>>>
>>>> Summary:
>>>>
>>>> The fix is to remove the errors in generated jvmti.html reported by 
>>>> the
>>>> LinkCheck tool:
>>>> http://javapubs.us.oracle.com/linkcheck_results/javase/7/Platform-Specs.html#platform/jvmti/ 
>>>>
>>>>
>>>>
>>>>
>>>> I verified the fix by looking into the generated jvmti.html:
>>>> http://cr.openjdk.java.net/~sspitsyn/webrevs/2012/6533010-JVMTI-doc/jvmti.html 
>>>>
>>>>
>>>>
>>>>
>>>> One more comment about the JVMTI version and the related changes:
>>>>
>>>> + <change date="11 October 2012" version="1.2.2">
>>>> + Fixed the "HTTP" and "Missing Anchor" errors reported by the 
>>>> LinkCheck
>>>> tool.
>>>> + </change>
>>>> </changehistory>
>>>>
>>>> </specification>
>>>> diff -r 48a75d2640a5 src/share/vm/prims/jvmtiEnvBase.hpp
>>>> --- a/src/share/vm/prims/jvmtiEnvBase.hpp Thu Oct 11 14:27:54 2012 
>>>> -0400
>>>> +++ b/src/share/vm/prims/jvmtiEnvBase.hpp Mon Oct 22 13:07:54 2012 
>>>> -0700
>>>> @@ -67,7 +67,7 @@
>>>> enum {
>>>> JDK15_JVMTI_VERSION = JVMTI_VERSION_1_0 + 33, /* version: 1.0.33 */
>>>> JDK16_JVMTI_VERSION = JVMTI_VERSION_1_1 + 102, /* version: 1.1.102 */
>>>> - JDK17_JVMTI_VERSION = JVMTI_VERSION_1_2 + 1 /* version: 1.2.1 */
>>>> + JDK17_JVMTI_VERSION = JVMTI_VERSION_1_2 + 2 /* version: 1.2.2 */
>>>> };
>>>>
>>>> I've decided to fix just micro version, so new version is 1.2.2 that
>>>> matches JDK 7.
>>>> It is because the fix is for both JFK 7 and 8 and it does not add any
>>>> new features related to JDK 8.
>>>> The enum in the jvmtiEnvBase.hpp is not used anywhere in hotspot code.
>>>> It is just to keep track of JVMTI versions matching different versions
>>>> of JDK.
>>>>
>>>>
>>>> Thanks,
>>>> Serguei
>>>>
>>>>
>>>>
>>>>
>>