y2partitioner_namespaces.md

The Y2Partitioner namespaces

About this document

The code organization of the Partitioner may not be obvious, specially since some of the original ideas and design goals had not always being followed for different reasons. This document tries to explain what the original idea was, no matter how closely the ideas has been followed or whether we plan to stick to them.

The general idea

Although CWM somehow encourages having quite some business logic in the view layer (every so-called "widget" is potentially a full-featured component able to fetch and process the related information, to perform complex validations and to communicate with other widgets/components), one of the design goals of the Partitioner was to have as little business logic as possible in the dialogs and widgets.

In other words, the goal was to keep the view layer as "dumb" as possible, so the #validate, #init or #store methods of some widget here or there does not contain the logic about things like how to process subvolumes when a new Btrfs file-system is created or which devices can be selected to create a new LVM or whether deleting a given device is allowed or not under some circumstances.

The Y2Storage::Actions namespace

The way of keeping the widgets and dialogs clean from that partitioner-specific business logic was encapsulating such logic in one class per every action allowed by the Partitioner. As said, the actions should contain only partitioner-specific business logic. The more general logic that applies to all possible uses of the devices (like calculating subvolumes shadowing or performing extra steps that are needed when creating a file-system of a particular type) should be implemented directly in the Y2Storage classes, to ensure consistency in how the devices are used in the Partitioner, the Guided Setup, AutoYaST or any other YaST component.

Every action class implements a method #run that returns a symbol:

• :back means the action was not performed. Either because it's not possible or because the user regreted during the process. In the first case, is expected that the action notifies the reason to the user (via a pop-up) if needed as part of #run, before returning the symbol.
• :finish means the action has been completed and the interface needs to be redrawn to reflect any change performed by the action in the current devicegraph.
• :quit tell the Partitioner to terminate.

Many actions do not need extra information from the user, so they don't need to implement any UI except a pop-up to ask for confirmation or to notify why the action cannot be performed. This is specially true for delete operations.

But in some cases, the action needs to open a dialog to ask the user some parameters that are needed to perform the operation. In those cases, it's expected that the corresponding business logic, like calculating the possible values to be offered to the user or making the user selection effective in the current devicegraph, resides in the action class, with the dialog (and its widgets) being basically a thin presentation layer.

A good example of that is the current (at the moment of writing) Actions::CreatePartitionTable and its relationship with the corresponding (pretty simple and dumb) dialog Dialogs::PartitionTableType.

Sequences and the Actions::Controllers namespace

Some Partitioner actions can get quite complicated and take several UI steps in a wizard before they can be completed. In those cases, the action object does not only have to hold the business logic, but it also has to control the execution flow. That is, deciding which steps are presented in which order, passing the information from one step to another and, in short, coordinating the whole sequence of dialogs.

That's how we ended up breaking those actions into two pieces. On one hand, the action object which in this case is limited to basically control the sequence of steps and return one of the symbols explained above when the sequence is over (succesfully, aborted or simply not started). On the other hand, a controller object (nothing to do with the role of a controller in the MVC pattern) which contains the business logic and stores the intermediate result and the information introduced by the user in previous steps of the sequence.

So only action objects that represent wizards (a.k.a. sequences) rely on some corresponding classes in the Y2Partitioner::Actions::Controllers. Note there is not always a 1:1 relationship between classes in the Actions and the Controllers namespaces. In some cases, the same controller class is used by several action classes. On the other hand, some complex and long wizards use more than one controller class.

The base class Actions::TransactionWizard

Due to the nature of libstorage-ng, some business logic that lives in the Y2Storage namespace can only be used when some devices have been already created and deleted in the devicegraph. For example, to know if an MD RAID is valid or to calculate its size, the MD device must be already created in the devicegraph with a chosen name/number and the corresponding partitions/disks must have been already associated to the RAID. In order to do so, all the previous devices (like file-systems or LVMs) depending on those partitions/disks must be deleted. A pretty aggressive set of actions to be performed on the current devicegraph just to be able to visualize a temptative size or to move some devices in a temporary list.

To handle those cases, an action can be implemented as a subclass of Actions::TransanctionWizard. That base class contains logic to take a snapshot of the current devicegraph when the action is starting, rolling back any change if the action is not completed successfully.

Several complex wizards are subclasses of TransactionWizard and rely on one or several controller objects (the would work directly on the current devicegraph, not knowing they are part of an atomic transaction). But in general, the usage of controllers or transactions is not needed, so such mechanisms should only be added to an action when there is a real need.