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

Fri Oct 26 00:28:31 PDT 2012

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). :)

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.

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