[mat-dev] API changes: read primitive array content

["Buchen, Andreas" <andreas.buchen@xxxxxxx>]

Hi all,

we have been discussing API changes to IArray, IObjectArray and IPrimitiveArray. These changes become necessary as we plan to support other heap dump formats like DTFJ and PHP.


What is it about?

The current IArray interface has two methods to retrieve the array content.

public interface IArray extends IObject
{
    public int getLength();
    public Object getContent();
    public Object getContent(int offset, int length);
}

For an object array, the content is returned as long[], e.g. object addresses. A '0' indicates a null value in the array.

For primitive arrays, the content is returned as byte[]. To get to the underlying char[], long[], int[] etc., one needs to convert the raw bytes into the appropriate primitive type (IPrimitiveArray#getType).

This approach has two problems:
(a) Every user of the API has to do the conversion if he/she wants to access the actual primitive values.
(b) The DTFJ interface already returns the correct primitive values. To implement the current interface, the DTFJ adapter needs to convert the char[] into and byte[], so that the reader then must convert the byte[] back to a char[]. This is obviously inefficient.



I propose the following changes:

public interface IArray extends IObject
{
    public int getLength();
}

public interface IObjectArray extends IArray
{
    long[] getReferenceArray();
    long[] getReferenceArray(int offset, int length);
}

public interface IPrimitiveArray extends IArray
{
    /** returns an array with the correct component type */
    public Object getValueArray();
    public Object getValueArray(int offset, int length);

    [...]
}


This in turn, requires changes to the Adapter API:

public interface IObjectReader
{
    Object readPrimitiveArrayContent(PrimitiveArrayImpl array, int offset, int length) //
                    throws IOException, SnapshotException;

    long[] readObjectArrayContent(ObjectArrayImpl array, int offset, int length) //
                    throws IOException, SnapshotException;

    [...]
}

Basically, the IObjectArray and IPrimitiveArray methods call in turn the appropriate IObjectReader methods. The object reader would need to (a) convert and return the primitive arrays with the proper component type and (b) take care of any necessary caching, lazy reading etc. The org.eclipse.mat.hprof.HprofHeapObjectReader could serve as an example.



Kind regards,

Andreas.






Andreas Buchen
Senior Software Developer
SAP AG
Dietmar-Hopp-Allee 16
69190 Walldorf, Germany
andreas dot buchen at sap dot com
www.sap.com

Sitz der Gesellschaft/Registered Office: Walldorf, Germany 
Vorstand/SAP Executive Board: Henning Kagermann (Sprecher/Co-CEO), Léo Apotheker
(Sprecher/Co-CEO), Werner Brandt, Erwin Gunst, Claus Heinrich, Bill McDermott, 
Gerhard Oswald, John Schwarz, Jim Hagemann Snabe, Peter Zencke 
Vorsitzender des Aufsichtsrats/Chairperson of the SAP Supervisory Board: Hasso Plattner
Registergericht/Commercial Register Mannheim No HRB 350269