Meet CLI for the 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. Our community is no exception. Therefore, we've been asked frequent questions like "How can I start a project without CUBA Studio?" or "Is there a light-weight, free command-line alternative to CUBA Studio?" So, good news everyone! We are going to explore the answers to those questions in this article. Read on for more!

Does Free CLI Replace Commercial CUBA Studio?

CLI is not seen as an alternative to the CUBA Studio. It has another mission. CLI is useful for developers who are experienced with the 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 the CUBA Platform. Also, it provides the lightweight scaffolding of the main project artifacts, including entities, screens, services, etc.

At the same time, the studio keeps its niche by providing a short track into the CUBA world. It provides an intuitive user interface, where even a newcomer to CUBA can design their first application in minutes without any experience in JPA, 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 having an ultimate comfort in an IDE.

To sum up, CUBA Studio is more about "learning while doing" and can save you a lot of time. CLI is a workhorse that writes the mandatory boilerplate routine for you.

What Can CLI Do?

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 an existing one. By tapping the Tab, you can find all the supported commands listed. Choose or type the help command and it will give you a short overview about every command. Let's look at what these commands do behind the scene and how they save developer's time and make the life of your keyboard longer.

Project Setup and Global Settings

• create-app: This guides you 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: This adds a new client to your application, based on the Polymer library and 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: The 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 CSS 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 a server restart. This part of the documentation provides detailed information on this subject.
• add-component: This plugs an existing application component into your application. It adds a new line into the dependencies block of your build Gradle and modifies theweb.xml of the web module by adding the main package of the application component to the appComponents context parameter.

Domain Modeling

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

Business Logic

• entity-listener: This scaffolds a Spring component and implements the 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: This scaffolds an interface in the global module and its implementation in the core. To be usable from the web module, it gets registered in the  WebRemoteProxyBeanCreator bean definition in  web-spring.xml.
• bean: This simply generates a Spring component and saves time on typing around 150 characters.
• config: This 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

The command scaffolds the 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: This turns your CUBA application to be embeddable (pluggable) into another CUBA application. Find out more information about the concept of application components in this documentation. This command generates the  app-component.xml file that defines the dependencies on other components, describes the existing application modules, generates artifacts, and exposes application properties. While running the command, it will prompt you 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 the  build.gradle files.
• update-script: This creates an SQL update script file, meeting CUBA conventions for its place and name. The CUBA Platform includes the 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: This generates the project files from velocity templates, defined by a developer. Templating mechanism allows you to extend the CLI command set declaratively and without compilation. Find more information about CLI templating engine here.

As you can see, CLI undertakes a large amount of work to protect a developer from a 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, which 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. The 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 cases, feel free to help the community and leave a comment below.

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. 

By starting your first CUBA project, it might happen that CLI becomes 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. 

Additionally, you can watch the CLI demo video here.