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 theapi.rest.base-path
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.
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:
1 2 3 4 5 6 |
|
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:
1 2 3 4 5 6 7 8 9 10 11 |
|
... as opposed to packaging by file type:
1 2 3 4 5 6 7 8 9 10 11 |
|
Gloop
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) orAccountUpdatingService
(noun)GetRemoteData
(verb) orRemoteDataFetchingService
(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:
$gloopIndex
, which is used in iterate and while steps$gloopCount
, which is used in iterate and while steps$gloopIterate
, which is used in break steps$gloopWhile
, which is used in break steps$gloopParent
, which is used in break steps$gloopService
, which is used in break steps$gloopAll
, which is used in break steps$gloopException
, which is used incatch
block steps$gloopOutput
, which is used in invoke steps
-
For Groovy and Java code, access to a class is specified via access modifiers. ↩
-
PascalCase is a variation of camel case, albeit that which writes the first letter in uppercase. ↩