User Tools

Groups refactoring (July 2019)


Why refactoring groups ?

The Capsis group system was already refactored several times, but it had still little things to be clarified. In particular, declaring groups for a new module implied to change the Group class to declared what kind of elements could be grouped, how to access them and their types.

The new Group framework

Several interfaces and classes were introduced to clarify the framework.

Scene level / group type / groupable element

Any subclass of GScene may contain elements to be grouped. If so, it must implement the PossiblyGroupableScene interface, and answer true on isGroupable (). The elements must implement GroupableElement.

It then must return the available groupable types on getGroupableTypes (), returns instances of GroupableType, i.e. the type of elements which can be grouped. The type is no more a String but now an instance of GroupableType, with a key (must be unique within the group system) and a translation of the key for the two main languages of Capsis: french and english. The translated key is the name, will be returned on GroupableType.getName (), using the Capsis Translator.

E.g. TreeList.GROUP_ALIVE_TREE → Alive trees / Arbres vivants

The getGroupableElements (type) must return the elements candidate for grouping matching the given type, all instances of GroupableElement.

The Group class

All the group framework relies on the Group class to explore scenes to find groupable types and groupable elements. The group class now uses redirections to the given scene in all its methods. Thus it may be tuned once for all, without needing updates each time group types are added.

E.g. the static method isGroupable(GScene scene) in Group redirects on scene.isGroupable ().

Helper implementations

The major types were Group.TREE, Group.CELL, several types for Fish, Reach and Weir in the fish modules, and a Management unit type for the mustard model.

The two first are now GroupableTypes in the TreeList class: TreeList.GROUP_ALIVE_TREE and TreeList.GROUP_PLOT_CELL. The latter is for subclasses of TreeListCell, i.e. SquareCells and PolygonalCells in PlotOfCells instances (reminder: the plot is connected to the GScene by getPlot ()).

For the fish related groups, a helper class was added: FishGroupHelper, to ease the implementation in bidasoa, dynet, guppies, kergelen, mediterranea, runaway and ibasam. The new GroupableTypes are FishGroupHelper.GROUP_FISH, FishGroupHelper.GROUP_REACH and FishGroupHelper.GROUP_WEIR. Implementations of getGroupableTypes () and getGroupableElements () are provided, compatible with all these modules.

The mustard module provides MustForest.GROUP_MANAGEMENT_UNIT (MustForest is the GScene immplementation).

documentation/groupsrefactoring.txt · Last modified: 2019/07/22 17:07 by coligny