Best practices for using fragments

This topic tells you about the benefits, and design considerations for fragments.

Benefits of using Fragment

A fragment is a partial accelerator. It can do the same transformations as an accelerator, but it cannot run on its own. It’s always part of the calling (host) accelerator.

Developing a fragment is useful in the following situations:

• When you must update a version of an element of a technology stack in multiple locations. For example, when the Java Development Kit (JDK) version must be updated in the build tool configuration, the buildpack configuration, and in the deployment options.
• To add a consistent cross-cutting concern to a set of accelerators. For example, logging, monitoring, or support for a certain type of deployment or framework.
• To add integration with some technology to a generated application skeleton. For example, certain database support, support for a messaging middleware, or integration with an email provider.

Design considerations

Developing and maintaining a fragment is complex. The following is a list of design considerations:

• The fragment you develop must work with all possible syntax and format variations. For example, dependency in a Gradle build.gradle.kts can have the following forms:

  • implementation(‘org.springframework.boot:spring-boot-starter’)
  • implementation("org.springframework.boot:spring-boot-starter")
  • implementation(group = "org.springframework.boot”, name= “spring-boot-starter")
  • implementation(group = ‘org.springframework.boot’, name= ‘spring-boot-starter’)
  • implementation(name= “spring-boot-starter", group = "org.springframework.boot”)

• The fragment can be used in multiple accelerator contexts and its behavior must result in a compilable and deployable application skeleton.

• Testing a fragment in isolation is more difficult than testing an accelerator. Testing takes more time because all the combinations must be tested from an accelerator perspective.

• When flexibly reusing fragments in different combinations, each fragment must cover a small, cohesive function. Fragments must follow these two UNIX principles:

  • Small is beautiful.
  • Each fragment does one thing well.

• Keep the files the fragment changes to a minimum. Only change the files that are related to the same technology stack for the same purpose.

• The design of both the accelerator and fragment is limited by the technology stack and the target deployment technology chosen for the accelerator. For example, to create a fragment for standardizing logging, you must create one fragment per base technology stack.

Housekeeping rules

Fragments are used by accelerator authors. VMware has found that the following guidelines keep fragments understandable and reusable.

• Give fragments an intuitive name and short description that reflects their purpose. Do not include “fragment” in the name.
• Fragments must expose options to allow configuring the output of execution.
• Each fragment must contain a README file explaining the additional functions the fragment adds to a generated application skeleton. List any options expected by this fragment. Also describe how this fragment can be included in a host accelerator. Be sure to state any known limitations or use cases not covered. For example, if the fragment supports Maven and Gradle as build tools but only Groovy DSL of Gradle is supported, the README file must include this information.
• If a fragment must provide additional documentation to end users, it can either be added to a README-X file of the generated application skeleton or append a section to the host’s README.

Versioning

Fragments might require the use of versioning. For example, if accelerator acc-1 imports fragment frag, and accelerator acc-2 also uses fragment frag, then care must be taken in the contract that the fragment exposes. Changing its behavior for the benefit of acc-1 might break its use in acc-2.

To resolve this, you can track the versions of the fragment and document with numbers when there is an incompatible change. VMware recommends that you use semantic versioning to track the contract for fragments.

To give you more flexibility with version control, Application Accelerator does not manage versioning. VMware recommends that you track the semantic version of fragments in the fragment name. For example, if fragment frag changes its contract in a way that is not compatible with previous accelerators that use it, it becomes frag-v2 and is regarded as a different fragment.

You can store fragment versions where you want, but version control systems such as Git are a good choice.