4.6.2. Создание компонентов приложения

В этом разделе описаны рекомендации по созданию компонентов приложения с целью повторного использования.

Правила именования
  1. Имя корневого пакета должно следовать нотации reverse-DNS, например, com.jupiter.amazingsearch.

    Имя корневого пакета не должно начинаться с имени любого другого компонента или приложения. К примеру, если корневой пакет вашего приложения com.jupiter.tickets, вы НЕ можете использовать пакет com.jupiter.tickets.amazingsearch для компонента. Это обусловлено тем, что Spring сканирует classpath бинов, начиная с указанного корневого пакета, и это сканирование должно быть уникальным для всех компонентов.

  2. Пространство имён используется в качестве префикса таблиц в базе данных, поэтому для публичных компонентов оно должно быть составным, к примеру, jptams, а не просто search. Это минимизирует риск совпадения имён между компонентов и конечным приложением. В пространстве имён запрещено использовать нижние подчёркивания и дефисы, только буквы и цифры.

  3. Значение Module prefix должно повторять пространство имён, но может при этом содержать дефисы, например, jpt-amsearch.

  4. Используйте namespace в качестве префикса имён бинов и свойств приложения, например:

    @Component("jptams_Finder")
    @Property("jptams.ignoreCase")
Установка в локальный Maven-репозиторий

Чтобы сделать компонент доступным для использования в проектах, расположенных на том же компьютере, установите его в локальный репозиторий Maven, выполнив команду Run > Install app component в меню Studio. Данная команда просто запускает задачу Gradle install после остановки демонов Gradle.

Загрузка в удалённый Maven-репозиторий
  1. Создайте репозиторий, следуя инструкции в разделе Установка приватного репозитория артефактов.

  2. Укажите репозиторий и данные для входа в настройках вашего проекта вместо стандартного репозитория CUBA.

  3. Откройте файл build.gradle проекта компонента на редактирование и добавьте секцию uploadRepository в секцию cuba:

    cuba {
        //...
        // repository for uploading your artifacts
        uploadRepository {
            url = 'http://repo.company.com/nexus/content/repositories/snapshots'
            user = 'admin'
            password = 'admin123'
        }
    }
  4. Откройте проект компонента в Studio.

  5. В диалоге Search (Alt-/) найдите задачу Gradle uploadArchives и выполните её. Вы также можете выполнить эту задачу из командной строки. Артефакты компонента будут загружены в ваш репозиторий.

  6. Удалите артефакты проекта из локального Maven-репозитория, чтобы убедиться, что они будут загружены из удалённого репозитория при следующей сборке проекта приложения. Для этого просто удалите папку .m2/repository/com/company из домашнего каталога пользователя.

  7. Теперь при сборке и запуске приложения, использующего этот компонент, он будет скачиваться из удалённого репозитория.

Загрузка в Bintray
  1. Зарегистрируйтесь на https://bintray.com/signup/oss

    Tip

    Для входа на Bintray можно использовать social login (через GitHub, Gmail или Twitter), однако позже вам потребуется выполнить сброс пароля, так как для получения API-ключа (см.ниже) понадобится пароль от учетной записи.

  2. Запомните своё имя пользователя Bintray. Его можно взять из URL, который открывается после логина на Bintray. К примеру, в https://bintray.com/vividphoenix именем пользователя будет vividphoenix.

  3. Получите свой API key. Его можно найти через интерфейс Bintray в настройках профиля. В разделе API-key вам потребуется ввести пароль от учетной записи, чтобы ключ высветился. Используйте ключ и имя пользователя для авторизации с помощью плагина:

    • Вы можете создать для авторизации переменные окружения:

      BINTRAY_USER=your_bintray_user
      BINTRAY_API_KEY=9696c1cb90752357ded8fdf20eb3fa921bf9dbbb
    • Вместо переменных окружения можно использовать эти параметры в явном виде в файле build.gradle:

      bintray {
      user = 'bintray_user'
      key = 'bintray_api_key'
      ...
      }
    • Как вариант, можно передать параметры доступа Bintray в командной строке:

      ./gradlew clean assemble bintrayUpload -Pcuba.artifact.version=1.0.0 -PbintrayUser=your_bintray_user -PbintrayApiKey=9696c1cb90752357ded8fdf20eb3fa921bf9dbbb
  4. Создайте публичный репозиторий с типом Maven. При создании open source (OSS) репозитория обязательно нужно указать тип лицензии.

    Структура Bintray предполагает использование пакетов (packages) внутри репозиториев. На данном этапе создавать пакет необязательно, так как он будет создан автоматически в ходе задания gradle bintrayUpload.

  5. Добавьте зависимость для плагина загрузки Bintray в файл build.gradle:

    buildscript {
        // ...
        dependencies {
            classpath "com.haulmont.gradle:cuba-plugin:$cubaVersion"
            // Bintray upload plugin
            classpath "com.jfrog.bintray.gradle:gradle-bintray-plugin:1.8.0"
        }
    }
  6. В конце скрипта build.gradle укажите настройки для плагина Bintray:

    /** * If you have a multi-project build, make sure to apply the plugin and the plugin configuration to every project which artifacts you want to publish to Bintray. */
    subprojects {
        apply plugin: 'com.jfrog.bintray'
    
        bintray {
            user = project.hasProperty('bintrayUser') ? project.property('bintrayUser') : System.getenv('BINTRAY_USER')
            key = project.hasProperty('bintrayApiKey') ? project.property('bintrayApiKey') : System.getenv('BINTRAY_API_KEY')
    
            configurations = ['archives']
    
            // make files public ?
            publish = true
            // override existing artifacts?
            override = false
    
            // metadata
            pkg {
                repo = 'main'           // your repository name
                name = 'amazingsearch'  // package name - it will be created upon upload
                desc = 'AmasingSearch'  // optional package description
    
                // organization name, if your repository is created inside an organization.
                // remove this parameter if you don't have an organization
                userOrg = 'jupiter-org'
    
                websiteUrl = 'https://github.com/jupiter/amazing-search'
                issueTrackerUrl = 'https://github.com/jupiter/amazing-search/issues'
                vcsUrl = 'https://github.com/jupiter/amazing-search.git' // mandatory for Open Source projects
    
                licenses = ["Apache-2.0"]
                labels = ['cuba-platform', 'opensource']
    
                //githubRepo = 'amazingsearch/cuba-platform' // optional Github repository
                //githubReleaseNotesFile = 'README.md' // optional Github readme file
            }
        }
    }
    • здесь, pkg:repo - ваш репозиторий (используйте main),

    • pkg:name - имя пакета (используйте ваше уникальное имя, например, amazingsearch),

    • pkg:desc - необязательное описание пакета, которое будет отображаться в интерфейсе Bintray,

    • pkg:userOrg - имя организации, к которой должен относиться репозиторий (если не задано, по умолчанию будет использоваться значение BINTRAY_USER).

  7. Теперь вы можете собрать и загрузить проект, используя следующую команду:

    ./gradlew clean assemble bintrayUpload -Pcuba.artifact.version=1.0.0
  8. Если вы публикуете аддон в маркетплейс CUBA, его репозиторий будет привязан к стандартным репозиториям CUBA, и пользователям не придётся дополнительно настраивать репозитории в своих проектах.