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

Sat Oct 27 00:42:27 PDT 2012

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