[jena-site] branch main updated: Update system-initialization.md

[an...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

andy pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/jena-site.git


The following commit(s) were added to refs/heads/main by this push:
     new abba6bfcf Update system-initialization.md
abba6bfcf is described below

commit abba6bfcf4215a7511aebe4e5876c009121c2162
Author: Andy Seaborne <an...@apache.org>
AuthorDate: Sat Jan 7 15:49:38 2023 +0000

    Update system-initialization.md
---
 .../documentation/notes/system-initialization.md   | 111 +++++++--------------
 1 file changed, 38 insertions(+), 73 deletions(-)

diff --git a/source/documentation/notes/system-initialization.md b/source/documentation/notes/system-initialization.md
index 8766a01cd..9f851e0b6 100644
--- a/source/documentation/notes/system-initialization.md
+++ b/source/documentation/notes/system-initialization.md
@@ -2,54 +2,76 @@
 title: Apache Jena Initialization
 ---
 
-Jena has a simple initialization sequence that is
+Jena has an initialization sequence that is
 used to setup components available at runtime.
 
 Application code is welcome to also use this mechanism. This
-must be done with care. Java initialization can lead to
-visibility of uninitialized data.
+must be done with care. During Jena initialization, there can be 
+visibility of uninitialized data in class static members.
 
 The standard initialization sequence is  
 Core -> RIOT -> ARQ -> TDB -> other (including jena text)
 
-The sequence from core to TDB should be executed before application
-components. See below for how to control the order.
+The sequence from 0 to level 500 is the Jena platform
+initialization. Application may use the jena initialization mechanism and it is
+recommended to place initialization code above level 500.
 
 Initialization occurs when `JenaSystem.init()` is first called.  Jena ensures that this
 is done when the application first uses any Jena code by using class
 initializers.
 
+Application can call `JenaSystem.init()`. 
+
 See [notes on repacking Jena code](jena-repack.html) for how to deal
-with ServiceLoader files in repacked jars.
+with `ServiceLoader` files in repacked jars.
 
 ## Initialization code
 
-Initialization code is an implementation of `JenaSubsystemLifecycle`.
-For use in the default initialization, the class must have a zero-argument constructor
+Initialization code is an implementation of `JenaSubsystemLifecycle` which
+itself extends `SubsystemLifecycle`.
+
+For use in the default initialization, the class must have a zero-argument
+constructor and implement:
 
+```java
     public interface JenaSubsystemLifecycle {
         public void start() ;
         public void stop() ;
         default public int level() { return 9999 ; }
     }
+```
 
-The code also supply a level, indicating its place in the order of initialization.
+The code should supply a level, indicating its place in the order of initialization.
 The levels used by Jena are:
 
 * 0 - reserved
 * 10 - Used by jena-core
+* 15 - CLI Commands registry
 * 20 - RIOT
 * 30 - ARQ
-* 40 - TDB
-* 9999 - other
+* 40 - Text indexing
+* 40 - TDB1
+* 42 - TDB2
+* 60 - Additional HTTP configuration
+* 60 - RDFPatch
+* 96 - SHACL
+* 96 - ShEx
+* 101 - Fuseki
+* 9999 - Default.
+
+Levels up to 500 are considered to be "Jena system level", Application code
+should use level above 500.
+
+Fuseki initialization includes [Fuseki
+Modules](/documentation/fuseki2/fuseki-modules) which uses `SubsystemLifecycle`
+with a different Java interface.
 
 ## The Initialization Process
 
-The process followed by `JenaSystem.init()` is to obtain an instance of
-`JenaSubsystemRegistry`, ask it to `load()` initialization code, then call
-that code in an order based on declared level. The order of invocation
-of different initialization code within the same level is undefined
-and may be different from run to run.
+The process followed by `JenaSystem.init()` is to load all java `ServiceLoader`
+registered `JenaSubsystemLifecycle`, sort into level order, then call `init` on
+each initialization object. Initialization code at the same level may be called
+in any order and that order may be different between runs.
 
 Only the first call of `JenaSystem.init()` causes the process to run.
 Any subsequent calls are cheap, so calling `JenaSystem.init()`
@@ -58,19 +80,6 @@ when in doubt about the initialization state is safe.
 Overlapping concurrent calls to `JenaSystem.init()` are thread-safe.
 On a return from `JenaSystem.init()`, Jena has been initialized at some point.
 
-## The Standard Subsystem Registry
-
-The `JenaSubsystemRegistry` normally used is based on `java.util.ServiceLoader`.
-It looks for class resources
-`META-INF/services/org.apache.jena.sys.JenaSubsystemLifecycle`
-on the classpath during the load step.
-
-See the javadoc for `java.util.ServiceLoader` for more details.
-
-See also the javadoc for
-[JenaSystem](/documentation/javadoc/jena/org/apache/jena/system/JenaSystem.html)
-and the source code.
-
 ## Debugging
 
 There is a flag `JenaSystem.DEBUG_INIT` to help with development. It is not
@@ -78,47 +87,3 @@ intended for runtime logging.
 
 Jena components print their initialization beginning and end points on
 `System.err` to help track down ordering issues.
-
-## Modifying the Standard Process
-
-It is possible, with care, to alter the way
-that initialization code is discovered.
-
-An application can change the `JenaSubsystemRegistry` instance.
-This must be done before any Jena code is called anywhere
-in the current JVM.
-
-    // Example alternative registry.
-    JenaSubsystemRegistry r = new JenaSubsystemRegistryBasic() {
-        @Override
-        public void load() {
-            if ( JenaSystem.DEBUG_INIT )
-                System.err.println("Example custom load") ;
-            super.load();
-        }
-    } ;
-
-    // Set the sub-system registry
-    JenaSystem.setSubsystemRegistry(r);
-
-    // Enable output if required
-    // JenaSystem.DEBUG_INIT = true ;
-
-    // Initialize Jena
-    JenaSystem.init() ;
-
-## Jena initialization in multi-classloader environments
-
-In some applications with multiple classloaders, or different classloader strategies, Jena initialization may
-not work as expected. If the Jena initialization debug information shows that components were not loaded correctly,
-trying to switch the context class loader may fix the initialization process.
-
-    ClassLoader contextClassLoader = null;
-    try {
-        contextClassLoader = Thread.currentThread().getContextClassLoader();
-        Thread.currentThread().setContextClassLoader(getClass().getClassLoader());
-        JenaSystem.DEBUG_INIT = true;
-        // ...
-    } finally {
-        Thread.currentThread().setContextClassLoader(contextClassLoader);
-    }