plugins/org.eclipse.mat.ui.help/reference/oqlsyntaxfrom.dita

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Copyright (c) 2008, 2012 SAP AG, IBM Corporation 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
   
    Contributors:
        SAP AG - initial API and implementation
        IBM Corporation - autocompletion
 -->
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd" >
<reference id="ref_oqlsyntaxfrom" xml:lang="en-us">
	<title>FROM Clause</title>
	<shortdesc />

	<prolog>
		<copyright>
			<copyryear year=""></copyryear>
			<copyrholder>
				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
			</copyrholder>
		</copyright>
	</prolog>

	<refbody>
		<section>
			<title>Specify the class</title>
			<p>
				The FROM clause defines the classes on which to operate.
				Specify the class by one of the following means:
			</p>
			<b>by class name:</b>
			<codeblock>SELECT * FROM java.lang.String</codeblock>
			<b>by a regular expression matching the class name:</b>
			<codeblock>SELECT * FROM "java\.lang\..*"</codeblock>
			<b>by the object address of the class:</b>
			<codeblock>SELECT * FROM 0x2b7468c8</codeblock>
			<b>by the object addresses of more than one class:</b>
			<codeblock>SELECT * FROM 0x2b7468c8,0x2b74aee0</codeblock>
			<b>by the object id of the class:</b>
			<codeblock>SELECT * FROM 20815</codeblock>
			<b>by the object ids of more than one class:</b>
			<codeblock>SELECT * FROM 20815,20975</codeblock>
			<b>by a sub select:</b>
			<codeblock>SELECT * FROM ( SELECT *
                FROM java.lang.Class c
                WHERE c implements org.eclipse.mat.snapshot.model.IClass )</codeblock>
			<p>
				The statement returns all objects in the heap. The
				<cmdname>implements</cmdname>
				check is necessary, as the heap dump can contain
				<cmdname>java.lang.Class</cmdname>
				instances caused by proxy classes or classes representing
				primitive types such as
				<cmdname>int.class</cmdname> or <cmdname>Integer.TYPE</cmdname>.
				The following query has
				the same effect, which calls a method directly on
				the ISnapshot object:
			</p>
			<codeblock>SELECT * FROM ${snapshot}.getClasses()</codeblock>
		</section>
		<section>
			<title>Include sub classes</title>
			<p>
				Use the
				<cmdname>INSTANCEOF</cmdname>
				keyword to include objects of sub-classes into the
				query:
			</p>
			<codeblock>SELECT * FROM INSTANCEOF java.lang.ref.Reference</codeblock>
			<p>
				The resulting table contains, amongst others,
				WeakReference and SoftReference objects because both
				classes extend from
				<cmdname>java.lang.ref.Reference</cmdname>
				. By the way, the same result has the following query
			</p>
			<codeblock>SELECT * FROM ${snapshot}.getClassesByName("java.lang.ref.Reference", true)</codeblock>
		</section>
		<section>
			<title>
				Prevent interpretation of the from term as classes
			</title>
			<p>
				Use the OBJECTS keyword if you do not want to process
				the term as classes.
				Specify the object or objects by one of the following means:
			</p>
			<b>by class name:</b>
			<codeblock>SELECT * FROM OBJECTS java.lang.String</codeblock>
			<p>
				The result is just one object, the java.lang.String
				class object.
			</p>
			<b>by the object address of the particular object:</b>
			<codeblock>SELECT * FROM OBJECTS 0x2b7468c8</codeblock>
			<b>by the object addresses of particular objects:</b>
			<codeblock>SELECT * FROM OBJECTS 0x2b7468c8,0x2b746868</codeblock>
			<b>by the object id of the particular object:</b>
			<codeblock>SELECT * FROM OBJECTS 20815</codeblock>
			<b>by the object ids of particular objects:</b>
			<codeblock>SELECT * FROM OBJECTS 20815,20814</codeblock>
			<b>by a sub expression (Memory Analyzer 1.4 or later):</b>
			<codeblock>SELECT * FROM OBJECTS (1 + ${snapshot}.GCRoots.length)</codeblock>
			<note>
				Please note, that currently the FROM OBJECTS term is in
				the test phase!
			</note>
		</section>
		<section>
			<title>
				Autocompletion
			</title>
			<p>
				The OQL pane now has autocompletion for class names, class name regular expressions,
				field names, attributes and methods. 
				See <xref href="tipsandtricks.dita#oqlcompletion">OQL autocompletion</xref>.
			</p>
		</section>
	</refbody>
</reference>