Microservice Extensibility Concepts

This project contains several example concepts demonstrating various extension and backend commerce API developer use-cases.

Table of Contents

• Microservice Extensibility Concepts
  • Terminology
  • Project Guidelines
  • Project Structure
  • What Do I Need?
  • Building a Concept Project
  • Roadmap
  • Concept Directory
    • Simple Product Extension
    • Product Extension with JSON Field
    • Explicit Product Projection
    • Product Extension with New Table Relationship
    • Product with Nested JSON Collection
    • Product with New Nested Table Relationship
    • Overriding a Repository
    • New Repository
    • Customizing Business Logic
    • Customized Business Logic with Auto Projection
    • Customized Business Logic with Explicit Projection
    • Endpoint Customization
    • Endpoint Customization using AutoProjection
    • Endpoint Customization using Explicit Projection
    • Brand New Entity
    • Brand New Entity with Complex Fields
    • Tuning Auto Projection with New Entity
    • New Entity with Explicit Projection

Terminology

• Concept: A sub-project within this overall project that showcases a discrete customization goal. The goal will be clearly stated in each concept project. Some concept projects will be deeper riffs on concepts from other projects (e.g. a simple domain extension in one project may be built on top of to add additional repository extension in another project).

• Flex Package: A deployable unit of Broadleaf Commerce Microservices. This may contain a single microservice (e.g. the Catalog Service), or it may contain several services bundled together. The advantages of flexpackage bundling are: reduced devops complexity with fewer discrete units running in an environment, smaller deployment footprint with multiple services running under the same JVM/heap allocation (saves $), and a sane local development footprint suitable for developer laptops to run the entire stack. Disadvantages include: less granular scale tuning, and possibly decreased team contribution isolation. It’s notable that flexpackage setup is a configuration only concern, and changing later on to a more granular deployment is entirely feasible. The Balanced flexpackage is generally considered the best mix when weighed against all these concerns at the same time. More details can be found here

• Auto Projection: Broadleaf Commerce Microservices operate with two versions of the domain class representation. The repository domain is generally represented as a JPA annotated POJO that interacts with an ORM to facilitate input/output from database storage. The projection domain is a version of the repository domain that is exposed outside of the service layer and represents the structure that is serialized into JSON as output from the microservice endpoints. Projection and repository domains can share the same structure, but are not required to do so, and Broadleaf provides mapping facilities to customize how data flows between these two representations of the same data. While Broadleaf does allow complexity here, it is not required that extensions of Broadleaf repository domain (or introduction of new repository domain) explicitly declare a projection with explicit mapping. If the needs are simple and direct representation of the data to the business layer is acceptable, then Broadleaf can auto generate a projection for you. Henceforth, you will be able to reference the projection and its fields using the facilities in Broadleaf (demonstrated in several of the concept examples). This serves to simplify configuration and development for standard use cases.

• Data Routing: This is the technology that primarily facilitates the operation of flexpackage bundling. Data routing is used to detect the datasource that should be utilized for the current flow. As a result, multiple service endpoints housed in the same JVM/classloader can leverage different datasources (and different backing database/schema) to enable their data interactions. Beyond datasources, spring beans can be grouped and filtered by a route to produce interesting behavior for service flows as well. This all supports proper bounded context per service, while still allowing more interesting deployment options.

• Data Tracking: This is the technology that supports entity discrimination, sandboxing, and catalog propagation. There are different tracking types based on the maintenance needs of the data. Types of tracking include: catalog, application, sandbox, customercontext, and tenant. These types include interesting grouping, discrimination, preview, audit, and workflow capabilities. Based on your requirements, you can also add these capabilities in a simple way to your own unique domain.

• Fragment (or Repository Fragment): This is a Spring Data concept for contributing repository data persistence behavior via interfaces and concrete implementations. The resulting spring component is callable at runtime and exposes the aggregate contract of all the contributed interfaces. Broadleaf provides facilities to contribute additional fragments (interfaces and optional concrete impls) to existing repositories. This is the primary extension mechanism for adding behavior to Broadleaf declared repositories.

Project Guidelines

• The concept project structure will be simple.

• Each concept project will consume framework and demo artifacts from the latest relevant stable branches.

• Each concept project is constructed using the minimal amount of configuration and code for optimum clarity.

• The concept project is based on Broadleaf starter parent pom files.

• If you’re using an initialzr starter project, you can include sample code from here in your own generated project. The samples demonstrated here are all for the catalog component, and you can generate a similar catalog component override module using the initialzr and selecting the catalog service checkbox to customize.

Project Structure

Directory	Description
concepts	Group of buildable projects that demonstrate a key dev or extension experience using the most streamlined approach available.

What Do I Need?

In order to get these concepts running locally, you will want to obtain and install the following:

1. General requirements described here.

2. Docker setup requirements described here.

3. Maven setup requirements described here.

Building a Concept Project

• You can compile and run the tests in each or all of these projects.

• You can tweak code / configuration and explore further customizations and test confirmations.

• In the project root at a terminal prompt you can:

  • Mac - ./mvnw clean install to build all the service overrides, liquibase changelogs, modelmapper caches, and execute tests.

  • Windows - mvnw.cmd clean install to build all the service overrides, liquibase changelogs, modelmapper caches, and execute tests.

• Or, to build only a single module from the project root (replace $artifactId with the artifactId of the module you want to build. e.g. broadleaf-concept-product-extension-only):

  • Mac - ./mvnw clean install -pl :$artifactId -am (the colon before the artifactId is important)

  • Windows - mvnw.cmd clean install -pl :$artifactId -am (the colon before the artifactId is important)

Roadmap

• This project represents an ongoing effort to document customization use cases and patterns.

• We will continue to add new concepts as they come up.

• If a new concept requires a framework change or enhancement (e.g. a change to one or more of the libraries above), we will increment the version of this concept project along with noting the version change(s) to the associated common framework libraries.

• Training will also be developed based on these concept materials and will be available separately.

Concept Directory

Simple Product Extension

Concept: 00100-productExtensionOnly

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

• Demonstrate the simplest type of extension

• Introduce the Projection interface

• Show full lifecycle support (json in/out) for the endpoint API

• Show supporting admin customization

• Show automated testing and the use of @TestCatalogRouted (et al.) to handle datarouting requirements during the test

Product Extension with JSON Field

Concept: 00200-productExtensionComplexFieldJson

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.

• Demonstrate more complex field type

• Demonstrate interaction with Projection interface to expose complex structures for editing

• Show full lifecycle support (json in/out) for the endpoint API

• Show supporting admin customization

• Builds On : 00100-productExtensionOnly

Explicit Product Projection

Concept: 00300-productExtensionExplicitProjection

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

• Demonstrate custom mapping to/from projection

• Demonstrate response only projection field

• Show supporting admin customization

• Demonstrate mapping to synthetic fields

• Builds On : 00200-productExtensionComplexFieldJson

Product Extension with New Table Relationship

Concept: 00400-productExtensionComplexFieldTableBased

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.

• Show table based complex field support in the JpaProduct extension

• Demonstrate custom mapping to/from projection

• Demonstrate special @ProjectionPostConvert support for setting bi-directional references

• Show supporting admin customization

• Builds On : 00200-productExtensionComplexFieldJson

Product with Nested JSON Collection

Concept: 00500-nestedJsonMemberExtension

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.

• Show several examples of nested structure extension

• Show supporting admin customization

• Builds On : 00300-productExtensionExplicitProjection

Product with New Nested Table Relationship

Concept: 00600-nestedTableBasedMemberExtension

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

• Show example of nested OneToMany table based structure extension

• Show supporting admin customization

• Builds On : 00400-productExtensionComplexFieldTableBased

Overriding a Repository

Concept: 00700-repositoryCustomizationOverride

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

• Show concrete fragment contribution example overriding JpaTrackableRepository methods for JpaProductRepository

• Demonstrate the use of JpaTrackableRepositoryDelegateSupplier to use in the fragment for extension via composition

• Builds On : 00200-productExtensionComplexFieldJson

New Repository

Concept: 00800-repositoryCustomizationContribution

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

• Demonstrate new query method fragment contribution (interface only)

• Demonstrate new concrete method implementation fragment contribution

• Show concrete fragment contribution example overriding JpaTrackableRepository methods for JpaProductRepository

• Demonstrate the use of JpaTrackableRepositoryDelegateSupplier to use in the fragment for extension via composition

• Builds On : 00200-productExtensionComplexFieldJson

Customizing Business Logic

Concept: 00900-businessLogicCustomization

Uses a simple customization of the DefaultProductService.

• Show a minor customization of the business logic of DefaultProductService

Customized Business Logic with Auto Projection

Concept: 01000-businessLogicCustomizationAutoProjection

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

• Show DefaultProductService call the customized repository to search by a new extended field

• Demonstrate how to use the Projection interface to interact with the service API

• Builds On : 00800-repositoryCustomizationContribution

Customized Business Logic with Explicit Projection

Concept: 01100-businessLogicCustomizationExplicitProjection

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

• Show complete lifecycle in/out of the endpoint with extended field information

• Demonstrate handling of the customized repository and domain

• Builds On : 00300-productExtensionExplicitProjection

Endpoint Customization

Concept: 01200-endpointCustomization

Simple customization of out-of-the-box ProductEndpoint

• Demonstrate a behavior tweak of a single endpoint method

Endpoint Customization using AutoProjection

Concept: 01300-endpointCustomizationAutoProjection

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

• Demonstrate a behavior tweak of a single endpoint method

• Show leveraging a completely customized flow through to persistence

• Demonstrate working with an auto projection in the endpoint

• Builds On : 01000-businessLogicCustomizationAutoProjection

Endpoint Customization using Explicit Projection

Concept: 01400-endpointCustomizationExplicitProjection

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

• Demonstrate a behavior tweak of a single endpoint method

• Demonstrate working with an explicit projection in the endpoint

• Builds On : 01100-businessLogicCustomizationExplicitProjection

Brand New Entity

Concept: 01500-newDomain

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

• Demonstrate the simplest type of domain introduction

• Show full lifecycle support (json in/out) for the endpoint API

• Builds On : 00100-productExtensionOnly

Brand New Entity with Complex Fields

Concept: 01600-newDomainComplexField

Introduction of new domain including complex field structures

• Demonstrate domain introduction with embedded json collection fields

• Demonstrate domain introduction with nested JPA OneToMany collection fields

• Builds On : 01500-newDomain

Tuning Auto Projection with New Entity

Concept: 01700-newDomainFineTuneAutoProjection

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

• Demonstrate customization of auto projection with the ExplicitProjectionFieldConfiguration annotation

• Demonstrate removing a field from the projection

• Demonstrate limiting a field to response only during update/replace

• Demonstrate altering deserialization/serialization (e.g. to/from MonetaryAmount for a BigDecimal field)

• Builds On : 01600-newDomainComplexField

New Entity with Explicit Projection

Concept: 01800-newDomainExplicitProjection

Introduction of new domain including explicit projection declaration

• Demonstrate explicit projection declaration

• Demonstrate projection customizations

• Demonstrate custom JSON deserialization/serialization for a projection field

• Demonstrate maintenance to/from a synthetic map to a different JPA domain structure

• Builds On : 01600-newDomainComplexField, 00300-productExtensionExplicitProjection