cuba-platform/documentation

CUBA Platform Documentation

documentation's Issues

How to use MySQL with UTF-8

Check connectionParams:

?useUnicode=true&characterEncoding=UTF-8

Nginx proxy configuration

See also: http://stackoverflow.com/questions/43003625/cuba-on-tomcat-proxied-by-nginx/43016283?noredirect=1#comment73219918_43016283
Do not forget UberJAR options with X-Forwarded-For HTTP header

Thread safety of Configuration Interfaces

Configuration interfaces may be used as middleware beans' attributes, for example:

class MyBean {

    protected  MyConfiguration myConfig;

    @PostConstruct
    public void init() {
        myConfig = configuration.getConfig(MyConfiguration.class);
    }

    public void doSomething() {
        if (myConfig.isSomePropertyEnabled()) {
            ....
        }
    }
}

Thus,

• ConfigPersisterImpl is thead-safe,
• Server implementation does not cache values, so it always read the newest values from ConfigStorage.

Combine the 'Creating a service' and 'Using a service' chapters into one

Now it is not clear that after the service creation user should add some information about this service to the web-spring.xml file

https://doc.cuba-platform.com/manual-6.6/service_creation.html
https://doc.cuba-platform.com/manual-6.6/service_import.html

Production settings

Relates to
See also

Document the recommended production settings:

• Tomcat (local.app.properties etc),
• production mode ON for vaadin in web.xml
• production mode ON for REST API
• unset auto-filled default login and password
• (optional) if app is running under nginx, the correct version of proxy http and certain headers should be set, otherwise, websockets will not start up, and vaadin will fall into long polling (this can be detected in JS console)

The real question from a client: We want to deploy the portal app on a separate tomcat instance on a different physical server. What config needs to be set for it to know the location of the core app?

How to provide DB settings using CLI params for UberJAR and Docker deployment

See also: https://www.cuba-platform.com/support/topic/deploying-a-base-container-image-to-multiple-instances-with-unique-database-connection
Relates to

Group Appendix B: Application Properties page content

It is very hard now to find some app property if you don't know its FQN.
The suggestion is to group properties and add menu items (links to anchors - group headers)

Deployment and reports: Libreoffice not found

Describe LibreOffice setup for Yarg reporting on Ubuntu
https://www.cuba-platform.com/discuss/t/deployment-and-reports-libreoffice-not-found/2933

NEW prefix in Screen Links mechanism

See https://www.cuba-platform.com/support/topic/screen-link-which-is-ready-to-create-record

How to replace Service implementation completely

Without inheritance from base service from app component

At the moment, we have to annotate new service implementation with @service annotation and exclude this class from component-scan:

<context:component-scan base-package="com.haulmont.cuba">
    <context:exclude-filter type="regex" expression="com\.haulmont\.cuba\.web\.sys\.CustomMyServiceBean"/>
</context:component-scan>

How to customize validation notification in Window

Relates to
At the moment, it is implemented in com.haulmont.cuba.web.gui.WebWindow#showValidationErrors and cannot be changed.

See: https://www.cuba-platform.com/support/topic/how-to-change-the-position-of-error-alert

New configuration property: cuba.gui.validationNotificationType
Default value: TRAY

Valid value: one of com.haulmont.cuba.gui.components.Frame.NotificationType (TRAY, TRAY_HTML, HUMANIZED, HUMANIZED_HTML, WARNING, WARNING_HTML, ERROR, ERROR_HTML)

You can override default behaviour for concrete Window/Frame in showValidationErrors() method:

    @Override
    public void showValidationErrors(ValidationErrors errors) {
        super.showValidationErrors(errors);
    }

How to extend an existing visual component

See for example: https://www.cuba-platform.com/support/topic/date-custom-datatype#comment-6402

Row-level security support in REST API

New section: migration recommendations

write about clean Tomcat, full reassembling, etc

Platform documentation switches to the mobile view on a Desktop PC

Examples in Client-Level Exception Handlers section: do not use system handlers

Time Frame description for cron scheduling type

Time frame – if Start date is specified, Time frame defines the time window in seconds, during which the task will be launched after startDate + period * N time expires. If Time frame is not specified explicitly, it is equal to period / 2.
If Start date is not specified, Time frame is ignored, i.e. the task will be launched at any time after Period since the previous execution of the task expires.

Describe also cron scheduling with time frame

Add link to documentation home page from each manual

cuba.numberIdCacheSize application property description

entityManager.find() and loadContext.find() behavior if view is not defined

Describe which view will be used if not set explicitly

saveSettings / applySettings usage examples

Add examples of using screen settings (saveSettings() / applySettings()), e.g. CreditCardTransactionBrowser screen controller.

How to override message for concrete Entity and operation in case of RowLevelSecurityException

Confluence
See example in com.haulmont.cuba.gui.exception.UniqueConstraintViolationHandler
RowLevelSecurityExceptionHandler_draft.txt

Fix integration test examples

https://doc.cuba-platform.com/manual-6.6/integration_tests_mw.html

1. Get rid of:

• new Customer() - creation of entities with new is dangerous and we show warning inspection in Idea
• new ArrayList<>(Arrays.asList( - verbose, use simple Arrays.asList(

2. There is no example of test-app.properties file, usually it contains important options:

cuba.confDir=${user.dir}/test-home/cuba/conf
cuba.logDir=${user.dir}/test-home/cuba/logs
cuba.tempDir=${user.dir}/test-home/cuba/temp
cuba.dataDir=${user.dir}/test-home/cuba/work

3. Specify full package name for sales-app.properties, test-app.properties, since new projects always have app.properties files inside of root package

Details of working with in-memory constraints

See comments in https://confluence.haulmont.com/pages/viewpage.action?spaceKey=PLAT&title=Brand+new+row+level+security

JS Slider does not set values to state on `valueChanged` from Client

https://doc.cuba-platform.com/manual-6.6/js_library_sample.html

SliderServerComponent should have the following constructor:

    public SliderServerComponent() {
        addFunction("valueChanged", arguments -> {
            JsonArray array = arguments.getArray(0);
            double[] values = new double[2];
            values[0] = array.getNumber(0);
            values[1] = array.getNumber(1);

            getState(false).values = values;

            listener.valueChanged(values);
        });
    }

Also we have to override the following method:

    @Override
    protected SliderState getState(boolean markAsDirty) {
        return (SliderState) super.getState(markAsDirty);
    }

Warn about custom servlets in single WAR

Entity states and em.merge

All newbie developers and many experienced ones don't understand the meaning of managed entity state and purpose of em.merge. For them em.merge call is "save entity changes to DB", like em.save().
Existing documentation pages (1, 2) are not enough. Too brief, people just don't get the sense without real code.

TODO: add examples, recommended scenarios, explanations of side effects.

What can be added:

• explanation of what exactly em.merge is doing under the hood. Side effects: optimistic lock checking. When we need to use em.merge and when we don't need it. Code example of justified em.merge usage.
• code example of em.reload usage.
• code example for this sentence:

Any changes of the instance in Managed state will be saved to the database when the transaction that the EntityManager belongs to is committed.

cuba.testMode application property

Test Reporting with LibreOffice integration with preinstalled Tomcat on Linux

https://www.cuba-platform.com/discuss/t/deployment-and-reports-libreoffice-not-found/2933/10

Slow application startup on VPS

Tomcat use blocking secure random generator, to enable non-blocking linux random source add option to bin/setenv.sh:

CATALINA_OPTS="$CATALINA_OPTS -Djava.security.egd=file:/dev/./urandom"

See https://www.digitalocean.com/community/tutorials/how-to-optimize-your-tomcat-installation-on-ubuntu-14-04

Ability to use session parameters in query filter

Relates to

Command line DB updater: option to skip Groovy update scripts

Current workaround, when the app context is started:

 delete from sys_db_changelog where script_name like '%groovy' and create_ts > (now() - interval '1 hour')

Add description to MariaDB support

Relates to

Entity states and possibly detached references in entity listeners

Relates to

See https://www.cuba-platform.com/support/topic/using-related-entity-in-entity-listener

Hot deploy settings

Document how HD works:

• Help -> Hot Deploy settings in Studio
• Help -> Instant Hot deploy setting in Studio
• Run ->Hot deploy conf

If Instant Hot deploy is deactivated, one can run Run ->Hot deploy conf:

• works only for GUI and WEB modules
• limited capabilities (described in https://youtrack.cuba-platform.com/issue/STUDIO-2807)

If Instant Hot deploy is active:

• Help->Instant Hot deploy settings are applied
• files in global module are not hot deployed at all (waiting for the fix)
• changes in services are hot deployed only from implementations, interface changes (in global) cannot be hot deployed
• Groovy beans cannot be hot deployed (ticket)

Help -> Settings, ->Context help

The 'Instant hot deploy' checkbox allows you to turn off hot deploy.
If hot deployment is enabled, Studio dynamically updates the UI of your deployed web application as you apply or save changes to views, screens, messages or the main menu. На самом деле Instant hot deploy работает не только для UI (see above)

Run ->Hot deploy conf

Hot deploy conf runs the deployConf Gradle task which by default copies all sources of the web module into the application server's configuration directory.
The task can be configured in build.gradle if necessary. This command is usually excessive because Studio can instantly deploy changed source files of the web module if the Instant hot deploy for Web Client checkbox in the Screens section is set.

In fact: not only Web module and not all sources.

Instant hot deploy for Web Client checkbox in the Screens section - should be clarified.

UPDATE:

1. What works:
   XML descriptors and screen controllers (including static methods), located in web and gui modules
   Middleware service implementations, located in core module

2. What doesn't work:
   Any classes of the global module, including middleware service interfaces

3. Other UI and middleware classes and beans, including their static methods, hot deployed ONLY IF some class from item 1 has also been changed. The reason for this is that class reloading is started by some signal: for screen controllers it is the screen reopening, for services - Studio generates special trigger file that is recognized by server and used to reload particular service class and all its dependencies.

See also https://www.cuba-platform.com/support/topic/hot-deploy-issue#comment-6654

Deployment on Azure

Pre/post handlers of actions

WildFly Deployment for Linux

See https://www.cuba-platform.ru/support/topic/%D1%80%D0%B0%D0%B7%D0%B2%D0%B5%D1%80%D1%82%D1%8B%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-war-%D0%B2-wildfly-linux

Use asciidoc gradle plugin to build the documentation

This plugin doesn't require Ruby installed on the machine

REST API: notice that POJOs that are used by the service must implement serializable

Fix cuba-folders-pane style name in Application Folders article

.cuba-folders-pane .v-tree-node.emphasized {
  font-weight: bold;
}

See: https://doc.cuba-platform.com/manual-6.8/application_folder.html

It should be .c-folders-pane instead of .cuba-folders-pane

BaseIntIdentityIdEntity

Implement search for mobile version of manual

Rewrite Jespa integration example

Multi-threading considerations for BackgroundTask#run() implementation

Add examples of safe multi-threading.

Problem:
The run() method runs in a separate thread, not in the UI thread. It must be considered in case:

• you need to pass parameters to the task,
• call UI components from the task,
• use changeable variables, also used from UI thread, from the task.

Main rules:

• Changing UI components and datasources state from run() is a bad practice that can result in mystic Vaadin and Swing errors.
• Read and update operations for any changeable state from run() (including datasources, components, and added fields of screen controllers) must be synchronized,
• The best practice for background tasks would be to avoid synchronization at all with the help of Platform means.

These means are:

The task is coded in functional style divided into 3 parts:

1. Prepare task parameters - in UI thread before running the task,
2. run() performing a continuous action in a separate thread. It uses only prepared parameters and prepares some result which serves as a class-task parameter. Multiple results can be wrapped in POJO.
3. The task result is applied to the interface and saved in some cache-fields, performed in done(), handleException(), handleTimeout().

Passing parameters via the task constructor seems to be more type-safe than by getParams().

Example №2:

// Here:
// parameter - String searchString
// result - List<AddressSuggestion>
// state - addresses and components

@Named("searchString")
protected TextField searchStringField;
@Named("addressDs")
private CustomDatasource<GuiSuggestion> addressDs;
@Named("searchProgressBar")
private Label searchProgressBar;

protected List<AddressSuggestion> addresses;
protected BackgroundTaskWrapper<Void, List<AddressSuggestion>> backgroundTaskWrapper = new BackgroundTaskWrapper<>();

protected class AddressSearchTask extends BackgroundTask<Void, List<AddressSuggestion>> {
    private String searchString;

    public AddressSearchTask(String searchString) {
        super(30);
        this.searchString = searchString;
    }

    @Override
    public List<AddressSuggestion> run(TaskLifeCycle<Void> taskLifeCycle) {
        List<AddressSuggestion> matches = addressSearchService.search(searchString);
        return matches;
    }

    @Override
    public void canceled() {
        addresses = Collections.emptyList();
        addressDs.refresh();
        setInSearch(false);
    }

    @Override
    public void done(List<AddressSuggestion> result) {
        addresses = result;
        addressDs.refresh();
        setInSearch(false);
    }
}

protected void setInSearch(boolean inSearch) {
    searchProgressBar.setVisible(inSearch);
}

...
// call
String searchString = searchStringField.getValue();
setInSearch(true);
backgroundTaskWrapper.restart(new AddressSearchTask(searchString));

Example №2

// Пример №2
// Расчёт цены заказа в фоновом потоке
// для сложного объекта-заказа, который редактируется на форме

// Т.к. во время выполнения задачи заказ может изменяться через компоненты редактирования
//  - то нельзя передавать в задачу объект, хранящийся в датасорсе.
//  Перед запуском задачи нужно создать объект-копию заказа, для которого и будет идти расчет

    @Inject
    protected Datasource<Order> orderDs;
    @Inject
    protected ProgressBar progressBar;
    @Inject
    protected Label priceLabel;

    private class PriceCalcTask extends BackgroundTask<Void, Price> {
        private Order orderCopy;

        public PriceCalcTask(Order orderCopy) {
            super(60, frame);
            this.orderCopy = orderCopy;
        }

        @Override
        public Price run(TaskLifeCycle<Void> taskLifeCycle) {
            return priceService.calculatePrice(orderCopy);
        }

        @Override
        public void done(Price result) {
            assignPriceToOrder(orderCopy, result);
            priceLabel.setValue(result.getTotal());
            progressBar.setVisible(false);
        }

        @Override
        public boolean handleException(Exception ex) {
            showNotification("Failed to calculate price", NotificationType.WARNING);
            progressBar.setVisible(false);
            return true;
        }
    }

// вызов
progressBar.setVisible(true);
Order orderClone = deepClone(orderDs.getItem());
priceTaskWrapper.restart(new PriceCalcTask(orderClone));

CUBA_TOMCAT_START_SCRIPT env variable

See https://www.cuba-platform.com/support/topic/javatomact-console-on-mac-os-x#comment-5357

BPM sub-models example

How to create custom DataStore

com.haulmont.cuba.web.auth.RequestContext

Using @Converter

For example:

• Dates stored in integers like 20200110