552879: OQL enhancements for sub-selects, maps, context providers

More help

Change-Id: Ic49d4d51dd06f202931edd5a5bb53b01982f0387
Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=552879

2 files changed, 73 insertions, 31 deletions

diff --git a/plugins/org.eclipse.mat.ui.help/reference/propertyaccessors.dita b/plugins/org.eclipse.mat.ui.help/reference/propertyaccessors.dita
index 039ea94c..c572e2a3 100644
--- a/plugins/org.eclipse.mat.ui.help/reference/propertyaccessors.dita
+++ b/plugins/org.eclipse.mat.ui.help/reference/propertyaccessors.dita
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>

 <!--

-    Copyright (c) 2008, 2010 SAP AG.

+    Copyright (c) 2008, 2020 SAP AG and IBM Corporation.

     All rights reserved. This program and the accompanying materials

     are made available under the terms of the Eclipse Public License v1.0

     which accompanies this distribution, and is available at

@@ -8,6 +8,7 @@
    

     Contributors:

         SAP AG - initial API and implementation

+        Andrew Johnson (IBM Corporation) - enhancements

  -->

 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd" >

 <reference id="propertyaccessors" xml:lang="en-us">

@@ -17,7 +18,7 @@
 		<copyright>

 			<copyryear year=""></copyryear>

 			<copyrholder>

-				Copyright (c) 2008, 2010 SAP AG and others.

+				Copyright (c) 2008, 2020 SAP AG and others.

 			    All rights reserved. This program and the accompanying materials

 			    are made available under the terms of the Eclipse Public License v1.0

 			    which accompanies this distribution, and is available at

@@ -68,67 +69,67 @@
 				<strow>

 					<stentry>Any heap object</stentry>

 					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#method_summary" format="html">IObject</xref></stentry>

-					<stentry>objectId</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getObjectId--" format="html">objectId</xref></stentry>

 					<stentry>id of snapshot object</stentry>

 				</strow>

 				<strow>

 					<stentry />

 					<stentry />

-					<stentry>objectAddress</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getObjectAddress--" format="html">objectAddress</xref></stentry>

 					<stentry>address of snapshot object</stentry>

 				</strow>

 				<strow>

 					<stentry />

 					<stentry />

 					<stentry>class</stentry>

-					<stentry>Java class of this object</stentry>

+					<stentry>Java class of this object as a Memory Analyzer object</stentry>

 				</strow>

 				<strow>

 					<stentry />

 					<stentry />

-					<stentry>clazz</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getClazz--" format="html">clazz</xref></stentry>

 					<stentry>IClass of this object. See also classof(object).</stentry>

 				</strow>

 				<strow>

 					<stentry />

 					<stentry />

-					<stentry>usedHeapSize</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getUsedHeapSize--" format="html">usedHeapSize</xref></stentry>

 					<stentry>shallow heap size</stentry>

 				</strow>

 				<strow>

 					<stentry />

 					<stentry />

-					<stentry>retainedHeapSize</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getRetainedHeapSize--" format="html">retainedHeapSize</xref></stentry>

 					<stentry>retained heap size</stentry>

 				</strow>

 				<strow>

 					<stentry />

 					<stentry />

-					<stentry>displayName</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getDisplayName--" format="html">displayName</xref></stentry>

 					<stentry>display name</stentry>

 				</strow>

 				<strow>

 					<stentry>Class object</stentry>

 					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IClass.html#method_summary" format="html">IClass</xref></stentry>

-					<stentry>classLoaderId</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IClass.html#getClassLoaderId--" format="html">classLoaderId</xref></stentry>

 					<stentry>id of the class loader</stentry>

 				</strow>

 				<strow>

 					<stentry>Any array</stentry>

 					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IArray.html#method_summary" format="html">IArray</xref></stentry>

-					<stentry>length</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IArray.html#getLength--" format="html">length</xref></stentry>

 					<stentry>length of the array</stentry>

 				</strow>

 				<strow>

 					<stentry>Primitive array</stentry>

 					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IPrimitiveArray.html#method_summary" format="html">IPrimitiveArray</xref></stentry>

-					<stentry>valueArray</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IPrimitiveArray.html#getValueArray--" format="html">valueArray</xref></stentry>

 					<stentry>the values in the array</stentry>

 				</strow>

 				<strow>

 					<stentry>Reference array</stentry>

 					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObjectArray.html#method_summary" format="html">IObjectArray</xref></stentry>

-					<stentry>referenceArray</stentry>

+					<stentry><xref href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObjectArray.html#getReferenceArray--" format="html">referenceArray</xref></stentry>

 					<stentry>the objects in the array (as long values, the addresses of the objects)

 					Access a particular element using get() and convert to an object using OBJECTS.

 					</stentry>

@@ -285,8 +286,25 @@
 			</p>

 		</section>

 		<section>

-		<title>

-		</title>

+			<title>Collection access</title>

+			<codeblock>SELECT a[0] FROM java.util.ArrayList a</codeblock>

+			<p>Many of the standard collections classes are well known by Memory Analyzer.

+			The <xref href="../tasks/analyzingjavacollectionusage.dita">collection queries</xref>

+			allow analysis of lists, sets, queues, deques and maps.

+			This access is extended to OQL so if the collection queries work with a particular

+			collection or map then so does OQL.

+			</p>

+			<note>Collection and map access is still experimental and subject to change.</note>

+			<codeblock>SELECT a[0:-1] FROM java.util.ArrayList a</codeblock>

+			<p>If the array access syntax is used on a collection (list,set, queue, deque) object

+			then particular elements of the collection can be extracted. If subarray syntax

+			is used then that part of collection is converted to a list ready for further processing</p>

+			<codeblock>SELECT h[0].@key, h[0].@value FROM java.util.HashMap h</codeblock>

+			<p>If the array access syntax is used on a map then the map is converted to a list of

+			map entries. These can then be examined using the bean access syntax to retrieve the key

+			<codeph>h[0].@key</codeph> or value <codeph>h[0].@value</codeph>.

+			See <xref format="html" href="https://wiki.eclipse.org/MemoryAnalyzer/OQL#Map_processing">Wiki OQL Map processing</xref>

+			for more details of OQL with maps and collections.</p>

 		</section>

 		<section>

 			<title>Built-in OQL functions</title>

diff --git a/plugins/org.eclipse.mat.ui.help/reference/propertyaccessors.html b/plugins/org.eclipse.mat.ui.help/reference/propertyaccessors.html
index ac770fdd..07f111f9 100644
--- a/plugins/org.eclipse.mat.ui.help/reference/propertyaccessors.html
+++ b/plugins/org.eclipse.mat.ui.help/reference/propertyaccessors.html
@@ -9,8 +9,8 @@
 <meta name="abstract" content=""/>
 <meta name="description" content=""/>
 <meta name="DC.Relation" scheme="URI" content="../reference/oqlsyntax.html"/>
-<meta name="copyright" content="Copyright (c) 2008, 2010 SAP AG and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html " type="primary"/>
-<meta name="DC.Rights.Owner" content="Copyright (c) 2008, 2010 SAP AG and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html " type="primary"/>
+<meta name="copyright" content="Copyright (c) 2008, 2020 SAP AG and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html " type="primary"/>
+<meta name="DC.Rights.Owner" content="Copyright (c) 2008, 2020 SAP AG and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html " type="primary"/>
 <meta name="DC.Format" content="XHTML"/>
 <meta name="DC.Identifier" content="propertyaccessors"/>
 <meta name="DC.Language" content="en-us"/>
@@ -75,7 +75,7 @@
 
 					<td valign="top" class="stentry" width="22.22222222222222%"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#method_summary">IObject</a></td>
 
-					<td valign="top" class="stentry" width="22.22222222222222%">objectId</td>
+					<td valign="top" class="stentry" width="22.22222222222222%"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getObjectId--">objectId</a></td>
 
 					<td valign="top" class="stentry" width="33.33333333333333%">id of snapshot object</td>
 
@@ -85,7 +85,7 @@
 
 					<td valign="top" class="stentry"> </td>
 
-					<td valign="top" class="stentry">objectAddress</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getObjectAddress--">objectAddress</a></td>
 
 					<td valign="top" class="stentry">address of snapshot object</td>
 
@@ -97,7 +97,7 @@
 
 					<td valign="top" class="stentry">class</td>
 
-					<td valign="top" class="stentry">Java class of this object</td>
+					<td valign="top" class="stentry">Java class of this object as a Memory Analyzer object</td>
 
 				</tr>
 <tr class="strow">
@@ -105,7 +105,7 @@
 
 					<td valign="top" class="stentry"> </td>
 
-					<td valign="top" class="stentry">clazz</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getClazz--">clazz</a></td>
 
 					<td valign="top" class="stentry">IClass of this object. See also classof(object).</td>
 
@@ -115,7 +115,7 @@
 
 					<td valign="top" class="stentry"> </td>
 
-					<td valign="top" class="stentry">usedHeapSize</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getUsedHeapSize--">usedHeapSize</a></td>
 
 					<td valign="top" class="stentry">shallow heap size</td>
 
@@ -125,7 +125,7 @@
 
 					<td valign="top" class="stentry"> </td>
 
-					<td valign="top" class="stentry">retainedHeapSize</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getRetainedHeapSize--">retainedHeapSize</a></td>
 
 					<td valign="top" class="stentry">retained heap size</td>
 
@@ -135,7 +135,7 @@
 
 					<td valign="top" class="stentry"> </td>
 
-					<td valign="top" class="stentry">displayName</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObject.html#getDisplayName--">displayName</a></td>
 
 					<td valign="top" class="stentry">display name</td>
 
@@ -145,7 +145,7 @@
 
 					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IClass.html#method_summary">IClass</a></td>
 
-					<td valign="top" class="stentry">classLoaderId</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IClass.html#getClassLoaderId--">classLoaderId</a></td>
 
 					<td valign="top" class="stentry">id of the class loader</td>
 
@@ -155,7 +155,7 @@
 
 					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IArray.html#method_summary">IArray</a></td>
 
-					<td valign="top" class="stentry">length</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IArray.html#getLength--">length</a></td>
 
 					<td valign="top" class="stentry">length of the array</td>
 
@@ -165,7 +165,7 @@
 
 					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IPrimitiveArray.html#method_summary">IPrimitiveArray</a></td>
 
-					<td valign="top" class="stentry">valueArray</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IPrimitiveArray.html#getValueArray--">valueArray</a></td>
 
 					<td valign="top" class="stentry">the values in the array</td>
 
@@ -175,7 +175,7 @@
 
 					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObjectArray.html#method_summary">IObjectArray</a></td>
 
-					<td valign="top" class="stentry">referenceArray</td>
+					<td valign="top" class="stentry"><a class="xref" href="../../../ntopic/org.eclipse.mat.ui.help/doc/org/eclipse/mat/snapshot/model/IObjectArray.html#getReferenceArray--">referenceArray</a></td>
 
 					<td valign="top" class="stentry">the objects in the array (as long values, the addresses of the objects)
 					Access a particular element using get() and convert to an object using OBJECTS.
@@ -404,9 +404,33 @@
 
 		</div>
 
-		<div class="section"><!--no heading--><h2 class="title sectiontitle">
-		</h2>
-		
+		<div class="section"><h2 class="title sectiontitle">Collection access</h2>
+			
+			<pre class="pre codeblock">SELECT a[0] FROM java.util.ArrayList a</pre>
+
+			<p class="p">Many of the standard collections classes are well known by Memory Analyzer.
+			The <a class="xref" href="../tasks/analyzingjavacollectionusage.html">collection queries</a>
+			allow analysis of lists, sets, queues, deques and maps.
+			This access is extended to OQL so if the collection queries work with a particular
+			collection or map then so does OQL.
+			</p>
+
+			<div class="note note"><span class="notetitle">Note:</span> Collection and map access is still experimental and subject to change.</div>
+
+			<pre class="pre codeblock">SELECT a[0:-1] FROM java.util.ArrayList a</pre>
+
+			<p class="p">If the array access syntax is used on a collection (list,set, queue, deque) object
+			then particular elements of the collection can be extracted. If subarray syntax
+			is used then that part of collection is converted to a list ready for further processing</p>
+
+			<pre class="pre codeblock">SELECT h[0].@key, h[0].@value FROM java.util.HashMap h</pre>
+
+			<p class="p">If the array access syntax is used on a map then the map is converted to a list of
+			map entries. These can then be examined using the bean access syntax to retrieve the key
+			<samp class="ph codeph">h[0].@key</samp> or value <samp class="ph codeph">h[0].@value</samp>.
+			See <a class="xref" href="https://wiki.eclipse.org/MemoryAnalyzer/OQL#Map_processing">Wiki OQL Map processing</a>
+			for more details of OQL with maps and collections.</p>
+
 		</div>
 
 		<div class="section"><h2 class="title sectiontitle">Built-in OQL functions</h2>