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.
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.
@Configuration public class CatalogServiceAutoConfiguration { // ... @Bean @ConditionalOnMissingBean 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.
Broadleaf provides many out of the box domain classes. It is common for implementations to need to add persisted fields and structures as part of a commerce implementation to one or more of these. See Joined Inheritance For Domain.
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.
@Entity @Table(name = "MYCOMPANY_PRODUCT") @Data @EqualsAndHashCode(callSuper = true) public class MyJpaProduct extends JpaProduct { @Column(name = "MY_PROPERTY") private String myProperty; # (1) @Override public ModelMapper fromMe() { # (2) return super.fromMe(); } @Override public ModelMapper toMe() { return super.toMe(); } @Override public Class<?> getBusinessDomainType() { # (3) return MyProduct.class; } }New property added to the extension (primitive, collection, or map)
(Optional) fromMe and toMe are used if special mapping is required from a custom business domain type you have created. Most of the time these are not required and can be omitted when extending. You can call super.fromMe(), for example, to get the populated ModelMapper from the superclass and add your further mappings to it.
(Optional) getBusinessDomainType is only required if you are creating a custom projection type (see below). If you omit the getBusinessDomainType override, the system will auto create a projection for you of type Projection<MyJpaProduct>. See Projection for more information on how to get a projection instance based on your extended domain type, and then how to exercise its API by calling expose.
and (Optional) the similar customization needed for the projection domain. If an extended projection is not declared, Broadleaf can synthesize one for you.
@Data @EqualsAndHashCode(callSuper = true) public class MyProduct extends Product { private String myProperty;See Sandboxing In Detail for more information on general domain class design.
| 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. |
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.
When considering extensions to Broadleaf, it is important to understand Broadleaf release versioning. Broadleaf uses semantic 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 manner 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.
Minor releases are more common and represent significant enhancements and bug fixes that could require work to upgrade. Minor releases are backward compatible from an API and code operation perspective. However, minor releases may introduce schema change, but that change will be done in a way that will not preclude rollback. See Release Notes for more information on our semantic versioning with schema addendum policy.
| Note | Each microservice has its own upgrade lifecycle which allows for targeted upgrades. Services release schedules are ad-hoc and as needed. The "release collection" indicates an official release of the "BOM", which 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. This especially applies to services that have been configured to run together in the same Spring boot container, as 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 backward compatibility and no database schema change. 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.