Skip to content

Toro Cloud Dev Center

Naming conventions

Martini packages

TORO recommends Martini packages to be named using:

  • Nouns
  • Alphanumeric characters
  • Lowercase characters with each word separated with a dash
  • Descriptive yet simple words, indicating the package's purpose

For example:

  • subscription-management-system
  • chatops-sales-team
  • employee-onboarding
  • stock-price-alerts

Invalid names for Martini packages

The PackageManager will not allow a Martini package to have any of the following names due to the possibility of conflicting HTTP request mappings:

  • api (or the value of the property defined in the application properties file)
  • api-explorer
  • app
  • assets
  • broker
  • coder-api
  • document
  • errors
  • esb
  • esbapi
  • esbws
  • favicon.ico
  • flux-api
  • invoker
  • license
  • log
  • logout
  • martini
  • martini-ws
  • notification
  • oauth
  • opensearch
  • properties
  • public
  • reports
  • rest
  • setup
  • soap
  • static
  • statistics
  • store
  • system
  • throttling-monetization
  • tracker

Code directories

Code directories are directories under Martini package code folders, intended to contain service and bean or model files. They work similar to Java packages in that they let developers organize their code and control access1. Code directories in Martini also observe the same naming conventions as Java packages; their names:

  • Can only contain alphanumeric characters
  • Are written in lowercase letters
  • Cannot contain keywords
  • Typically start with the reversed internet domain of the company

Here are a couple of examples:

  • io.toro.oms

    This will be the starting package name. It is based on the reversed internet domain name of the company and the name or identifier of the project, which in this case is oms. oms stands for 'order management system'.

  • io.toro.oms.web.controller

    The package which will contain code used to expose APIs over HTTP such as Spring controllers, ad hoc REST endpoints, and Gloop REST or SOAP APIs.

  • io.toro.oms.order

    The package which will contain order models or beans and services specific to managing orders.

Namespace conflicts

A namespace conflict happens when two packages contain objects with identical namespaces. For example, if you already have a Martini package containing a service with a namespace of io.toro.oms.ViewOrder, creating another service with the same namespace in another Martini package will cause a namespace conflict; and is therefore not allowed.

Namespace conflict

Resolving namespaces

Namespaces are resolved by combining the directories under the code directory with dots (.) and prepending them to the name of the file without its extension. This means that if you have a file structure of:

└── code
    └── io
        └── toro
            └── oms
                └── ViewOrder.gloop

The resulting namespace of ViewOrder.gloop will be io.toro.oms.ViewOrder. Note that the code directory is not included in the namespace.

File organization

How files are organized should depend on the standards set by the developer or company that is using Martini. Once a set of standards have been chosen, it is important to let the pattern be consistent to help make the code easier to locate and maintain.

To start, TORO recommends that models, beans, and services are organized by feature instead of packaging by file type. Here is an example that demonstrates packaging by feature:

├── code
│   └── io.toro
│       ├── account
│       │   └── CreateAccount.gloop
│       │   └── DeleteAccount.gloop
│       │   └── ExportAccount.ffd
│       └── contact
│           └── CreateContact.gloop
│           └── DeleteContact.gloop
│           └── ExportContact.ffd

... as opposed to packaging by file type:

├── code
│   └── io.toro
│       ├── sql
│       │   └── CreateAccount.gloop
│       │   └── CreateContact.gloop
│       │   └── DeleteAccount.gloop
│       │   └── DeleteContact.gloop
│       └── flatfile
│           └── ExportAccount.ffd
│           └── ExportContact.ffd


Gloop files

Like Groovy and Java beans, Gloop models should be named using simple, yet descriptive nouns comprised of alphanumeric characters in PascalCase2.

Below are some sample Gloop model names:

  • Account
  • Order
  • Employee

Services, including SQL services and flat file descriptors, are also named in similar fashion although Verbs can be used in addition to nouns.

Below are some sample service names:

  • UpdateAccount (verb) or AccountUpdatingService (noun)
  • GetRemoteData (verb) or RemoteDataFetchingService (noun)

Gloop properties and variables

Gloop properties and variables should be:

  • Named using nouns comprised of alphanumeric characters
  • Written in camel case, specifically the variant which uses lowercase on the initial character
  • None of the Java, Groovy or Gloop keywords

Property names

Although TORO has established some simple standards for naming Gloop properties, they are generally named to match the required element/property names when the Gloop properties are written as XML and JSON.

For example:

  • url
  • person
  • accountName

Gloop keywords

The following is a list of Gloop keywords which should not be used for naming variables, properties, models, and services:

  1. For Groovy and Java code, access to a class is specified via access modifiers

  2. PascalCase is a variation of camel case, albeit that which writes the first letter in uppercase.