Microservices Extensibility Concepts

Table of Contents

Concept Directory
Extending Auth Entities

To illustrate the most common extension use-cases, we’ve created a project called Microservices Concepts available here: https://github.com/BroadleafCommerce/MicroservicesConcepts

This project focuses on creating runnable examples demonstrating how these typical customizations can be accomplished. Each example is structured as a runnable "concept".

Note
view the README in the Microservices Concepts project for details around getting this project running locally

Concept Directory

Concept Description

Concept	Description
Simple Product Extension	Simple extension of `JpaProduct` adding only a basic field type. Also leverages auto projection, rather than opting for an explicit extended projection.
Product Extension with JSON Field	Simple extension of `JpaProduct` adding more complex field types, including collections and maps. The complex types use JPA converters to persist the complex structure as JSON. This example still leverages auto projection and does not declare an explicit extending projection type.
Explicit Product Projection	Continues with the complex field example persisted as JSON. However, in this case, an explicit projection type is declared.
Product Extension with New Table Relationship	Alters the complex field example to leverage a traditional JPA OneToMany associated collection. The relates to a new table in the database, rather than serializing to JSON.
Product with Nested JSON Collection	Extends nested structures that appear arbitrarily deep in the object graph of `JpaProduct`. The structures appear in various embedded collections and are persisted as JSON.
Product with New Nested Table Relationship	Extends nested structures that appear arbitrarily deep in the object graph of JpaProduct. The structures appear in OneToMany table based collections.
Overriding a Repository	Adds a new repository implementation fragment overriding out-of-the-box behavior of JpaTrackableRepository
New Repository	Introduces new repository methods that contribute new persistence related behavior. This take the form of either dynamic query method fragments, or concrete implementation fragments.
Customizing Business Logic	Uses a simple customization of the `DefaultProductService`.
Customized Business Logic with Auto Projection	Business logic customization that leverages a customized repository and extended domain with auto projection
Customized Business Logic with Explicit Projection	Business logic customization that leverages a customized repository and extended domain with explicit projection
Endpoint Customization	Simple customization of out-of-the-box `ProductEndpoint`
Endpoint Customization using AutoProjection	Customization of an endpoint method in `ProductEndpoint` leveraging a customized service, repository, auto-projection, and domain
Endpoint Customization using Explicit Projection	Customization of an endpoint method in `ProductEndpoint` using an extended explicit projection and domain
Brand New Entity	Introduction of new domain without explicit projection or any other explicit plumbing like repository, service, or endpoint
Brand New Entity with Complex Fields	Introduction of new domain including complex field structures
Tuning Auto Projection with New Entity	Introduction of new domain with auto projection output fine tuned through customization
New Entity with Explicit Projection	Introduction of new domain including explicit projection declaration

Simple Product Extension

Simple extension of JpaProduct adding only a basic field type. Also leverages auto projection, rather than opting for an explicit extended projection.

Product Extension with JSON Field

Simple extension of JpaProduct adding more complex field types, including collections and maps. The complex types use JPA converters to persist the complex structure as JSON. This example still leverages auto projection and does not declare an explicit extending projection type.

Explicit Product Projection

Continues with the complex field example persisted as JSON. However, in this case, an explicit projection type is declared.

Product Extension with New Table Relationship

Alters the complex field example to leverage a traditional JPA OneToMany associated collection. The relates to a new table in the database, rather than serializing to JSON.

Product with Nested JSON Collection

Extends nested structures that appear arbitrarily deep in the object graph of JpaProduct. The structures appear in various embedded collections and are persisted as JSON.

Product with New Nested Table Relationship

Extends nested structures that appear arbitrarily deep in the object graph of JpaProduct. The structures appear in OneToMany table based collections.

Overriding a Repository

Adds a new repository implementation fragment overriding out-of-the-box behavior of JpaTrackableRepository

New Repository

Introduces new repository methods that contribute new persistence related behavior. This take the form of either dynamic query method fragments, or concrete implementation fragments.

Customizing Business Logic

Uses a simple customization of the DefaultProductService.

Customized Business Logic with Auto Projection

Business logic customization that leverages a customized repository and extended domain with auto projection

Customized Business Logic with Explicit Projection

Business logic customization that leverages a customized repository and extended domain with explicit projection

Endpoint Customization

Simple customization of out-of-the-box ProductEndpoint

Endpoint Customization using AutoProjection

Customization of an endpoint method in ProductEndpoint leveraging a customized service, repository, auto-projection, and domain

Endpoint Customization using Explicit Projection

Customization of an endpoint method in ProductEndpoint using an extended explicit projection and domain

Brand New Entity

Introduction of new domain without explicit projection or any other explicit plumbing like repository, service, or endpoint

Brand New Entity with Complex Fields

Introduction of new domain including complex field structures

Tuning Auto Projection with New Entity

Introduction of new domain with auto projection output fine tuned through customization

New Entity with Explicit Projection

Introduction of new domain including explicit projection declaration

Extending Auth Entities

When extending out-of-the-box Broadleaf entities in AuthenticationService, a specific Hibernate enhancement plugin configuration is required in the pom.xml to support field-level lazy loading (FetchType.LAZY). Without this plugin configuration, Hibernate cannot process lazy properties properly, causing the extended auth entities to fail at runtime.

Depending on your project setup, this configuration might need to be added manually:

Manifest-Based Projects (New Activation)

If you are using a Manifest-based project (using manifest.yml with the Broadleaf Flex Maven Plugin) and are just now enabling the authComponent, the plugin configuration is automatically injected into the generated authComponent/pom.xml during the code generation process. No manual action is required.

Non-Manifest Projects or Pre-existing Auth Modules

You must manually add the hibernate-enhance-maven-plugin configuration to your authComponent module’s pom.xml under the <build><plugins> section if:

You are not using a Manifest-based project structure.
You already have a pre-existing, custom-extended authComponent module (as the automated generator avoids overwriting or altering pre-existing POM structures).

Required Maven Plugin Configuration:

<plugin>
    <!--
        IMPORTANT: This plugin configuration is required for extensions against
        Broadleaf Auth entities to work properly.
        This plugin is required to support field-level lazy loading (FetchType.LAZY)
        for out of the box Auth entities. Without this plugin, Hibernate cannot process
        lazy properties properly, which will cause auth extended entities to fail.
     -->
    <groupId>org.hibernate.orm.tooling</groupId>
    <artifactId>hibernate-enhance-maven-plugin</artifactId>
    <executions>
        <execution>
            <configuration>
                <failOnError>true</failOnError>
                <enableLazyInitialization>true</enableLazyInitialization>
                <enableDirtyTracking>true</enableDirtyTracking>
            </configuration>
            <goals>
                <goal>enhance</goal>
            </goals>
        </execution>
    </executions>
</plugin>