@Beta
public interface GroupNamingConvention

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.

1. shared: something shared across all members of a group, and fully retrievable via api. Ex. security group or network
2. 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 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 # 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 - followed by the group name. The jclouds prefix signifies 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 mycluster, the naming convention for shared resources would produce 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 mycluster, the naming convention for unique resources could produce jclouds-mycluster-f3e the first time, and jclouds-mycluster-e64 the next.

note

It is typically safe to assume that an IllegalStateException is thrown when attempting to create a named resource which already exists. However, if you attempt to create a resource with a name generated by GroupNamingConvention, and receive an IllegalStateException, it may have been for another reason besides name conflict.