Recommendations on developing add-ons

[krivopustov (Konstantin Krivopustov)]

UPDATE: this information is also available in the docs, see Creating Application Components.

Naming Rules

1. Choose the root package using the standard reverse-DNS notation, e.g. com.jupiter.amazingsearch

2. Root package should not begin with a root package of any other add-on or application. For example, if you have an application with com.jupiter.tickets root package, you cannot use com.jupiter.tickets.amazingsearch package for an add-on. The reason is that Spring scans the classpath for the beans starting from the specified root package, and this scanning space must be unique for each component.

3. Namespace is used as a prefix for DB tables, so for a public add-on it should be composite, like jptams, not just search. It will minimize the risk of name collisions in the target application. You cannot use underscores and dashes in namespace, only letters and digits.

4. Module prefix should repeat namespace, but can contain dashes, like jpt-amsearch.

5. Use namespace as a prefix for bean names and application properties, for example:

   • @Component("jptams_Finder")
   • @Property("jptams.ignoreCase")

Deployment

Your add-on binaries should be uploaded to an artifact repository to save the users from building the add-on from sources. Below are our recommendations on uploading to Bintray.

1. Register at Service End for Bintray, JCenter, GoCenter, and ChartCenter | JFrog

2. Get the API key. It can be found in Bintray interface if you edit your profile.

3. Create a public repository of Maven type.

4. In your build.gradle, add the Bintray upload plugin dependency as follows:

   buildscript {
       // ...
       dependencies {
           classpath "com.haulmont.gradle:cuba-plugin:$cubaVersion"
           // Bintray upload plugin
           classpath "com.jfrog.bintray.gradle:gradle-bintray-plugin:1.8.0"
       }
   }
   

5. At the end of build.gradle, add the Bintray plugin settings:

   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
               
               // 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']
           }
       }
   }
   
   

6. Create environment variables with Bintray credentials:

   BINTRAY_USER=your_bintray_user
   BINTRAY_API_KEY=9696c1cb90752357ded8fdf20eb3fa921bf9dbbb
   

7. Now you can build and upload the project with the following command:

   ./gradlew clean assemble bintrayUpload -Pcuba.artifact.version=1.0.0
   

   Alternatively, you can provide Binrtray credentials in the command line:

   ./gradlew clean assemble bintrayUpload -Pcuba.artifact.version=1.0.0 -PbintrayUser=your_bintray_user -PbintrayApiKey=9696c1cb90752357ded8fdf20eb3fa921bf9dbbb
   

8. If you publish the add-on on the CUBA Marketplace, its repository will be linked to the standard CUBA repositories and users won’t have to specify your repository in their build.gradle files.

[artamonov (Yuriy Artamonov)]

Recently, we have released plugin for CUBA CLI (1.0.2+) that simplifies publication of add-ons to Bintray.

See Github: GitHub - cuba-platform/cli-bintray-publisher: Plugin for CUBA CLI that configures CUBA Platform add-on project for publishing in Bintray
Downloads: Service End for Bintray, JCenter, GoCenter, and ChartCenter | JFrog