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

[serguei.spit...@oracle.com]

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.spit...@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.spit...@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@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.spit...@oracle.com wrote:
Hello,


Please, review the fix for (preliminary reviewed by
james.holml...@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