# Heap Dump Parser

###### Identifier:

org.eclipse.mat.parser.parser

###### Since:

0.7.0

###### Description:

The format of heap dumps is specific to the Virtual Machine used. This extensions allows to plug in new dump formats. Out of the box, the Memory Analyzer supports HPROF and IBM dumps read via DTFJ. A DTFJ implementation is available from IBM developerWorks.

###### Configuration Markup:

<!ELEMENT extension (parser)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #REQUIRED

name CDATA #REQUIRED

>

<!ELEMENT parser EMPTY>

<!ATTLIST parser

name CDATA #REQUIRED

fileExtension CDATA #REQUIRED

indexBuilder CDATA #REQUIRED

objectReader CDATA #REQUIRED

dynamic CDATA #IMPLIED

>

- name - Name of the heap dump format. For example, shown in the file selection dialog.
- fileExtension - The file extension typically associated witht the file format. Used to filter files in the file selection dialog.
- indexBuilder - implementor of `org.eclipse.mat.snapshot.adapter.IIndexBuilder` which creates the index files, i.e. the structural information of the heap dump like the reference graph
- objectReader - implementor of `org.eclipse.mat.parser.IObjectReader` to read the object details from the heap dump file
- dynamic - This is a class which extends java.util.Map and returns a set of extensions and descriptions, together with ids which replace the attributes "id", "name", "fileExtension" in the dynamic parser.

###### Examples:

Following is an example of a parser declaration:

       <extension
             id="hprof"
             name="HPROF Formatted Dumps"
             point="org.eclipse.mat.parser.parser">
          <parser
            name="HPROF binary heap dumps"
                fileExtension="hprof,bin"
                indexBuilder="org.eclipse.mat.hprof.HprofIndexBuilder"
                objectReader="org.eclipse.mat.hprof.HprofHeapObjectReader">
          </parser>
       </extension>

###### API Information:

The value of the indexBuilder attribute must represent an implementor of `org.eclipse.mat.parser.IIndexBuilder`, the objectReader attribute `org.eclipse.mat.parser.IObjectReader`. The dynamicParser attribute is a class which extends java.util.Map and returns a set of extensions and descriptions, together with ids which replace the attributes "id", "name", "fileExtension" in the dynamic parser.

    Map<String, Map<String, String>>

Main id
  fully qualified id for each parser
  id
    fully qualified id for the parser
  name
    readable name for the parser
  fileExtension
    file extensions for this parser

The subparsers share the indexBuilder and objectReader.

This is used for example by the DTFJ parser which has to find out at run time which DTFJ implementations are available and to create an MAT parser definition for each one.

###### Supplied Implementation:

The Memory Analyzer supplies an implementation for HPROF and IBM DTFJ format dumps. Check out the `org.eclipse.mat.hprof` plug-in and `org.eclipse.mat.dtfj` plug-in. A DTFJ implementation is available from IBM DeveloperWorks.

Copyright (c) 2008,2011 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 http://www.eclipse.org/legal/epl-v10.html