Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/broadleafcommerce/microservicesconcepts

Various extension and dev use cases. Proving ground for concepts.
https://github.com/broadleafcommerce/microservicesconcepts

Last synced: about 1 year ago
JSON representation

Various extension and dev use cases. Proving ground for concepts.

Awesome Lists containing this project

README 

          
:icons: font

:source-highlighter: prettify

:doctype: book

:toc: macro

ifdef::env-github[]

:tip-caption: :bulb:

:note-caption: :information_source:

:important-caption: :heavy_exclamation_mark:

:caution-caption: :fire:

:warning-caption: :warning:

endif::[]



++++



++++



= Microservice Extensibility Concepts



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



toc::[]



== 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 https://developer.broadleafcommerce.com/architecture/deployment-flexibility#overview[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 link:https://start.broadleafcommerce.com/[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 link:https://developer.broadleafcommerce.com/starter-projects#what_do_i_need[here].

2. Docker setup requirements described link:https://developer.broadleafcommerce.com/starter-projects/evaluation-credentials#docker_registry_authentication[here].

3. Maven setup requirements described link:https://developer.broadleafcommerce.com/starter-projects/evaluation-credentials#maven_repository_authentication[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: xref:concepts/00100-productExtensionOnly/README.adoc[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: xref:concepts/00200-productExtensionComplexFieldJson/README.adoc[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 : xref:concepts/00100-productExtensionOnly/README.adoc[00100-productExtensionOnly]



=== Explicit Product Projection



Concept: xref:concepts/00300-productExtensionExplicitProjection/README.adoc[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 : xref:concepts/00200-productExtensionComplexFieldJson/README.adoc[00200-productExtensionComplexFieldJson]



=== Product Extension with New Table Relationship



Concept: xref:concepts/00400-productExtensionComplexFieldTableBased/README.adoc[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 : xref:concepts/00200-productExtensionComplexFieldJson/README.adoc[00200-productExtensionComplexFieldJson]



=== Product with Nested JSON Collection



Concept: xref:concepts/00500-nestedJsonMemberExtension/README.adoc[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 : xref:concepts/00300-productExtensionExplicitProjection/README.adoc[00300-productExtensionExplicitProjection]



=== Product with New Nested Table Relationship



Concept: xref:concepts/00600-nestedTableBasedMemberExtension/README.adoc[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 : xref:concepts/00400-productExtensionComplexFieldTableBased/README.adoc[00400-productExtensionComplexFieldTableBased]



=== Overriding a Repository



Concept: xref:concepts/00700-repositoryCustomizationOverride/README.adoc[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 : xref:concepts/00200-productExtensionComplexFieldJson/README.adoc[00200-productExtensionComplexFieldJson]



=== New Repository



Concept: xref:concepts/00800-repositoryCustomizationContribution/README.adoc[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 : xref:concepts/00200-productExtensionComplexFieldJson/README.adoc[00200-productExtensionComplexFieldJson]



=== Customizing Business Logic



Concept: xref:concepts/00900-businessLogicCustomization/README.adoc[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: xref:concepts/01000-businessLogicCustomizationAutoProjection/README.adoc[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 : xref:concepts/00800-repositoryCustomizationContribution/README.adoc[00800-repositoryCustomizationContribution]



=== Customized Business Logic with Explicit Projection



Concept: xref:concepts/01100-businessLogicCustomizationExplicitProjection/README.adoc[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 : xref:concepts/00300-productExtensionExplicitProjection/README.adoc[00300-productExtensionExplicitProjection]



=== Endpoint Customization



Concept: xref:concepts/01200-endpointCustomization/README.adoc[01200-endpointCustomization]



Simple customization of out-of-the-box `ProductEndpoint`



- Demonstrate a behavior tweak of a single endpoint method



=== Endpoint Customization using AutoProjection



Concept: xref:concepts/01300-endpointCustomizationAutoProjection/README.adoc[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 : xref:concepts/01000-businessLogicCustomizationAutoProjection/README.adoc[01000-businessLogicCustomizationAutoProjection]



=== Endpoint Customization using Explicit Projection



Concept: xref:concepts/01400-endpointCustomizationExplicitProjection/README.adoc[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 : xref:concepts/01100-businessLogicCustomizationExplicitProjection/README.adoc[01100-businessLogicCustomizationExplicitProjection]



=== Brand New Entity



Concept: xref:concepts/01500-newDomain/README.adoc[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 : xref:concepts/00100-productExtensionOnly/README.adoc[00100-productExtensionOnly]



=== Brand New Entity with Complex Fields



Concept: xref:concepts/01600-newDomainComplexField/README.adoc[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 : xref:concepts/01500-newDomain/README.adoc[01500-newDomain]



=== Tuning Auto Projection with New Entity



Concept: xref:concepts/01700-newDomainFineTuneAutoProjection/README.adoc[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 : xref:concepts/01600-newDomainComplexField/README.adoc[01600-newDomainComplexField]



=== New Entity with Explicit Projection



Concept: xref:concepts/01800-newDomainExplicitProjection/README.adoc[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 : xref:concepts/01600-newDomainComplexField/README.adoc[01600-newDomainComplexField], xref:concepts/00300-productExtensionExplicitProjection/README.adoc[00300-productExtensionExplicitProjection]