Create Use Case Bundle

A use case bundle is an OSGi bundle containing both the logic as well as all the UI resources to handle a use case within the application. In the Demo application, there are two use cases implemented. The Demonstrate Vaadin Widgets use case and the Application Configuration use case.

A use case bundle plugs technically into the Ripla platform by providing an implementation of the org.ripla.web.services.IUseCase service. The visual entry point of a use case is an entry in the main menu.

The Demo application's main menu displaying the entry points for two use cases.

When the user hovers over the menu entry, the menu's structure is displayed and the user can click an entry in the pulldown menu.

The Ripla platform leverages the model-view-controller (MVC) pattern. Clicking a menu item will call a controller which will eventually return a Vaadin view that is displayed in the applications main window. A view may have a context menu that allows to switch from the actual view to a different view suitable for the use case. Thus, the controller manages not only the view for the main menu, but the context menu too. The visual representation of this context menu is displayed in the sidebar panel.

This behaviour is reflected by the org.ripla.web.services.IUseCase interface:

public interface IUseCase {
    Package getControllerClasses();    
    IControllerSet getControllerSet();    
    IMenuItem getMenu();   
    IMenuSet[] getContextMenus();  
}

The method IUseCase.getControllerClasses() returns the package containing the use case's controller classes. A Ripla controller is a Java class implementing the org.ripla.web.interfaces.IPluggable interface and annotated with the class annotation org.ripla.annotations.UseCaseController. To make use case development easier, controller classes should extend org.ripla.web.controllers.AbstractController which provides basic functionality useful for all controllers. If IUseCase.getControllerClasses() returns a value not null, the application scans the whole package returned for controller classes and registers them at the application's controller manager. An alternative approach is provided by the IUseCase.getControllerSet() method. In this case, the use case implementer has to specify the controller classes in the org.ripla.interfaces.IControllerSet returned.

The method IUseCase.getMenu() returns the composite defining the use case's menu for the application's menu bar.

The method IUseCase.getContextMenus() returns an array containing org.ripla.web.interfaces.IMenuSet instances. Each of these instances is identified by a set ID and contains a list of context menu items (org.ripla.web.interfaces.IContextMenuItem). If a controller wants to display a context menu (i.e. a set of context menu items), the only thing it has to do is to call the set with its set ID.

This description suggest the following steps to create a use case bundle for a Ripla application:

1. Implement the use case service provider class, i.e. the class implementing the org.ripla.web.services.IUseCase interface.
2. Write the OSGi component description for that the OSGi container running the application can register the bundle as OSGi declarative service at the service registry.
3. Implement the use case controller classes by writing Java classes extending org.ripla.web.controllers.AbstractController annotated with @UseCaseController.
4. Implement the view components the controllers return. A view class is a Vaadin component (com.vaadin.ui.Component), usually it extends com.vaadin.ui.CustomComponent.
5. Implement the use case's menu entry and menu structure for the application's main menu bar.
6. Implement the set of context menus useful for the use case.