Package com.broadleafcommerce.common.jpa.schema

Class SchemaCompatibiltyUtility

java.lang.Object

com.broadleafcommerce.common.jpa.schema.SchemaCompatibiltyUtility

public final class SchemaCompatibiltyUtility
extends Object

Utility for exporting a generated schema from emitted persistence configuration via ORM (from entity metadata) to a Liquibase change log xml file. This utility furthermore has validation functionality. Here's a list of the specific features.

1. Generate a change log - used to create a new change log xml for the entities known to Spring and ORM at runtime.
2. Generate diff - used to append delta change sets to a previous change log from the most recent state of entities known to Spring and ORM at runtime.
3. Validate release - used to confirm a change log is up-to-date with the most recent state of entities known to Spring and ORM at runtime. This can also serve as an extra checkpoint to detect unknown entity changes that would affect the schema requirements for a release - especially a patch release, which should not have deltas here.

This utility is most often employed as part of a integration test that couples it with Spring and allows a dev to easily generate up-to-date change log files, while also allowing a CI pipeline to perform validation checks during a release. This utility works with the RDBMS platforms supported by Broadleaf. Note, Broadleaf currently supports the following RDBMS platforms and versions:

1. Postgres >= 9.2
2. Oracle >= 12cR1
3. MySql >= 8
4. Mariadb >= 10.2.2

In order to discover certain files within a project, this utility will attempt to find the root of the current project relative to the build directory. By default, this utility keys off of a Jenkinsfile defined in the root of a project that follows a build directory structure of "root/dir1/dir2/target/classes" or "root/dir1/target/classes" (e.g. myproject/services/catalog/target/classes) These defaults can be overriden by passing in the following environment properties: "broadleaf.project.root" and "broadleaf.project.relative.build.depth". For example, you can define a flat project structure with an empty placeholder file called BLCRoot at the root of the project with a build directory of "myproject/target/classes" by defining "broadleaf.project.root=BLCRoot" and "broadleaf.project.relative.build.depth=2"

Author:

Jeff Fischer

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SchemaCompatibiltyUtility.Initializer	Spring environment initializer.
static class	SchemaCompatibiltyUtility.MariaBaseProvider
static class	SchemaCompatibiltyUtility.MariaUtilityProvider
static class	SchemaCompatibiltyUtility.MariaVerificationProvider
static class	SchemaCompatibiltyUtility.ModifiedMariaDB103Dialect	A modified Mariadb ORM dialect describing any Broadleaf specific schema generation requirements for JPA entities.
static class	SchemaCompatibiltyUtility.ModifiedMariaDBDatabase
static class	SchemaCompatibiltyUtility.ModifiedMySQL8Dialect	A modified Mysql ORM dialect describing any Broadleaf specific schema generation requirements for JPA entities.
static class	SchemaCompatibiltyUtility.ModifiedOracle12cDialect	A modified Oracle ORM dialect describing any Broadleaf specific schema generation requirements for JPA entities.
static class	SchemaCompatibiltyUtility.MySqlBaseProvider
static class	SchemaCompatibiltyUtility.MySqlUtilityProvider
static class	SchemaCompatibiltyUtility.MySqlVerificationProvider
static class	SchemaCompatibiltyUtility.OracleBaseProvider
static class	SchemaCompatibiltyUtility.OracleUtilityProvider
static class	SchemaCompatibiltyUtility.OracleVerificationProvider
static class	SchemaCompatibiltyUtility.PostgresBaseProvider
static class	SchemaCompatibiltyUtility.PostgresUtilityProvider
static class	SchemaCompatibiltyUtility.PostgresVerificationProvider
static class	SchemaCompatibiltyUtility.ValidationPackage
static class	SchemaCompatibiltyUtility.YugabyteBaseProvider
static class	SchemaCompatibiltyUtility.YugabyteUtilityProvider
static class	SchemaCompatibiltyUtility.YugabyteVerificationProvider

Field Summary

Fields

Modifier and Type	Field	Description
static String	IGNORE_VALIDATION

Method Summary

Modifier and Type	Method	Description
static void	generateLog(org.springframework.context.ApplicationContext appctx)	Generate a change log xml file based on the current entity configuration known to Spring and the ORM.
static void	initializeOracleUser(String sysPassword, String jdbcUrl, String newUser, String newPassword)
static void	mariaSetup(String jdbcUrl, String userName, String password, String databaseName)	Mariadb platform specific setup method that establishes base configuration for execution.
static void	mySqlSetup(String jdbcUrl, String userName, String password, String databaseName)	Mysql platform specific setup method that establishes base configuration for execution.
static void	oracleSetup(String jdbcUrl, String userName, String password)	Oracle platform specific setup method that establishes base configuration for execution.
static void	postgresSetup(String jdbcUrl, String userName, String password, String databaseName)	Postgres platform specific setup method that establishes base configuration for execution.
static void	setup(String jdbcUrl, String userName, String password, String databaseName)	Short-version setup method that establishes base configuration for execution.
static void	setup(String jdbcUrl, String userName, String password, String driverClassname, String dialect, String platform, String databaseName)	Catch-all setup method that establishes base configuration for execution.
static void	validateForRelease(org.springframework.context.ApplicationContext appctx)	During a release, we expect to find a existing changelog file in the codebase, and we expect that file to be up-to-date with the current entities that Spring and the ORM are aware of at runtime.
static void	yugabyteSetup(String jdbcUrl, String userName, String password, String databaseName)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IGNORE_VALIDATION

public static final String IGNORE_VALIDATION

See Also:

Constant Field Values

Method Detail

validateForRelease

public static void validateForRelease(org.springframework.context.ApplicationContext appctx)
                               throws Exception

During a release, we expect to find a existing changelog file in the codebase, and we expect that file to be up-to-date with the current entities that Spring and the ORM are aware of at runtime. This utility method performs that check and will throw an IllegalStateException should that validation fail.

Parameters:

appctx - The spring application context

Throws:

Exception - Any exception occurring during the validation, including an IllegalStateException.

setup

public static void setup(String jdbcUrl,
                         String userName,
                         String password,
                         String driverClassname,
                         String dialect,
                         String platform,
                         String databaseName)

Catch-all setup method that establishes base configuration for execution.

Parameters:

jdbcUrl - The jdbc url for connecting to the target database for schema generation

userName - The login username

password - The password for login

driverClassname - The jdbc driver class

dialect - The ORM dialect class name

platform - The Liquibase short name for the database platform

databaseName - The name of the database connecting to. This is the target schema for mysql, mariadb, and oracle. This is the target catalog for postgres.

setup

public static void setup(String jdbcUrl,
                         String userName,
                         String password,
                         String databaseName)

Short-version setup method that establishes base configuration for execution.

Parameters:

jdbcUrl - The jdbc url for connecting to the target database for schema generation

userName - The login username

password - The password for login

databaseName - The name of the database connecting to. This is the target schema for mysql, mariadb, and oracle. This is the target catalog for postgres.

mySqlSetup

public static void mySqlSetup(String jdbcUrl,
                              String userName,
                              String password,
                              String databaseName)

Mysql platform specific setup method that establishes base configuration for execution.

Parameters:

jdbcUrl - The jdbc url for connecting to the target database for schema generation

userName - The login username

password - The password for login

databaseName - The name of the database connecting to. This is the target schema for mysql, mariadb, and oracle. This is the target catalog for postgres.

mariaSetup

public static void mariaSetup(String jdbcUrl,
                              String userName,
                              String password,
                              String databaseName)

Mariadb platform specific setup method that establishes base configuration for execution.

Parameters:

jdbcUrl - The jdbc url for connecting to the target database for schema generation

userName - The login username

password - The password for login

databaseName - The name of the database connecting to. This is the target schema for mysql, mariadb, and oracle. This is the target catalog for postgres.

oracleSetup

public static void oracleSetup(String jdbcUrl,
                               String userName,
                               String password)

Oracle platform specific setup method that establishes base configuration for execution.

Parameters:

jdbcUrl - The jdbc url for connecting to the target database for schema generation

userName - The login username

password - The password for login

postgresSetup

public static void postgresSetup(String jdbcUrl,
                                 String userName,
                                 String password,
                                 String databaseName)

Postgres platform specific setup method that establishes base configuration for execution.

Parameters:

jdbcUrl - The jdbc url for connecting to the target database for schema generation

userName - The login username

password - The password for login

databaseName - The name of the database connecting to. This is the target schema for mysql, mariadb, and oracle. This is the target catalog for postgres.

yugabyteSetup

public static void yugabyteSetup(String jdbcUrl,
                                 String userName,
                                 String password,
                                 String databaseName)

generateLog

public static void generateLog(org.springframework.context.ApplicationContext appctx)
                        throws Exception

Generate a change log xml file based on the current entity configuration known to Spring and the ORM. If no file currently exists, a new one will be created. If a file already exists, any deltas from the current know state and that described in the change log file are added to the change log file. If the change log file is up-to-date, it is left alone.

Parameters:

appctx - The spring application context

Throws:

Exception - Any exception occurring during the change log generation

initializeOracleUser

public static void initializeOracleUser(String sysPassword,
                                        String jdbcUrl,
                                        String newUser,
                                        String newPassword)