# Headless and Programmatic Usage

Eclipse Memory Analyzer is an Eclipse application. Its parsers, queries, and
extension points are all wired through the Eclipse OSGi plugin infrastructure.
This means you cannot simply add MAT JARs to a plain Java classpath and call
`SnapshotFactory.openSnapshot()` -- the Eclipse extension registry will not be
initialized, and you will get a `NullPointerException` from
`Platform.getExtensionRegistry()`.

There are several supported ways to use the MAT analysis engine without the
desktop GUI, ranging from simple command-line scripts to full programmatic
embedding.

## Approach comparison

| Approach | Effort | Best for |
|----------|--------|----------|
| [ParseHeapDump scripts](#parseheapdump-scripts) | Low -- run a shell script | CI pipelines, batch reports, one-off server-side analysis |
| [Eclipse JIFA](#eclipse-jifa) | Medium -- deploy a service or container | Web-based collaborative analysis, REST API access to MAT |
| [Direct OSGi embedding](#direct-osgi-embedding) | High -- bootstrap Equinox yourself | Custom tooling that needs full `ISnapshot` API access |
| [Docker wrapping](#docker-wrapping) | Low -- pull an image | Portable CI/CD without installing MAT |

## ParseHeapDump scripts

Every MAT installation includes `ParseHeapDump.sh` (Linux/macOS) and
`ParseHeapDump.bat` (Windows). These scripts launch the MAT engine as an
Eclipse headless application and produce ZIP files containing HTML reports.

### Basic indexing

Running without any report arguments parses the heap dump and generates index
files. These index files make subsequent analysis (in the GUI or via further
script runs) significantly faster.

```shell
/path/to/mat/ParseHeapDump.sh /path/to/heapdump.hprof
```

### Generating reports

Append one or more report IDs to produce ZIP files with HTML reports:

```shell
/path/to/mat/ParseHeapDump.sh /path/to/heapdump.hprof \
  org.eclipse.mat.api:suspects \
  org.eclipse.mat.api:overview \
  org.eclipse.mat.api:top_components
```

Available built-in reports:

| Report ID | Output |
|-----------|--------|
| `org.eclipse.mat.api:suspects` | Leak suspect report |
| `org.eclipse.mat.api:overview` | Overview report |
| `org.eclipse.mat.api:top_components` | Top memory consumers by component |

### Running a single query

The `org.eclipse.mat.api:query` report runs a single MAT command or OQL query
and produces an HTML report from the result.

```shell
# Run the histogram command
/path/to/mat/ParseHeapDump.sh heapdump.hprof \
  "-command=histogram" \
  org.eclipse.mat.api:query

# Run an OQL query (quote the whole -command argument)
/path/to/mat/ParseHeapDump.sh heapdump.hprof \
  "-command=oql \"SELECT * FROM java.lang.String s WHERE s.count > 1000\"" \
  org.eclipse.mat.api:query
```

Add `-format=txt -unzip` after the report ID to get plain text output instead of
zipped HTML.

### Comparing two heap dumps

```shell
# General comparison
/path/to/mat/ParseHeapDump.sh heapdump1.hprof \
  -snapshot2=heapdump2.hprof \
  org.eclipse.mat.api:compare

# Leak suspects comparison
/path/to/mat/ParseHeapDump.sh heapdump1.hprof \
  -baseline=heapdump2.hprof \
  org.eclipse.mat.api:suspects2
```

### Parse options

| Option | Effect |
|--------|--------|
| `-keep_unreachable_objects` | Retain objects not reachable from GC roots |
| `-snapshot_identifier=<id>` | Select a specific snapshot when the file contains multiple (e.g. `#1`, `#2`) |
| `-discard_pattern=<regex>` | (Experimental) Discard objects matching the class name pattern |

### Truly headless environments (no GTK)

Newer versions of `ParseHeapDump.sh` invoke the `MemoryAnalyzer` binary, which
may attempt to load GTK libraries. On servers without a display or GTK, invoke
the Equinox launcher directly:

```shell
java -Xmx4g \
  -jar /path/to/mat/plugins/org.eclipse.equinox.launcher_*.jar \
  -consoleLog \
  -application org.eclipse.mat.api.parse \
  /path/to/heapdump.hprof \
  org.eclipse.mat.api:suspects
```

Adjust `-Xmx` to match the size of the heap dump being analyzed. See the
[FAQ](faq.md#how-much-heap-do-i-need) for sizing guidance.

### Batch mode reference

See the Eclipse help page on
[Batch mode](https://help.eclipse.org/latest/topic/org.eclipse.mat.ui.help/tasks/batch.html)
for the full reference.

## Eclipse JIFA

[Eclipse JIFA](https://eclipse-jifa.github.io/jifa/) (Java Issue Finding
Assistant) wraps the MAT analysis engine in a web application with a REST API.
It handles the OSGi bootstrapping internally, so you do not need to manage
Eclipse infrastructure yourself.

JIFA provides:

- A web UI for heap dump analysis (leak detection, dominator tree, OQL)
- GC log, thread dump, and JFR analysis
- Collaborative analysis -- multiple users can access the same server

### Quick start with Docker

```shell
docker run -p 8102:8102 eclipsejifa/jifa
```

The service is then available at `http://localhost:8102`. Upload a heap dump
through the web interface to begin analysis.

To analyze a local file directly:

```shell
docker run -p 8102:8102 \
  -v /path/to/dumps:/dumps \
  eclipsejifa/jifa
```

### Building from source

```shell
git clone https://github.com/eclipse/jifa.git
cd jifa
./gradlew buildJifa
```

JIFA's Gradle build uses the
[p2asmaven](https://github.com/niclasr/goomph) plugin to download MAT JARs
from the Eclipse P2 update sites automatically.

### When to use JIFA

JIFA is the recommended path when you want to use the MAT engine from a
non-Eclipse Java application. Rather than bootstrapping OSGi yourself, JIFA
provides a tested integration. It is also useful when you need to share analysis
results across a team via a central server.

For more information, see the
[JIFA documentation](https://eclipse-jifa.github.io/jifa/).

## Direct OSGi embedding

If you need full programmatic access to the MAT `ISnapshot` API within your own
JVM process, you must bootstrap the Eclipse Equinox OSGi runtime so that MAT's
extension points are properly initialized.

This is an advanced approach. The MAT codebase does not provide a standalone
"MAT as a library" artifact -- the Eclipse plugin architecture is a fundamental
part of the design, not an incidental dependency.

### Reference implementations

Two existing implementations demonstrate the pattern:

1. **ParseSnapshotApp** in the MAT source code
   ([ParseSnapshotApp.java](https://github.com/eclipse-mat/mat/blob/master/plugins/org.eclipse.mat.api/src/org/eclipse/mat/internal/apps/ParseSnapshotApp.java))
   is the application behind `ParseHeapDump.sh`. It shows how to open a
   snapshot and run queries within a properly initialized Eclipse application.

2. **Eclipse JIFA** embeds the MAT engine by pulling dependencies from Eclipse
   P2 update sites and initializing the OSGi bundle context. Its
   `HeapDumpAnalyzerImpl` class demonstrates calling `SnapshotFactory` with a
   properly running extension registry.

### Key requirements

- All MAT plugins and their transitive Eclipse dependencies must be available
  as OSGi bundles
- The Equinox OSGi framework must be started before any MAT API calls
- Extension points for parsers (HPROF, DTFJ) and queries are discovered
  through the Eclipse extension registry at runtime

### Common pitfall

Calling `SnapshotFactory.openSnapshot()` without a running OSGi runtime produces:

```
java.lang.NullPointerException: Cannot invoke
  "org.eclipse.core.runtime.IExtensionRegistry.getExtensionPoint(String)"
  because the return value of
  "org.eclipse.core.runtime.Platform.getExtensionRegistry()" is null
```

This error means the Eclipse platform is not initialized. You must either use
one of the higher-level approaches above (ParseHeapDump, JIFA) or fully
bootstrap Equinox in your application.

See [issue #155](https://github.com/eclipse-mat/mat/issues/155) for further
discussion of this topic.

## Docker wrapping

For CI/CD pipelines where you want MAT analysis without installing it on the
build agent, a Docker image can be used.

The [dgroup/mat](https://github.com/dgroup/mat) project provides a pre-built
Docker image:

```shell
docker run -it --rm \
  -v "$PWD":/dumps -w /dumps \
  dgroup/mat \
  /mat/ParseHeapDump.sh heapdump.hprof \
    org.eclipse.mat.api:suspects \
    org.eclipse.mat.api:overview \
    org.eclipse.mat.api:top_components
```

This approach combines the simplicity of the ParseHeapDump scripts with the
portability of containers.