Make it easier to write extensions

[eclipsewebmaster]

| --- | --- |
| Bugzilla Link | 327129 |
| Status | ASSIGNED |
| Importance | P3 normal |
| Reported | Oct 06, 2010 11:53 EDT |
| Modified | Nov 09, 2022 08:44 EDT |
| Version | 1.1 |
| Depends on | 327564 |
| See also | Gerrit change 180301, Git commit 42186a66, Gerrit change 180341, Git commit 242aeffa, Gerrit change 180370, Git commit df3fbb8b, Gerrit change 180609, Git commit 2848d7ab, Gerrit change 196845, Git commit 7cd65a49 |
| Reporter | Andrew Johnson |

Description

We should make it easier to write extensions for MAT - e.g. for name resolvers, queries, etc.

One aspect is to improve Javadoc and schema definitions.

Some sample extensions could be useful too.

We also need some good instructions - should adopters have to get the source for MAT, or should it be possible to build extensions against a binary version of MAT.

[eclipsewebmaster]

By Krum Tsvetkov on Oct 08, 2010 03:43

I fully agree that this is an area where we need to improve (a lot).

Javadoc and schema is a good start.

About examples, I often wonder if it is better to have separate sample extensions, or just point to some understandable "real" extensions within MAT's own coding. What do you think?

The instructions point is also good. I think it should be possible (and easy) for adopters to develop both against binaries and against sources.
When using sources - we need to update the instructions on the Wiki, as well as to provide different team project sets. For the project set I got already the complaint that after checkout some things don't compile (some have dependencies on BIRT or DTFJ). Therefore I think it may be useful to have several different project set files and a good description.

I have one more point - documentation on how to use MAT's API and how to extend the tool. Here I believe the easiest solution will be to start writing in Wiki. So far I imagine two major sections - 1) using MAT's API to extract/read data from heap dumps and 2) extending the tool.

Shall I create separate bugzilla entries for the different topics? Any other thoughts on the topic?

[eclipsewebmaster]

By Andrew Johnson on Oct 11, 2010 11:31

Source bundles can be used to provide Javadoc.

Currently exporting source bundles for org.eclipse.mat.api gives two copies of the source, in org/eclipse/mat and src/org/eclipse/mat

We should fix the source export, and preferably build the source bundles as a feature.

[eclipsewebmaster]

By Andrew Johnson on Oct 12, 2010 07:39

Ideally we would build source bundles and features, but until then it helps to have the schema files in the binary bundles. They exist in api and parser, but not report.

[eclipsewebmaster]

By Andrew Johnson on Oct 12, 2010 13:07

Now I have added the org.eclipse.pde.core.javadoc extension to o.e..mat.ui.help and the schema files to o.e.mat.report then it is much easier to compile against a binary version of MAT.

Create MAT as a target platform:

Windows->Preferences->Plug-in Development->Target Platform
Add->Nothing->Next
Name: MAT
Locations->Add->Installation
Location: path_to_MAT/mat
Finish

Select MAT as active target platform

Create a new plug-in project:

File->New->Other->Plug-in project

Name: MAT Extension
->Next
Execution Environment: J2SE-1.5 (that's all MAT currently requires)
No activator (unless you are doing something complicated)
No UI contribution
No API analysis
No template
->Finish
Dependencies
add org.eclipse.mat.api
Save (cntl-S)
Extensions
select org.eclipse.mat.api.nameResolver
->Finish
click on impl
Adjust package name and class name to suit
->Finish

Add for example
@subject("java.lang.Runtime")
before the class definition

Organize imports (cntl-shift-O)

In
public String resolve(IObject object)
Change
return null;
to
return "The Java runtime of size"+object.getUsedHeapSize();

Note the hover javadoc help for IObject, IClassSpecificNameResolver.
Note the method list for object.

Save

To test:
Select Plug-in, Run As->Eclipse Application

[eclipsewebmaster]

By Andrew Johnson on Feb 10, 2011 10:07

I've added an XML schema for report XML files.

This helps validate the report definitions. We may need to move the xsd file elsewhere, add name spaces etc., so that user written reports can pick up the schema. Perhaps an XML expert can help.

One problem this flagged was the overview.xml file which had

but this is not recognized by the code. Instead:

would be the way this is done.
The equals could be a problem if column names were used with an equals.

Should we use:


or

[eclipsewebmaster]

By Andrew Johnson on Feb 10, 2011 15:59

One aspect of param is that it could be used to set up parameters for the command which are substituted with ${}.
The schema disallows this, but the report generator doesn't enforce this restriction.
Is this useful?
Will we avoid more errors with invalid predefined parameters if the schema gives an error for this?

E.g.


cmd ${config1}
</query

Also, applying the schema to regression.xml and performance.xml gives errors for params after the command and for

It seems to me that restricting params to before the command makes the xml more readable, so is fair.

Should we add a sort_order parameter? One possible reason for a = on sort_column would be for sorting by multiple columns, but that seems tricky and sort_order could use a multiple value too:
sort_column="#1=ASC,#2=DESC"
or
sort_column="#1,#2"
sort_order="ASC,DESC"

[eclipsewebmaster]

By Krum Tsvetkov on Mar 11, 2011 10:20

Programming agains MAT set as target platform works very good now (comment 4).

I also like the idea with the schema for the report. However, I didn't fully understand what the problem with the param/command elements is/was.

[eclipsewebmaster]

By Andrew Johnson on Mar 23, 2011 09:22

(In reply to comment #7)

I also like the idea with the schema for the report. However, I didn't fully
understand what the problem with the param/command elements is/was.

The param element has a key attribute which is defined as being of type string with a restriction that only certain values are allowed:
<xs:enumeration value="format" />
<xs:enumeration value="filename" />
<xs:enumeration value="filename_suffix" />

		<xs:enumeration value="html.collapsed" />\
		<xs:enumeration value="html.separate_file" />\
		<xs:enumeration value="html.is_important" />\
		<xs:enumeration value="html.show_table_header" />\
		<xs:enumeration value="html.show_heading" />\
		<xs:enumeration value="html.show_totals" />\
		<xs:enumeration value="html.render_details" />

		<xs:enumeration value="sort_column" />\
		<xs:enumeration value="filter" />\
		<xs:enumeration value="limit" />\
		<xs:enumeration value="hide_column" />

		<xs:enumeration value="derived_data_column" />

This means that a key of any other value will cause a validation error.

I think we should add a
<xs:enumeration value="rendering.pattern" />
which would match Params.java

I'll update the test reports to match the new schema.

[eclipsewebmaster]

May 06, 2021 09:27

New Gerrit change created: https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/180301

[eclipsewebmaster]

May 06, 2021 09:29

Gerrit change https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/180301 was merged to [master].
Commit: http://git.eclipse.org/c/mat/org.eclipse.mat.git/commit/?id=42186a66177c785691923827dc25f55bba14c274

[eclipsewebmaster]

May 07, 2021 02:45

New Gerrit change created: https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/180341

[eclipsewebmaster]

May 07, 2021 02:48

Gerrit change https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/180341 was merged to [master].
Commit: http://git.eclipse.org/c/mat/org.eclipse.mat.git/commit/?id=242aeffa31b4b7c218c11d83dbf380137b1a0f3a

[eclipsewebmaster]

May 07, 2021 13:06

New Gerrit change created: https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/180370

[eclipsewebmaster]

May 07, 2021 13:07

Gerrit change https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/180370 was merged to [master].
Commit: http://git.eclipse.org/c/mat/org.eclipse.mat.git/commit/?id=df3fbb8be876814541e4861f16932e98586e05d5

[eclipsewebmaster]

May 14, 2021 11:25

New Gerrit change created: https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/180609

[eclipsewebmaster]

May 14, 2021 11:28

Gerrit change https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/180609 was merged to [master].
Commit: http://git.eclipse.org/c/mat/org.eclipse.mat.git/commit/?id=2848d7ab4d53d09307b54a8f8347997d4452a3ef

[eclipsewebmaster]

Nov 09, 2022 08:31

New Gerrit change created: https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/196845

[eclipsewebmaster]

Nov 09, 2022 08:44

Gerrit change https://git.eclipse.org/r/c/mat/org.eclipse.mat/+/196845 was merged to [master].
Commit: http://git.eclipse.org/c/mat/org.eclipse.mat.git/commit/?id=7cd65a495493e38f80001dcd766db2eb21fa24d4