jclouds needs to understand the difference between resources it creates and those supplied by the user. For example, if jclouds creates a security group, it should be able to delete this as a part of cleanup without accidentally deleting resources the user specified manually.
uniqueness of a name
The naming convention must apply to both to resources shared across all members of a group, and those created for a subset of members.
- shared: something shared across all members of a group, and fully retrievable via api. Ex. security group or network
- unique: something that only applies to individuals or subsets of a group, or isn't fully retrievable via api. Ex. node names or keypair names
why repeat?
Some resources we'd otherwise want to share across a group must be redundantly created, if the user has no access to the complete object via api or otherwise. For example, ssh key apis generally do not store the private key data on the server. In order to ensure we can always log into a server without configuration, we may generate a temporary key on-demand for each call to {@link ComputeService#createNodesInGroup}Typically, a security group or network is something shared across all members of a group, so the name should be concise, yet unique.
implementation
Typically, a security group or network is something shared across all members of a group, so the name should be concise, yet unique.
character sets and delimiters
Character sets in apis are often bound to dns names, perhaps also allowing underscores. Since jclouds groups are allowed to be alphanumeric with hyphens (hostname style), care must be taken to implement this in a way that allows the delimiter to be also nested in the group name itself. In other words, we need to be able to encode a group into a name even when they share the same character set. Note that characters like {@code #} can sometimes break apis.As such, you may end preferring always using a hyphen.
shared resources
A good name for a shared resources might include a prefix of jclouds, a delimiter of {@code -} followed by the group name. The jclouds prefixsignifies this resource is safe to delete, and the hash clearly delineates the encoding from what's in the group name.
example
given a jclouds group named {@code mycluster}, the naming convention for shared resources would produce {@code jclouds-mycluster}
unique resources
A good name for a unique resource might be the same as the shared, with a random hex string suffix. A few hex characters can give you 4096 combinations, giving a small degree of collision avoidance, yet without making the resource name difficult.
example
given a jclouds group named {@code mycluster}, the naming convention for unique resources could produce {@code jclouds-mycluster-f3e} the first time,and {@code jclouds-mycluster-e64} the next.
note
It is typically safe to assume that an {@link IllegalStateException} isthrown when attempting to create a named resource which already exists. However, if you attempt to create a resource with a name generated by {@link GroupNamingConvention}, and receive an {@link IllegalStateException}, it may have been for another reason besides name conflict.
@author Adrian Cole