For example, this is a basic transformation of a CodeModel that redirects all calls to static methods in the Foo class to the Bar class, preserving all other elements:

CodeTransform fooToBar = (b, e) -> {
    if (e instanceof InvokeInstruction i
            && i.owner().name().equalsString("Foo")
            && i.opcode() == Opcode.INVOKESTATIC) {
        // remove the old element i by doing nothing to the builder
        // add a new invokestatic instruction to the builder
        b.invokestatic(CD_Bar, i.name().stringValue(), i.typeSymbol(), i.isInterface());
    } else {
        b.with(e);  // leaves the element in place
    }
};

More advanced usages of transforms include start or end handling, stateful transformation that makes a decision based on previously encountered member elements, and composition of transforms, where one transform processes the results of a previous transform on the input compound structure. All these capabilities are supported by this interface and accessible to user transform implementations.

Users can define custom start and end handling for a transform by overriding atStart(B) and atEnd(B). The start handler is called before any member element is processed, and the end handler is called after all member elements are processed. For example, the start handler can be used to inject extra code elements to the beginning of a code array, and the end handler, combined with stateful transformation, can perform cleanup actions, such as determining if an attribute has been merged, or if a new attribute should be defined. Each subtype of ClassFileTransform defines a utility method endHandler that returns a transform that only has end handling.

Transforms can have states that persist across processing of individual member elements. For example, if a transform injects an annotation, the transform may keep track if it has encountered and presented an updated RuntimeVisibleAnnotationsAttribute to the builder; if it has not yet, it can present a new attribute containing only the injected annotation in its end handler. If such a transform is to be shared or reused, each returned transform should have its own state. Each subtype of ClassFileTransform defines a utility method ofStateful where a supplier creates the transform at its initial state each time the transform is reused.

Transforms can be composed via andThen(C). When this transform is composed with another transform, it means the output member elements received by the ClassFileBuilder become the input elements to that other transform. Composition avoids building intermediate structures for multiple transforms to run on. Each subtype of ClassFileTransform implements andThen(C), which generally should not be implemented by users.

Transforms that run on smaller structures can be lifted to its enclosing structures to selectively run on all enclosed smaller structures of the same kind. For example, a CodeTransform can be lifted via ClassTransform.transformingMethodBodies(Predicate, CodeTransform) to transform the method body of select methods in the class it runs on. This allows users to write small transforms and apply to larger scales.

Besides ClassFileBuilder.transform(CompoundElement, ClassFileTransform), there are other methods that accepts a transform conveniently, such as ClassFile.transformClass(ClassModel, ClassTransform), ClassBuilder.transformField(FieldModel, FieldTransform), ClassBuilder.transformMethod(MethodModel, MethodTransform), or MethodBuilder.transformCode(CodeModel, CodeTransform). They are convenience methods that suit the majority of transformation scenarios.