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

Fri Oct 26 08:08:25 PDT 2012

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