Element Sets

We saw in the overview page that it is the conjunction of Element Sets with Element Display Styles by Element Bindings which form the building blocks of a Diagram Style - our ultimate goal.

Elements

Before we look at Element Sets, let us first define what we mean by elements. The Eclipse JDT exposes an API which allows the structure of a Java project to be examined programmatically. The structure is a composition of nodes of type IJavaElement. IJavaElements represent everything from projects, through packages, class files, java files import statements etc. In AgileJ StructureViews the only IJavaElements we need for populating a diagram are:

Field
Initializer
Method
Type

For the sake of simplicity, let us call instances of any of these four types elements. An Element Set consists of a number of rules which define a set of instances of elements.

Creating a new Element Set

With the Profile File Editor open, right-click on an empty space in the profile part tree. This will show a popup as above. Select Element Set, and the attributes panel will look as follows:

id: This should be a name for this set.
children ored : Normally the children will be anded. For example, for an element to belong to this set it must satisfy Element Filter X and Element Filter Y. On occasions, it is necessary to specify that an element belongs to this set if it satisfies Element Filter X or Element Filter Y.
stereotype: It can be useful to see on the diagram which Element Set a class belongs to. The value of the stereotype attribute is displayed on the title of the class (if the DisplayStyle so permits).
typeFilter: There are multiple uses for Element Sets. One of those uses is for thinning down the group of classes added to a diagram in one shot. Setting the typeFilter to yes causes this ElementTo be offered as a filter.
description: Where extra clarification is needed as to the purpose an Element Set (and in particular where it is used as a typeFilter), a short description may optionally be entered.

Children of Element Set

The children of an Element Set are called Element Filters. An Element Set is built up from a number of Element Filters which each have a say in which elements belong to their Element Set.

Right-clicking on an Element Set makes a popup menu appear as above. Note that:

You are free to add as many or as few Element Filters as you like to an Element Set.
You can use the same Element Filter type as many times as you like within the definition of an Element Set.
The order in which the Element Filters are added has no effect upon the members of the Element Set.
Each Element Filter acts like a separate rule adding to the definition of the Element Set in which it is declared.
The attributes within an Element Filter are anded.
Each Element Filter has an exclude flag. This inverts the operation of the filter accepting elements which would normally be rejected and vice versa.

Above: composition of an Element Set

Each subtype of Element Filter has the exclude attribute and zero or more attributes of its own as follows:

Depends Upon	Must have a dependence upon one or more elements from another set dependee. An Element Set one or more members of which the candidate element depends upon. Example: Anything which depends upon javax.swing
Fields	Must be a field type. An Element Set to which the type of the field belongs. type is owner. Whether the type of field must be the same as the declaring class. Example: All fields of type java.util.Vector Example: All singleton instances
Initializers	Must be an initializer Example: All static initializers
Methods	Must be a method constructor. Whether the method must be a constructor or not. return type. An Element Set to which the return type must belong. exception type. An Element Set to which one or more of the checked exceptions must belong. parameter name. A pattern to which one or more parameter names must match. parameter type. An Element Set to which the type of one or more of the parameters must belong. body. A string pattern to which the body of the method must match. overrides. Whether the method overrides another method. overridden. Whether the method is overridden by another method. overloaded. Whether the method is overloaded. type is owner. Whether the return type of the method is the same as the declaring type. Example: All constructors Example: All methods which return a 'StatusReport' Example: All methods which throw a java.io.RemoteException Example: All methods which have a parameter named 'event' Example: All methods which contain 'TODO' in the body Example: All methods which override toString() Example: All methods which provide access to a singleton
Modifier	Must be modified by a Java keyword keyword. One of: abstract, final, native, private, protected, public, static, synchronized, transient or volatile. Example: All public members
Name	Must have a name which matches a pattern name pattern. A string pattern to which the name of the element must match. Example: Anything with 'test' in its name
Other Set	Must belong to another set set. An Element Set for making a union or intersection. Example: All classes in Swing or AWT
Owner	Must be owned by an element belonging to another set owner set. An Element Set to which the owner of this element must belong. Example: All members of a class whose name begins with 'Test'
Owns	Must own one or more elements which belong to another set ownee set. An Element Set to which one or more children of this element must belong. Example: All classes which have a 'main' method
ReadOnly	Must be declared in a source file which is read only Example: All classes which are checked out of source control
Tag	Must be annotated with a Javadoc comment matching specific string patterns name pattern. A string pattern to which the name of the tag must match. value pattern. A string pattern to which the value of the tag must match. Example: All deprecated methods Example: Anything whose author is 'Joe'
Types	Must be a class or an interface interface. Whether the element must be an interface or class. super. An Element Set to which any of the supertypes of the type must belong. source code. Whether the source code containing the declaration of the type is available. package pattern. A string pattern to which the package in which the type is declared must match. Example: All interfaces Example: All subtypes of JFrame Example: All implementors of EJBHome Example: All classes for which the source code is not available Example: All classes declared in com.test.*

Checking the Contents of an Element Set

In order to run a test on the definition of an Element Set it is possible to request to see the contents of the Element Set. The contents will vary according to the Java elements available to the JDT at the time of running; in other words, which Java projects you have open in the workbench and which libraries they include. If you have a large number of Java elements available then this operation can take serveral minutes as every member of several thousand types is tested for inclusion in the set. Evenso, it can still be useful as a final check that an Element Set intended for long term use contains the elements you would expect.