From a81a2dcc938c667cd62f648fffcaf430cb017893 Mon Sep 17 00:00:00 2001 From: Jj! Date: Tue, 9 Oct 2018 09:56:05 -0500 Subject: [PATCH] [SHIBUI-467] doc --- docs/customizations.md | 48 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/customizations.md diff --git a/docs/customizations.md b/docs/customizations.md new file mode 100644 index 000000000..0423fbce9 --- /dev/null +++ b/docs/customizations.md @@ -0,0 +1,48 @@ +# Custom Development + +For a full example of creating a custom module for the application, see the `pac4j-module` project. + +As a Spring Boot application built with gradle, there are many opportunities available for +custom development against the application. Note that most customizations should be done in +separate modules, not directly modifying the source to the base application. + +## Application Classpath + +To get customizations in the application, one must make the changes available on the application +classpath. Depending on the deployment method, one has a few options for doing this. + +1. Take advantage of the `Properties Launcher` in the executable JAR +2. Put resources in the appropriate `WEB-INF` directory for a WAR deployment + +If one is adding Spring configuration, register the configuration classes with the Spring +Autoconfiguration service by adding a file called `META-INF/spring.factories` to the JAR +file containing the custom java class and referencing any configuration classes: + +```properties +org.springframework.boot.autoconfigure.EnableAutoConfiguration=org.example.SomeConfiguration +``` + +For more information, see [https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-developing-auto-configuration.html#boot-features-locating-auto-configuration-candidates] + +### Executable JAR + +The executable JAR uses the Properties Launcher provided by Spring Boot ([https://docs.spring.io/spring-boot/docs/current/reference/html/executable-jar.html#executable-jar-property-launcher-features]). +The easiest way to add something to the classpath is to create a file named `loader.properties` in the same directory +as the jar with the following: + +```properties +loader.path=libs/ +``` + +The noted directory will be added to the classpath, along with any JAR files contained in the directory. + +### WAR + +If deploying a WAR, one would use the standard packaging for providing items to the classpath. + +* JAR files should be placed in `WEB-INF/lib` +* all other resources should be placed `WEB-INF/classes` + +It is highly recommended that a WAR overlay be used to prevent changing the version fingerprint. Overlay +methods exist for both Maven ([https://maven.apache.org/plugins/maven-war-plugin/overlays.html]) and +Gradle ([https://github.com/scalding/gradle-waroverlay-plugin]) projects. \ No newline at end of file