Package org.jclouds.compute.functions

Interface GroupNamingConvention

  • All Known Implementing Classes:
    FormatSharedNamesAndAppendUniqueStringToThoseWhichRepeat
    @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.

    • Method Detail

      • sharedNameForGroup

        String sharedNameForGroup​(String group)
        encodes the {code group parameter} into a name that exists only once in the group.

      • uniqueNameForGroup

        String uniqueNameForGroup​(String group)
        encodes the {code group parameter} into a name that exists more than once in the group.

        note

        Do not expect this name to be guaranteed unique, though a good implementation should guess a unique name in one or two tries.

      • groupInUniqueNameOrNull

        @Nullable
String groupInUniqueNameOrNull​(String encoded)
        retrieve the group associated with the encoded name

      • groupInSharedNameOrNull

        @Nullable
String groupInSharedNameOrNull​(String encoded)
        retrieve the group associated with the encoded name

      • containsGroup

        com.google.common.base.Predicate<String> containsGroup​(String group)
        A predicate that identifies if an input has the given group encoded in it.

      • containsAnyGroup

        com.google.common.base.Predicate<String> containsAnyGroup()
        A predicate that identifies if an input has any group encoded in it.

      • extractGroup

        String extractGroup​(String encoded)
        Extracts the group from a shared/unique name. Or returns null if not in correct format to contain a group.