✔️ cae-framework

☕ Java & Kotlin edition

Welcome to the open source cae-framework repository! This component of the SDK is designed to enable the Angularization effect of client applications by following Clean Architecture principles.

▶️ The artifact:

<dependency>
  <groupId>com.clean-arch-enablers</groupId>
  <artifactId>cae-framework</artifactId>
  <version>${version}</version>
</dependency>

All available versions can be found here: cae-framework on Maven (since it is in a snapshot state, it is recommended to always use the latest version.)

State Symbol Key:

• ✅ — Under release state
• ✔️ — Under snapshot state
• ⏳ — Under full development state

📚 Key Concepts

⚙️ Use Cases

The core of the CAE Framework revolves around use cases. Each use case is a distinct, self-contained unit of functionality, designed to be easily maintained, extended, and tested.

🎨 Types of Use Cases

• ✔️ FunctionUseCase: Receives input and returns output.
• ✔️ ConsumerUseCase: Receives input but does not return output.
• ✔️ SupplierUseCase: Returns output without any input.
• ✔️ RunnableUseCase: Neither receives input nor returns output.

That's how you declare Use Cases:

//will receive objects of type GetBotAccountsUseCaseInput and return ones of type GetBotAccountUseCaseOutput
public abstract class GetBotAccountsUseCase extends FunctionUseCase<
        GetBotAccountsUseCaseInput,
        GetBotAccountsUseCaseOutput> {}

//will receive objects of type UpdateUserAccountProfileUseCaseInput and return nothing
public abstract class UpdateUserAccountProfileUseCase extends ConsumerUseCase<UpdateUserAccountProfileUseCaseInput> {}

//wont receive anything as input, but will return an object of type GetUserAccountProfilesUseCaseOutput
public abstract class GetUserAccountProfilesUseCase extends SupplierUseCase<GetUserAccountProfilesUseCaseOutput> {}

//neither receives or returns anything; it only executes something
public abstract class DeleteInactiveLeadsUseCase extends RunnableUseCase {}

Use Case types which accept input require the parameterized generic type of the input to be a subclass of UseCaseInput, this way the Use Case can leverage the UseCaseInput API for input validation rules. For the output types nothing is required.

▶️ Use Case Execution

Every Use Case subtype will inherit the same API for getting executed:

UseCase::execute

The difference between them all is only that some accept input and/or return output and others don't do either or at least one of the options. Regardless, everyone of them accepts the following parameter: an object of type ExecutionContext. This object serves the purpose of identifying each request with a unique ID, so troubleshootings can rely on the execution context at the log level of analysis, for example.

The ExecutionContext object keeps an attribute called correlationId which is the UUID that identifies each execution. It can be generated randomly or provided programmatically:

//generating random correlationId
var random = ExecutionContext.ofNew();

//providing a previous set correlationId
var correlationId = UUID.randomUUID().toString();
var previouslyEstablished = ExecutionContext.of(correlationId)

The random approach serves well when the workflow begins at that point, but in case the flow starts at the frontend app, for example, it is interesting for the frontend app to generate a correlationId in UUID and pass it down to the backend service where the Use Case is gonna be executed and programmatically pass it as the correlationId of the Execution Context the Use Case will consume. This way the step-by-step can be monitored even throughout different applications of the stack.

When executed, a Use Case can have some side behaviors:

• ✔️ Autolog
• ✔️ Auto input validation
• ⏳ Autocache
• ⏳ Autonotify
• ✔️ Scope based authorization validation
• ⏳ Role based authorization validation

📄 Autolog

Whenever an instance of use case gets executed, an automatic log will be generated. It can be in two modes:

• structured
• natural language

The structured mode is a JSON payload with the log data, while the natural language mode is basically a simple text. However, both can display the same data; they just differ in their presentation styles.

The contained info is:

• The use case: the name of the use case which is being executed (the object's class name)
• Execution correlation Id: an unique identifier per execution (can be parameterized or randomly generated)
• Whether or not successful: if the flow didn't throw any exceptions
• Exception thrown (in case of unsuccessful executions): what went wrong
• Latency
• Port insights: insights of what's going on during the execution of each of the use case's ports
• IO data: what the use case execution received as input and what returned as output

An example for the structured format:

{
    "useCaseExecution": {
        "useCase": "auth_root_account_implementation",
        "correlationId": "c6268eb5-2f2b-48e3-8138-f5636af216b4",
        "successful": "true",
        "exception": null,
        "latency": "31",
        "portInsights": [
            "FindRootAccountByLoginIdPortAdapter's insights: no exception has been thrown",
            "FindRootAccountSecretPortAdapter's insights: no exception has been thrown",
            "SessionTokenGenerationPortAdapter's insights: no exception has been thrown"
        ],
        "io": {
            "input": {
                "loginId": "[email protected]",
                "pass": "**********"
            },
            "output": {
                "expiration": "3600",
                "name": "Capitólio",
                "id": "4",
                "token": "eyJhbGciOiJIUzI1NiJ9.eyJvd25lciI6IjQiLCJhY3RvciI6IjQiLCJzY29wZXMiOiJST09UIiwiZXhwIjoxNzI5OTgyNDk4fQ.j068hm4oLFTFM2M5luS7UsB4YAEjYplkx1dAmubWVS8"
            }
        }
    }
}

As for the natural language style:

Use case "auth_root_account_implementation" execution with correlation ID of "509cbcbe-c6e8-4ffa-9ca6-62b1cd35e2e3" finished successfully. It took about 65 milliseconds. | Port insights: [FindRootAccountByLoginIdPortAdapter's insights: no exception has been thrown, FindRootAccountSecretPortAdapter's insights: no exception has been thrown, SessionTokenGenerationPortAdapter's insights: no exception has been thrown] [USE CASE INPUT]: { "pass": "**********", "loginId": "[email protected]" }; [USE CASE OUTPUT]: { "expiration": "3600", "name": "Capitólio", "id": "4", "token": "eyJhbGciOiJIUzI1NiJ9.eyJvd25lciI6IjQiLCJhY3RvciI6IjQiLCJzY29wZXMiOiJST09UIiwiZXhwIjoxNzMwMjQ3NDExfQ.kYGx3I8KbwzzRk9znYb-r6_h58359QVQZTFwFB9ipl8" };

The IO data processing for inclusion into the log payload is done natively with a to-json method. During its execution, the cae-native process takes into account the fields of the IO objects that are marked with the @Sensitive annotation. Depending on the parameterized configuration of this annotation, the autolog will:

• Completely mask the field value
• Partially mask the field value
• Mask from right or from left
• Just ignore the actual value and put a fixed length of "*" characters

@Getter
@Setter
public class SomeExample extends UseCaseInput {

    @Sensitive(unmaskFromLeft = false, unmaskedAmount = 3)
    private Long somePartiallyMaskedFieldFromRightToLeft;

    @Sensitive(unmaskedAmount = 5)
    private String anotherPartiallyMaskedFieldFromLeftToRight;

    @Sensitive(defaultMaskedAmount = 8)
    private String willJustBeAMaskWith8OfLength;

}

Any exceptions thrown during the execution of a Use Case will be intercepted by the Use Case itself. If the exception is a subtype of MappedException, the Use Case instance will consider it a part of the designed flow, as it is a MappedException, and let it go untouched. On the other hand, if it is not, the Use Case instance will see it as an unexpected exception and wrap it into a UseCaseExecutionException object. Either way the autolog will include this event in the log data.

The framework itself doesn't have a dependency for an actual logger, it depends on the client application to provide an implementation of the Logger native interface:

public interface Logger {

    void logInfo(String info);
    void logError(String error);
    void logDebug(String info);

}

An example of an actual implementation of the interface above, on the side of a client application:

@NoArgsConstructor(access = AccessLevel.PRIVATE)
@Slf4j
public class LoggerAdapter implements Logger {

    public static final Logger SINGLETON = new LoggerAdapter();

    @Override
    public void logInfo(String info) {
        log.info(info);
    }

    @Override
    public void logError(String error) {
        log.error(error);
    }

    @Override
    public void logDebug(String info) {
        log.debug(info);
    }

}

Once an implementation of the Logger interface is created, to provide it to the framework, it goes like this:

LoggerProvider.SINGLETON.setProvidedInstance(LoggerAdapter.SINGLETON);

The LoggerProvider is a native component of the cae-framework. The LoggerProvider::setProvidedInstance will receive any implementation of the Logger interface.

Expanding on the usage of the LoggerProvider API:

• LoggerProvider::structuredFormat: if set true, the presentation style of the log payload is the JSON mentioned in the beginning of this section. If false, in a simple text format.
• LoggerProvider::setUseCasesLoggingIO: another boolean for setting whether or not the autolog will include the IO data of Use Case executions.
• LoggerProvider::setPortsLoggingIO: same as the previous one, but for Ports (we'll get there).
• LoggerProvider::setLoggingStackTrace: whether or not the autolog will include logs of StackTrace for exceptions thrown during Use Case executions.
• LoggerProvider::setNumberOfLinesFromStackTrace: if the previous one is set true, it is possible to set the number of StackTrace lines will be included into the log.
• LoggerProvider::setIOLoggingMode: whether to use the CAE Native mode (which converts objects to JSON) or to rely on the objects' toString implementations.

It will look like this:

LoggerProvider.SINGLETON
    .setProvidedInstance(LoggerAdapter.SINGLETON)
    .setIOLoggingMode(IOLoggingMode.CAE_NATIVE)
    .structuredFormat(false)
    .setUseCasesLoggingIO(true)
    .setPortsLoggingIO(false)
    .setLoggingStackTrace(true)
    .setNumberOfLinesFromStackTrace(2);

⤵ Auto input validation

Two types of Use Case accept input: the FunctionUseCase and the ConsumerUseCase. Since they do, it is desirable to have a way to establish required input fields as not-null, not-blank, not-empty, etc. The cae-framework supports all of these, natively:

• @NotNullInputField: for fields of any type that must not be null.
• @NotBlankInputField: for String fields which can't be blank (empty or all-space strings).
• @NotEmptyInputField: for String and Collection fields that cannot be empty.
• @ValidInnerPropertiesInputField: for custom types that, inside, have their own properties with their own validation rules, based on the annotations mentioned above.

The input validation rule is established when any field of a UseCaseInput subtype is annotated with one or more of the above annotations.

An example of UseCaseInput validation rule:

@Getter
@Setter
public class AuthRootAccountUseCaseInput extends UseCaseInput {

    @NotNullInputField
    @NotBlankInputField
    private String loginId;

    @NotNullInputField
    @NotBlankInputField
    @Sensitive
    private String pass;

}

That way, whenever the AuthRootAccountUseCase instance gets executed and receives an AuthRootAccountUseCaseInput object as input, the Use Case will internally call the UseCaseInput::validateProperties API, which will ensure the validation rule is respected. If it is, the Use Case accepts the input and proceeds to process it. If it is not, the Use Case rejects and throws an exception specifying what went wrong:

Field 'AuthRootAccountUseCaseInput:loginId' can't have blank values.

📦 Autocache

...

🔔 Autonotify

...

🎯 Scope based authorization

Use Case types annotated with the @ProtectedUseCase will need to specify, within the annotation, the required scopes for being granted the access to execute the Use Case instance.

@ProtectedUseCase(scope = "ROOT || MAINTAINER")
public abstract class CreateUserAccountUseCase extends FunctionUseCase<
        CreateUserAccountUseCaseInput,
        CreateUserAccountUseCaseOutput> {}

For the Use Case above (CreateUserAccountUseCase), it is necessary to have either the ROOT or the MAINTAINER scope in order to execute it. The way the framework knows whether or not the responsible for the execution has the required scopes is via the Actor interface.

public interface Actor {
    List<String> getScopes();
}

An example for an actual implementation of it, on the side of a client application:

@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
public class ActorSessionManager implements Actor {

    @Getter
    private final String owner;
    @Getter
    private final String id;
    private final String scopes;

    public static Actor createOutta(String authorizationHeader){
        var jwt = JWT.of(authorizationHeader.replace("Bearer ", ""));
        var claims = jwt.getDecryptedJWT();
        if (claims.getExpiration().before(new Date()))
            throw new UnauthorizedException();
        return new ActorSessionManager(
                claims.getOwner(),
                claims.getActor(),
                claims.getScopes()
        );
    }

    @Override
    public List<String> getScopes() {
        return List.of(this.scopes);
    }

The example above extracts the expected scopes out of a JWT.

Once a concrete implementation of the Actor interface is created, the way to provide its instances on each Use Case execution is via the ExecutionContext object. For Use Case types which aren't annotated with @ProtectedUseCase, the ExecutionContext instance provided in each execution isn't required to have an instance of the Actor interface, however, for protected Use Case types, if one is not provided, the execution will be rejected.

The way to provide an instance of Actor to the ExecutionContext is as follows, considering the example of ActorSessionManager mentioned lastly as the implementation:

var actor = ActorSessionManager.createOutta(authorization);
var executionContext = ExecutionContext.of(correlationId, actor);
var useCaseOutput = useCase.execute(useCaseInput, executionContext);

⛑️ Role based authorization

...

📖 Autodoc

During the build phase of your application, each Use Case has its metadata extracted to a file named cae-docfile.json. This is an autodocumentation that can be integrated with the CAE Real-Time Service Catalog SaaS which is on its way to be born. The concept is that during CI/CD pipelines a Service Catalog is kept up to date in real time, enabling teams across the organization to keep up with what's available.

The autodoc feature doesn't care whether your Use Case instances are dispatched as REST Endpoints, Kafka Consumers, SQS Listeners, CRON jobs or any other type of primary adapter flavour: it only has eyes for the Use Cases themselves, which means a single way to document all Use Cases in a seamless manner.

🌐 Other components of the SDK:

• ✔️ cae-cli
• ✔️ cae-utils-mapped-exceptions
• ✔️ cae-utils-http-client
• ✔️ cae-common-primary-adapters
• ✔️ cae-utils-env-vars
• ✔️ cae-utils-trier
• ✔️ cae-rdb
• ⏳ cae-service-catalog

CAE — Clean Architecture made easy.