Set description language

This XML-based language provides the advanced ability to specify sets of objects in a declarative way. It can be used, for example, to examine memory distribution in automated memory tests.

To see some samples and define your custom sets, please use Settings | Sets of Objects... in the main menu. The sets can be opened via Memory | Predefined Set....

• Tag objects specifies objects of a particular class, or multiple classes.

  Mandatory attribute class specifies the fully qualified class name. Wildcards (*) are also accepted.

  Optional attribute subclasses specifies whether subclasses should be accepted (subclasses="true"), or the class should match exactly (subclasses="false"). Default value is true.

  Example

  <objects class="com.company.MyClass"/> - all instances of the class com.company.MyClass and its subclasses

  <objects class="com.company.MyClass" subclasses="false"/> - all instances of com.company.MyClass but excluding instances of classes derived from com.company.MyClass.

  <objects class="*[]"/> - all arrays

• Tag roots specifies all objects that are GC roots.

  Example

  <roots/>

• Tag and intersects the specified sets and returns all objects that are present in every set. There should be at least 2 nested sets.

  Example

  The specification of all objects of classes that implement both com.company.MyInterfaceA and com.company.MyInterfaceB interfaces:

  <and>
    <objects class="com.company.MyInterfaceA"/>
    <objects class="com.company.MyInterfaceB"/>
  </and>

• Tag or joins the specified sets and returns all objects that are present at least in one of the sets. There should be at least 2 nested sets.

  Example

  The specification of all objects of the class com.company.A and its subclasses, and all objects of the class com.company.B and its subclasses:

  <or>
    <objects class="com.company.A"/>
    <objects class="com.company.B"/>
  </or>

• Tag not specifies all objects that are not present in the specified set. There should be one and only one set specified.

  Example

  The specification of all objects except for the objects of class com.company.A and its subclasses:

  <not>
    <objects class="com.company.A"/>
  </not>

• Tag reachable-objects specifies objects accessible by references from the set specified via mandatory subtag from.

  The result will not include objects other than the ones specified via mandatory subtag object-filter. In terms of graphs, object-filter specifies allowed nodes.

  Mandatory subtag field-filter allows you to search for objects reachable only from particular fields of classes. Restrictions for any number of classes can be specified as class subtags of field-filter:

  <field-filter>
    <class name="com.company.ClassA">
      <allowed field="field1"/>
      ...
      <forbidden field="field2"/>
      ...
    </class>
    <class name="com.company.ClassB">
      ...
    </class>
    ...
  </field-filter>

  For each class, you can specify any number of names (including none) of the allowed and forbidden fields. If at least one allowed tag is specified, only the allowed fields will be allowed for the class. If no allowed fields are specified, any fields except for the forbidden ones will be allowed for the class.

  Any fields of classes not specified in field-filter are acceptable.

  Example

  The following example is a predefined set "Lost UI" (see Settings | Sets of Objects...). It lets you find all AWT/Swing UI controls that are not in the window hierarchy.

  UI controls are instances of java.awt.Component and its subclasses. Class java.awt.Container is a subclass of java.awt.Component and represents controls that contain other controls. To be shown, a control must be contained in windows, represented with objects of the class java.awt.Window with subclasses; java.awt.Window extends java.awt.Container.

  Our goal is to find any UI control (i.e. instance of java.awt.Component) not accessible from the window hierarchy. So we start from the windows (see the from section).

  We know that java.awt.Container stores its children in the field named component which is an array of components. According to this we form the object-filter and field-filter sections. Note that we have to include java.awt.Component[] to the object filter, so that the result of the entire reachable-objects tag includes arrays of components as well as components.

  To complete the task, we use a combination of and and not tags, to retrieve components that are not accessible from the windows in the specified way.

  <and>
    <objects class="java.awt.Component"/>
    <not>
  
      <reachable-objects>
        <from>
          <objects class="java.awt.Window"/>
        </from>
  
        <object-filter>
          <or>
            <objects class="java.awt.Component"/>
            <objects class="java.awt.Component[]"/>
          </or>
        </object-filter>
  
        <field-filter>
          <class name="java.awt.Container">
            <allowed field="component"/>
          </class>
        </field-filter>
      </reachable-objects>
  
    </not>
  </and>

• Tag retained-objects retrieves all objects that will be garbage-collected if all objects of the given set are garbage-collected. The given set is included. In other words, the retained set of set A is A itself plus all the objects accessible from A and only from A. These objects are called the retained set, and its size is called the retained size (see Shallow and retained sizes for more details).

  Example

  The following specifies of all objects that will be garbage collected if all objects of the class com.company.A and its subclasses are garbage collected:

  <retained-objects>
    <objects class="com.company.A"/>
  </retained-objects>

• Tag generation returns objects from specified generations.

  Example

  Objects from generation 3: <generation name="#3:*">

  Objects from all generation(s) with description "foo": <generation name="*: foo">

  All strings from generation #5:

  <and>
    <objects class="java.lang.String"/>
    <generation name="#5:*">
  </and>

• Tags strong-reachable, weak-soft-reachable, pending-finalization, unreachable return all objects of particular reachability scope.

  Example

  All weak or soft reachable strings:

  <and>
    <objects class="java.lang.String"/>
    <weak-soft-reachable/>
  </and>