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

Sat Oct 27 05:13:22 PDT 2012

Thanks, David!
Serguei

On 10/27/12 12:42 AM, David Holmes wrote:
> On 27/10/2012 3:44 AM, serguei.spitsyn at oracle.com wrote:
>> Thanks, Dan!
>>
>> My memory told me that the jvmti version has to be auto-updated, and I
>> was surprised that it is not.
>> I forgot that the SCCS ident string was used in the past and now it is
>> gone.
>>
>> So, David, are we Ok to integrate the fix now?
>
> I have no problem with it.
>
> Thanks,
> David
>
>> Thanks,
>> Serguei
>>
>>
>> On 10/26/12 8:08 AM, Daniel D. Daugherty wrote:
>>>> Dan, do you have any opinion on this?
>>>
>>> The micro version used to be auto generated from part of the SCCS
>>> ident string so it was modified every time the "source" file was
>>> changed. That mechanism was not carried forward into the Mercurial
>>> world.
>>>
>>> In other words, the micro version isn't something that any agent
>>> code could or should depend on because it could change (in the past)
>>> due to something not related to code.
>>>
>>> That said, the micro version only gets updated now when someone
>>> remembers to do it. Now code shouldn't depend on the micro
>>> version because it can be stale. That should probably be fixed
>>> in some way.
>>>
>>> Dan
>>>
>>>
>>>
>>> On 10/26/12 3:21 AM, serguei.spitsyn at oracle.com wrote:
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> 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
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>
>>>>
>>