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

Fri Oct 26 10:44:00 PDT 2012

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?

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
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>
>>