Working with Profiles

This is work in progress

[TODO] Provide links to published javadoc for API/SPI when there is one

---

A Profile is an identifiable set of configuration and resource items that can be applied to a Container.

A Profile has the following properties.

• It is uniquely identified in the fabric
• It has a set of attributes
• It is associated with a Version
• It contains a set of configurations and other files
• It may be associated with a set of Containers
• It may have multiple parent Profiles

Clients can obtain instances of profiles from the ProfileManager.

Managing Profile

The ProfileManager is the central entry point for working with profiles. It contains operations to

• Add, update, remove profiles
• Find profiles by given identifiers

Profile instances returned by the ProfileManager are shallow immutable objects. They represent the state of physical profile at a moment in time.

Effective Profile

From the ProfileManager you can obtain the effective/overlay profile for a given profile. This would be the flat profile representation of a given profile and the transitive tree of its parents. Child items override parent items based on identity.

ProfileManager manager = ProfileManagerLocator.getProfileManager();
Profile effectiveFoo = manager.getOverlayProfile(profile);

Creating a Profile

To create a profile, a client would use a ProfileBuilder and pass the so built Profile to the ProfileManager like this

// Building the profile
Profile profile = ProfileBuilder.Factory.create("foo")
   .addConfiguration("some.pid", Collections.singletonMap("foo", "bar"))
   .getProfile();

// Adding the profile to a version
ProfileManager manager = ProfileManagerLocator.getProfileManager();
profile = manager.createProfile(profile);

Every builder (not just for Profiles) supports the use of OptionsProvider. An OptionsProvider can take its information from an arbitrary source and invoke methods on a builder. This decouples data format from the Fabric8 builders.

Here is an example that builds a profile from JMX composite data.

Profile profile = ProfileBuilder.Factory.create()
   .addOptions(new CompositeDataOptionsProvider(cdata));
   profileBuilder.getProfile();

class CompositeDataOptionsProvider implements OptionsProvider<ProfileBuilder> {

    public ProfileBuilder addBuilderOptions(ProfileBuilder builder) {
        Profile profile = ProfileOpenType.getProfile(cdata);
        builder.identity(profile.getIdentity());
        builder.addAttributes(profile.getAttributes());
        ...
        return builder;
    }
}

Updating a Profile

Profile update uses a copy => modify => publish approach.

1. Obtain a deep copy of the Profile you want to update
2. Use the ProfileBuilder to modify that Profile (possibly including its parents)
3. Publish the updated Profile through the ProfileManager.

Profile updateProfile = ProfileBuilder.Factory.from(profile)
        .addConfiguration("some.pid", Collections.singletonMap("xxx", "zzz"))
        .getProfile();

Profile profile = prfManager.updateProfile(updateProfile);

[TODO] explain the asynchronous nature of updating a profile that is associated with a container and the wanted ability to listen on provisioning events

Removing a Profile

// Removing the profile to a version
ProfileManager manager = ProfileManagerLocator.getProfileManager();
manager.deleteProfile(versionId, profileId, true);

[TODO] Explain what happens when a profile that is associated with an active container is removed.

---

The POC project introduced the notion of profile items for better abstraction of profile content. Currently, profile content is a set of file in a git repository. At runtime it is represented as map of byte array stored in memory. Profile metadata is string encoded information in those byte arrays.