Table of Contents

Preface

1. Introduction

1.1. Overview

1.2. Technical Requirements

1.3. Release Notes

2. Installation and Setup

2.1. CUBA Studio Installation

2.2. IDE Integration

3. Quick Start

3.1. Application Details

3.2. Creating a Project

3.3. Creating Entities

3.4. Creating Database Tables

3.5. Creating User Interface Screens

3.5.1. Screens for Customer

3.5.2. Order Screens

3.5.3. Application Menu

3.5.4. Customer Editor With a List of Orders

3.6. Running the Application

4. The Framework

4.1. Architecture

4.1.1. Application Tiers and Blocks

4.1.2. Application Modules

4.1.3. Base Projects

4.1.4. Application Structure

4.2. Common Components

4.2.1. Data Model

4.2.1.1. Base Entity Classes

4.2.1.2. Entity Annotations

4.2.1.2.1. Class Annotations

4.2.1.2.2. Attribute Annotations

4.2.1.3. Enum Attributes

4.2.1.4. Soft Deletion

4.2.1.4.1. Use of Soft Deletion

4.2.1.4.2. Related Entities Processing Policy

4.2.1.4.3. Unique Restrictions at Database Level

4.2.2. Metadata Framework

4.2.2.1. Metadata Interfaces

4.2.2.2. Metadata Building

4.2.2.3. Datatype

4.2.2.3.1. Example of Data Formatting in UI

4.2.2.3.2. Examples of Date and Number Formatting in the Application Code

4.2.2.3.3. Example of a Custom Datatype

4.2.2.4. Meta-Annotations

4.2.3. Views

4.2.3.1. Views Creation

4.2.4. Managed Beans

4.2.4.1. Creating a Bean

4.2.4.2. Using the Bean

4.2.5. JMX Beans

4.2.5.1. Creating a JMX Bean

4.2.5.2. The Platform JMX Beans

4.2.5.2.1. CachingFacadeMBean

4.2.5.2.2. ConfigStorageMBean

4.2.5.2.3. EmailerMBean

4.2.5.2.4. PersistenceManagerMBean

4.2.5.2.5. ScriptingManagerMBean

4.2.5.2.6. ServerInfoMBean

4.2.6. Infrastructure Interfaces

4.2.6.1. Configuration

4.2.6.2. Messages

4.2.6.2.1. MessageTools

4.2.6.3. Metadata

4.2.6.3.1. MetadataTools

4.2.6.4. Resources

4.2.6.5. Scripting

4.2.6.6. Security

4.2.6.7. TimeSource

4.2.6.8. UserSessionSource

4.2.6.9. UuidSource

4.2.6.10. DataManager

4.2.6.10.1. Queries with distinct

4.2.6.10.2. Sequential Queries

4.2.7. AppContext

4.2.8. Application Properties

4.2.8.1. Access to Properties

4.2.8.2. Storing Properties in Files

4.2.8.3. Storing Properties in the Database

4.2.8.4. Configuration Interfaces

4.2.8.4.1. Using Configuration Interfaces

4.2.8.4.2. Property Types

4.2.8.4.3. Default Values

4.2.9. Messages Localization

4.2.9.1. Message Packs

4.2.9.2. Main Message Pack

4.2.9.3. Entity and Attributes Names Localization

4.2.9.4. Enum Localization

4.2.10. User Authentication

4.2.10.1. UserSession

4.2.10.2. Login

4.2.10.3. SecurityContext

4.2.11. Exceptions Handling

4.2.11.1. Exception Classes

4.2.11.2. Passing Middleware Exceptions

4.2.11.3. Client-Level Exception Handlers

4.3. Database Components

4.3.1. DBMS Types

4.3.1.1. Support for Other DBMSs

4.3.1.2. DBMS Version

4.3.2. Scripts to Create and Update the Database

4.3.2.1. The Structure of SQL Scripts

4.3.2.2. The Structure of Groovy scripts

4.3.3. The Execution of Database Scripts by Gradle Tasks

4.3.4. The Execution of Database Scripts by the Server

4.4. Middleware Components

4.4.1. Services

4.4.1.1. Creating a Service

4.4.1.2. Using the Service

4.4.1.3. DataService

4.4.2. System Authentication

4.4.3. The Persistence Interface

4.4.3.1. PersistenceTools

4.4.3.2. PersistenceHelper

4.4.3.3. DbTypeConverter

4.4.4. ORM Layer

4.4.4.1. EntityManager

4.4.4.2. Entity States

4.4.4.3. Lazy Loading

4.4.4.4. Executing JPQL Queries

4.4.4.4.1. Case-Insensitive Substring Search

4.4.4.4.2. Macros in JPQL

4.4.4.5. Running SQL Queries

4.4.4.6. Entity Listeners

4.4.5. Transaction Management

4.4.5.1. Programmatic Transaction Management

4.4.5.2. Declarative Transaction Management

4.4.5.3. Examples of Transactions Interaction

4.4.5.4. Transaction Timeout

4.5. Generic User Interface

4.5.1. Screens

4.5.1.1. Screen Types

4.5.1.1.1. Frame

4.5.1.1.2. Simple Screen

4.5.1.1.3. Lookup Screen

4.5.1.1.4. Edit Screen

4.5.1.2. XML-Descriptor

4.5.1.3. Screen Controller

4.5.1.3.1. AbstractFrame

4.5.1.3.2. AbstractWindow

4.5.1.3.3. AbstractLookup

4.5.1.3.4. AbstractEditor

4.5.1.3.5. Controller Dependency Injection

4.5.1.3.6. Controller Companions

4.5.2. Visual Components Library

4.5.2.1. Components

4.5.2.1.1. Button

4.5.2.1.2. Bulk Editor

4.5.2.1.3. CheckBox

4.5.2.1.4. DateField

4.5.2.1.5. Embedded

4.5.2.1.6. FieldGroup

4.5.2.1.7. FileMultiUploadField

4.5.2.1.8. FileUploadField

4.5.2.1.9. Filter

4.5.2.1.9.1. Using a Filter

4.5.2.1.9.2. Filter Component

4.5.2.1.9.3. User Permissions

4.5.2.1.9.4. External Filter Control Parameters

4.5.2.1.9.5. Applying Filters Sequentially

4.5.2.1.10. GroupTable

4.5.2.1.11. Label

4.5.2.1.12. Link

4.5.2.1.13. LinkButton

4.5.2.1.14. LookupField

4.5.2.1.15. LookupPickerField

4.5.2.1.16. MaskedField

4.5.2.1.17. OptionsGroup

4.5.2.1.18. PasswordField

4.5.2.1.19. PickerField

4.5.2.1.20. PopupButton

4.5.2.1.21. ProgressBar

4.5.2.1.22. Related Entities

4.5.2.1.23. RichTextArea

4.5.2.1.24. SearchPickerField

4.5.2.1.25. Table

4.5.2.1.26. TextArea

4.5.2.1.27. TextField

4.5.2.1.28. TimeField

4.5.2.1.29. TokenList

4.5.2.1.30. Tree

4.5.2.1.31. TreeTable

4.5.2.1.32. TwinColumn

4.5.2.2. Containers

4.5.2.2.1. BoxLayout

4.5.2.2.2. ButtonsPanel

4.5.2.2.3. GridLayout

4.5.2.2.4. GroupBoxLayout

4.5.2.2.5. IFrame

4.5.2.2.6. ScrollBoxLayout

4.5.2.2.7. SplitPanel

4.5.2.2.8. TabSheet

4.5.2.3. Miscellaneous

4.5.2.3.1. Formatter

4.5.2.3.2. Presentation

4.5.2.3.3. Timer

4.5.2.3.4. Validator

4.5.2.4. XML-Attributes of Components

4.5.3. Datasources

4.5.3.1. Creating Datasources

4.5.3.1.1. Declarative Creation

4.5.3.1.2. Programmatic Creation

4.5.3.1.3. Proper Implementation Classes

4.5.3.2. CollectionDatasourceImpl Queries

4.5.3.2.1. Returned values

4.5.3.2.2. Query Parameters

4.5.3.2.3. Query Filter

4.5.3.2.4. Case-Insensitive Search for a Substring

4.5.3.3. Data Source Listeners

4.5.3.4. DsContext

4.5.3.5. DataSupplier

4.5.4. Actions. The Action Interface

4.5.4.1. Declarative Creation of Actions

4.5.4.2. Standard Actions

4.5.4.2.1. Standard Actions over Collection

4.5.4.2.1.1. CreateAction

4.5.4.2.1.2. EditAction

4.5.4.2.1.3. RemoveAction

4.5.4.2.1.4. RefreshAction

4.5.4.2.1.5. AddAction

4.5.4.2.1.6. ExcludeAction

4.5.4.2.1.7. ExcelAction

4.5.4.2.2. Standard Actions of the Picker Field

4.5.4.2.2.1. LookupAction

4.5.4.2.2.2. ClearAction

4.5.4.2.2.3. OpenAction

4.5.4.3. BaseAction

4.5.5. Dialogs and Notifications

4.5.5.1. Dialogs

4.5.5.2. Notifications

4.5.6. Background Tasks

4.5.6.1. Using Background Tasks

4.5.6.2. Setting Up Environment

4.5.7. Creating Application Themes

4.5.7.1. Themes in Web Applications

4.5.7.1.1. Using Existing Themes

4.5.7.1.2. Extending an Existing Theme

4.5.7.1.3. Creating a Custom Theme

4.5.7.2. Themes in Desktop Applications

4.5.8. Web Client Specifics

4.5.8.1. Working with Vaadin Components

4.5.8.2. Main Window Layout

4.5.9. Desktop Client Specifics

4.5.9.1. Working with Swing Components

4.5.10. Creating Custom Components

4.5.10.1. Using Third-Party Vaadin Components

4.5.10.2. Integration with Generic UI

4.5.11. Keyboard Shortcuts

4.6. Portal Components

4.6.1. Basic Functionality

4.6.2. REST API

4.6.2.1. Including in a Project

4.6.2.2. Describing Functions

4.6.2.2.1. Login

4.6.2.2.2. Logout

4.6.2.2.3. Loading a Persistent Object Instance From the Database by Identifier

4.6.2.2.4. Executing JPQL Query to Retrieve Data

4.6.2.2.5. Committing New and Modified Instances, Removal

4.6.2.2.6. Uploading Files from Storage

4.6.2.2.7. Obtaining Data Model Description in HTML Format

4.6.2.2.8. Creating New Views on Server

4.6.2.2.9. Service Calls

4.6.2.2.9.1. Service Call by GET Request

4.6.2.2.9.2. Service Call by GET Request

4.6.2.2.9.3. Supported Service Method Parameter Types

4.6.2.2.9.4. Service Call Result

4.7. Platform Features

4.7.1. Scheduled Tasks Execution

4.7.1.1. Spring TaskScheduler

4.7.1.2. CUBA Scheduled Tasks

4.7.1.2.1. Task Registration

4.7.1.2.2. Tasks Handling Control

4.7.1.2.3. Implementation Specifics

4.7.2. Email Sending

4.7.2.1. Sending Methods

4.7.2.2. Email Attachments

4.7.2.3. Configuring Email Sending Parameters

4.7.3. Dynamic Attributes

4.7.3.1. Managing Dynamic Attributes

4.7.3.2. Categorized Entities

4.7.3.3. Dynamic Attributes in REST API

4.7.4. Pessimistic Locking

4.7.4.1. Entity Editing Locks

4.7.4.2. Locking Arbitrary Processes

4.7.4.3. Lock Monitoring

4.7.5. Entity Statistics

4.7.6. Entity Log

4.7.6.1. Setting Up Entity Log

4.7.6.2. Viewing the Entity Log

4.7.7. Entity Snapshots

4.7.7.1. Saving Snapshots

4.7.7.2. Viewing Snapshots

4.7.8. File Storage

4.7.8.1. Uploading Files

4.7.8.2. Downloading Files

4.7.8.3. Standard File Storage Implementation

4.7.9. Sequence Generation

4.7.10. Running SQL Using QueryRunner

4.7.11. Integration with MyBatis

4.7.12. Folders Panel

4.7.12.1. Application Folders

4.7.12.2. Search Folders

4.7.12.3. Record Sets

4.7.13. Screen Links

4.7.14. Entity Inspector

4.7.15. Information about Software Components

4.8. Functionality Extension

4.8.1. Extending an Entity

4.8.2. Extending Screens

4.8.3. Extending Business Logic

5. Application Development

5.1. Recommended Code Style

5.2. Project File Structure

5.3. Build Scripts Overview

5.3.1. The Structure of build.gradle

5.3.2. Starting Build Tasks

5.3.3. Building on a Continuous Integration Server

5.4. Creating a Project

5.5. Designing the Database

5.5.1. Creating the DB Schema

5.5.2. Connecting to HSQLDB with External Tools

5.5.2.1. Connecting with Squirrel SQL

5.5.2.2. Connecting with IntelliJ IDEA Ultimate

5.5.3. PostgreSQL Specifics

5.5.4. MS SQL Server Specifics

5.5.5. Oracle Database Specifics

5.6. Logging

5.6.1. Setting up Logging in Tomcat

5.6.2. Setting up Logging in The Desktop Client

5.7. Debugging and Testing

5.7.1. Connecting a Debugger

5.7.2. Debugging Web Widgets

5.7.3. Testing

5.7.3.1. Unit Tests

5.7.3.2. Middleware Integration Tests

5.7.3.3. Client Tier Integration Tests

5.8. Development Recipes

5.8.1. Getting Localized Messages

5.8.2. Assigning Initial Values

5.8.2.1. Entity Fields Initialization

5.8.2.2. Initialization Using CreateAction

5.8.2.3. Using initNewItem Method

5.8.3. Editing Composite Entities

5.8.3.1. Implementing a Composition

5.8.3.2. Deep Composition

5.8.4. Running Code at Application Start

5.8.5. Loading and Displaying Images

5.8.6. Creating Custom Visual Components

5.8.6.1. Example of Using a Third-party Vaadin Component

5.8.6.2. Example of Integrating a Vaadin Component into the Generic UI

6. Application Deployment

6.1. Application Directories

6.1.1. Configuration Directory

6.1.2. Work Directory

6.1.3. Log Directory

6.1.4. Temporary Directory

6.1.5. Database Scripts Directory

6.2. Deployment Options

6.2.1. Fast Deployment in Tomcat

6.2.1.1. Using Tomcat in Production

6.2.2. Deployment in WAR

6.3. Application Scaling

6.3.1. Setting up a Web Client Cluster

6.3.1.1. Installing and Setting up a Load Balancer

6.3.1.2. Setting up Web Client Servers

6.3.2. Setting up a Middleware Cluster

6.3.2.1. Setting up Connection to the Middleware Cluster

6.3.2.2. Configuring Interaction between Middleware Servers

6.3.3. Server ID

6.4. Using JMX Tools

6.4.1. Built-In JMX Console

6.4.2. Setting up a Remote JMX Connection

6.4.2.1. Tomcat JMX for Windows

6.4.2.2. Tomcat JMX for Linux

6.5. Creating and Updating the Database in Production

6.5.1. Execution of Database Scripts by Server

6.5.2. Initializing and Updating a Database from The Command Line

6.6. License File Usage

7. Security Subsystem

7.1. Security Subsystem Components

7.1.1. Login Screen

7.1.2. Users

7.1.2.1. User Substitution

7.1.2.2. Time Zone

7.1.3. Permissions

7.1.4. Roles

7.1.5. Access Groups

7.1.5.1. Constraints

7.1.5.2. Session Attributes

7.1.6. Integration with LDAP

7.1.6.1. Basic Active Directory Integration

7.1.6.2. Setting Up Authentication Using Jespa

7.1.6.2.1. Including the Library

7.1.6.2.2. Setting Up Configuration

7.2. Access Control Examples

7.2.1. Configuring Roles

7.2.2. Creating Local Administrators

A. Configuration Files

A.1. context.xml

A.2. datatypes.xml

A.3. dispatcher-spring.xml

A.4. menu.xml

A.5. metadata.xml

A.6. permissions.xml

A.7. persistence.xml

A.8. remoting-spring.xml

A.9. screens.xml

A.10. spring.xml

A.11. views.xml

A.12. web.xml

B. Application Properties

C. System Properties

Glossary