Meet CLI for CUBA Platform

There is no secret, that the world of software developers, especially Java developers, is full of keyboard maniacs who’d better type 10-15 letters over one mouse click. And our community is not an exception, therefore we've been frequently asked questions like "How can I start a project without CUBA Studio?" or "Is there light-weight free command line alternative to CUBA Studio?". So, good news everyone!

Does Free CLI Replace Commercial CUBA Studio?

CLI is not seen as an alternative to CUBA Studio, it has another mission. CLI will be useful for developers who are experienced in Spring Framework, JPA and CUBA infrastructure, and (important!) feel comfortable working in a black window with gray letters. In a nutshell, cuba-cli is a command line utility that enables you to easily create projects based on CUBA Platform. Also, it provides the lightweight scaffolding of the main project artifacts: entities, screens, services, etc.

At the same time Studio keeps its niche providing a short track into CUBA world. It provides an intuitive user interface, where even a newcomer to CUBA can design their first application in minutes, even without any experience in JPA or Spring or any underlying technology… In fact, you don't need to put any line of code to develop a standard CRUD application - the Studio will do it for you. Also the Studio will be a great choice for people who are migrating to CUBA from another ecosystem and for the ones who got used to have an ultimate comfort in an IDE.

To sum up, CUBA Studio is more about "learning while doing" and a huge "time saver", while CLI is a workhorse that writes mandatory boilerplate routine for you.

What CLI Can?

Obviously, you have to install CLI first. It supports major OSes and you can find the installation guide for each one here. After installation just type cuba-cli in your command line, and that's it - we are ready to start a new project or manipulate with an existing one. By tapping Tab you can find all supported commands listed. Choose or type the help command and it will give you a short overview about every command. Let's look what these commands do behind the scene and how they save developer's time and make the lifetime of your keyboard longer:

General Purpose

• help, version, exit, cd - obviously, these commands do not affect your source code and their action is clearly understandable from the names, so let's jump over them :).

Project Setup and Global Settings

• create-app - guides through the required steps to create a new CUBA project: project name, namespace, root package, platform version and a database used in the project. The project will contain global (accessible from both core and web modules), core (server side layer for business logic) and web (server side layer for screen controllers and other GUI logic) modules.
• polymer - adds a new client to your application, based on the Polymer library, developed by Google. It modifies settings.gradle and build.gradle by adding the configuration and tasks for the new module. It also creates files of required image resources and generates login, menu, and other useful web-components for your Polymer front-end application.
• theme - creates a special structure of folders under the modules/web directory, a few images to brand the application (login icon, menu icon and favicon) and a few scss files, where you can modify the default scheme. It also adds the webThemesModule module and its configuration to the settings.gradle and build.gradle files. Finally, this command adds the deployThemes gradle task to be able to see changes without server restart. This part of the documentation provides detailed information on this subject.
• add-component - plugs an existing application component into your application. It adds new line into the dependencies block of your build gradle and modifies web.xml of the web module adding the main package of the application component to the appComponents context parameter.

Domain Modeling

• entity - generates a stub for JPA entity and its DDL script. This entity will be also registered in persistence.xml or metadata.xml, depending on entity type - if it is persistent or not. Finally CLI will generate a message pack to provide localizations for entity attributes.
• enumeration - generates an Enum implementing the EnumClass interface, its fields with localization messages and a useful fromId method.

Business Logic

• entity-listener - scaffolds a Spring component implementing Entity Listeners interfaces and declares it in the corresponding Entity class. Such listeners are hooked when an entity changes its state. You can find more information here.
• service - scaffolds an interface in the global module and its implementation in core. To be usable from the web module it gets registered in the WebRemoteProxyBeanCreator bean definition in web-spring.xml.
• bean - simply generates a Spring component and saves your time on typing around 150 chars :).
• config - scaffolds a stub for a CUBA configuration interface in the specified module with the specified source type (System, DB or App). Find more information about CUBA configuration interfaces in this chapter of the documentation.

User Interface

• screen - scaffolds a GUI screen. The command supports creating:
  • a new empty screen
  • extending an already existing one
  • a browser - a screen with a list of entities, CRUD actions over them and a filter
  • an editor - a screen for creating or editing a single entity.

The command scaffolds xml screen descriptor and its Java controller with its localization message pack. Optionally it can also add a screen to the main menu.

Misc

• app-component - turns your CUBA application to be embeddable (pluggable) into another CUBA application. Find more information about the concept of application components in the documentation. This command generates app-component.xml file, that defines the dependencies on other components, describes the existing application modules, generated artifacts and exposed application properties. While running the command it will prompt to change your current module prefix to a unique one in order to avoid conflicts. If you change the prefix it will also adjust settings.gradle and build.gradle files.
• update-script - creates an SQL update script file, meeting CUBA conventions for its place and name. CUBA Platform includes mechanism of applying update scripts on application start. These scripts should be executed in the historical order, from oldest to newest. To ensure such ordering update scripts should be placed under the modules/core/db/update/{USED DATABASE}/{yy}/ directory and named as {yyMMdd}-{INCREMENT}-{SCRIPT NAME}.sql.
• custom-template - generates project files from velocity templates, defined by a developer. Templating mechanism allows to extend CLI command set declaratively and without compilation. Find more information about CLI templating engine here.

As you see CLI undertakes a large amount of work to protect a developer from boring, but inevitable routine.

Extensibility

First of all, as it was already mentioned, CLI provides a template engine to extend its command set without the need to change the sources and recompile it. CLI templates consist of two parts:

1. template.xml file, that declaratively describes questions to be asked by a custom command.
2. A set of files (xml, java, or any other format) with the Apache Velocity scripts in them, so that they could be processed by the Velocity template engine. Answers to the questions from the template.xml file will be passed as parameters and reachable in the Velocity scripts.

This wiki page provides the detailed information about the CLI templates.

Secondly, CLI provides extension points to load custom plugins and exposes public events which can be used in a custom plugin. Using this mechanism developers can create new commands with maximum flexibility as well as extend existing ones, e.g. add other options for the screen command, like lookup. You can find the documentation and development guide for CLI plugins here.

Finally, CUBA CLI is an open source project and its source code is published on GitHub. CUBA Team would be happy to see your contributions (see the contribution guideline) as well as issues you may face. So, if you see some common, but uncovered use case, feel free to help the community and send us your pull request!

Conclusion

This is just the starting point of our CLI and we hope that it will help you to make the development process slicker and faster, especially if you are not using CUBA Studio. We are going to improve CLI further and already planning the roadmap - here you can see the features we would like to release with the second version.

Concluding the article, I would like also to share a recommendation. Starting your first CUBA project, it might happen that CLI becomes too heavy lifting for the initial evaluation of the platform. CUBA Studio offers a 30-day trial, so, if you or your colleagues are new to the framework it is recommended to use CUBA Studio for the initial stage and interactively discover platform features. Since the trial is over, you can decide if you would like to subscribe and keep using CUBA Studio or move to CLI.

Finally, you can watch the CLI demo video on our youtube channel.

P.S. Oh, yes, almost forgot to tell that CLI is written in Kotlin. This is the first time we are using this language in production - so far so good!