Broadleaf Microservices

Extensibility / Customization


Extensibility is as a first class concern with the Broadleaf framework. Every controller, service, and entity within the product can be extended as needed to meet the needs of an implementation.

Important: A Broadleaf license includes access to source code; however, implementations rarely if ever need to modify source. Instead, Broadleaf provides mechanisms to override, extend, and replace out of box components through configuration and custom code. Note, also that "starters" and "demos" are examples that should be used directly and are not meant to be extensible.

Note: The Broadleaf Unified Admin is also fully extensible and is covered more in the related documentation sections.

Extending Components

Broadleaf has nearly a thousand service, repository, web, and utility components that each can be easily extended as needed for custom business logic and functionality. These are configured as spring beans through normal Spring Configuration mechanisms.

Broadleaf out of box beans use the following syntax which so that out of box functionality will back off if your application defines a configuration for the same bean. For example, here is the snippet of configuration that registers the out of box ProductService.

public class CatalogServiceAutoConfiguration {
// ...
        ProductService<Product> productService(
                ProductRepository<Trackable> productRepository,
                RsqlCrudEntityHelper helper,
                VariantService<Variant> variantService) {
            return new DefaultProductService<>(productRepository, helper, variantService);
// ...

The code above may be a little cryptic if you are new to Spring configuration but there are two important parts to callout. First, notice the line where the service is constructed with new DefaultProductService(…​). An implementation could create its own configuration that constructed an extension of the DefaultProductService to add, overrride, or replace out of box functionality.

This works because we use the @ConditionalOnMissingBean spring annotation which means that your bean configuration will always take priority over the out of box configuration.

Extending Domain

Broadleaf provides hundreds of out of box domains. It is common for implementations to need to add persisted fields and structures as part of a commerce implementation.

See the Customizing Broadleaf tutorials for a step by step tour of adding a new field to an existing Broadleaf entity.

Generally, extending the Broadleaf domain consists of extending the "business domain" and the "persisted domain" using standard SpringData and JPA annotations.

Note: Some services in Broadleaf have support for other persistence technologies. The general extension concepts are the same but examples will use JPA as it is supported by all services.

For example, here is a simple example where a single field is added to the persisted product.

@Table(name = "MYCOMPANY_PRODUCT")
@EqualsAndHashCode(callSuper = true)
public class MyProduct extends JpaProduct {
    @Column(name = "MY_PROPERTY")
    private String myProperty;

and the similar customization needed for the business domain …​

@EqualsAndHashCode(callSuper = true)
public class MyProduct extends Product {
    private String myProperty;

Note: This article focuses on programmatic domain extension. Many entities within Broadleaf can be extended by business users by using the "custom field" functionality within the admin.

Extending Controllers

Broadleaf uses Spring REST controllers to provide the out of box APIs. Instead of extending these components, the pattern is slightly different but still very simple.

To extend an out of box Broadleaf controller, you will create a new Spring REST controller that overrides the desired endpoint. It is typical to inject the out of box Broadleaf controller as a property into your controller to introduce a small variation. This pattern is detailed in the customizing Broadleaf endpoints tutorial.

Release Versioning

When considering extensions to Broadleaf, it is important to understand Broadleaf release versioning. Broadleaf uses standard maven versioning, for example 1.0.0-GA which can also be stated as {major}.{minor}.{patch}-GA.

Note: Broadleaf Support does not mandate upgrades and works with clients to support them on upgrading in a manor and timeline that is best for each individual business.

Major releases imply a possibly significant upgrade. These could follow major technology shifts in Java or Spring or within Broadleaf itself. Historically, Broadleaf has released major version about once every 2-3 years.

Minor releases are more common and represent changes that could require work to upgrade. If new domain is added or there are breaking API changes, Broadleaf will add those to a minor release. Similarly, if a spring or other library upgrade might introduce significant breaking changes, it that library upgrade would be part of a minor release. "Unified" minor releases frequency is every 3-4 months.

Note: Each microservice has its own upgrade lifecycle which allows for targeted upgrades. Services release schedules are ad-hoc and as needed. The "unified" release indicates an official release of the "BOM" which at Broadleaf is a concept similar to a Spring Boot version. Within the BOM, all of the Broadleaf microservices are guaranteed to have common versions of dependent libraries. For services being that have been configured to run together in the same Spring boot container, they need to use compatible dependent libraries. See (Deployment Flexibility

Patch releases typically occur monthly but can be released at any time, especially at the service level. A patch is issued for bug fixes and small enhancements with low (and often no) impact to implementations. It is highly recommended that applications consume the latest patch of the framework as patches include open source library upgrades that have been reported by security scanners and other important bug fixes.