diff --git a/docs/documentation/server_development/topics/providers.adoc b/docs/documentation/server_development/topics/providers.adoc index 24f414b6b52..0c5f27565b6 100644 --- a/docs/documentation/server_development/topics/providers.adoc +++ b/docs/documentation/server_development/topics/providers.adoc @@ -122,6 +122,44 @@ public class MyThemeSelectorProvider implements ThemeSelectorProvider { } ---- +The pom.xml file for your SPI requires a `dependencyManagement` section with an import reference to the {project_name} version that is intended for the SPI. In this example, replace the occurrence of `VERSION` with {project_versionMvn}, which is the current version of {project_name}. + +[source,xml] +---- + + + 4.0.0 + + org.example + test-lib + 1.0-SNAPSHOT + + + + + org.keycloak + keycloak-parent + VERSION + pom + import + + + + + + + org.keycloak + keycloak-model-jpa + provided + + + + +---- +<.> Replace `VERSION` with the current version of {project_name} + [[_override_builtin_providers]] ==== Override built-in providers @@ -224,14 +262,14 @@ After registering new providers or dependencies Keycloak needs to be re-built wi [NOTE] ==== -Provider JARs are not loaded in isolated classloaders, so do not include resources or classes in your provider JARs that conflict with built-in resources or classes. -In particular the inclusion of an application.properties file or overriding the commons-lang3 dependency will cause auto-build to fail if the provider JAR is removed. +Provider JARs are not loaded in isolated classloaders, so do not include resources or classes in your provider JARs that conflict with built-in resources or classes. +In particular the inclusion of an application.properties file or overriding the commons-lang3 dependency will cause auto-build to fail if the provider JAR is removed. If you have included conflicting classes, you may see a split package warning in the start log for the server. Unfortunately not all built-in lib jars are checked by the split package warning logic, so you'll need to check the lib directory JARs before bundling or including a transitive dependency. Should there be a conflict, that can be resolved by removing or repackaging the offending classes. -There is no warning if you have conflicting resource files. You should either ensure that your JAR's resource files have path names that contain something unique to that provider, +There is no warning if you have conflicting resource files. You should either ensure that your JAR's resource files have path names that contain something unique to that provider, or you can check for the existence of `some.file` in the JAR contents under the `"install root"/lib/lib/main` directory with something like: - + [source,bash] ---- find . -type f -name "*.jar" -exec unzip -l {} \; | grep some.file @@ -245,7 +283,7 @@ If you find that your server will not start due to a `NoSuchFileException` error ---- This will force Quarkus to rebuild the classloading related index files. From there you should be able to perform a non-optimized start or build without an exception. -==== +==== ==== Disabling a provider