svn commit: r1703995 - /jena/site/trunk/content/documentation/notes/system-initialization.mdtext

[an...@apache.org]

Author: andy
Date: Sat Sep 19 12:03:34 2015
New Revision: 1703995

URL: http://svn.apache.org/viewvc?rev=1703995&view=rev
Log:
Notes on Jena initialization

Added:
    jena/site/trunk/content/documentation/notes/system-initialization.mdtext

Added: jena/site/trunk/content/documentation/notes/system-initialization.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/notes/system-initialization.mdtext?rev=1703995&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/notes/system-initialization.mdtext (added)
+++ jena/site/trunk/content/documentation/notes/system-initialization.mdtext Sat Sep 19 12:03:34 2015
@@ -0,0 +1,106 @@
+Title: Apache Jena Initialization
+
+Jena has a simple 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.
+
+The standard initialization sequence is<br/>
+Core -> RIOT -> ARQ -> TDB -> other (SDB, jena text, jena spatial)
+
+The sequence from core to TDB should be executed before application
+compoents. See below for how to control the order.
+
+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.
+
+## Initialization code
+
+Initialzation code is an implementation of `JenaSubsystemLifecycle`.
+and must have a zero-argument constructor.
+
+```
+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 levels used by Jena are:
+
+* 0 - reserved
+* 10 - Used by jena-core
+* 20 - RIOT
+* 30 - ARQ
+* 40 - TDB
+* 9999 - other
+
+## 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.
+
+Only the first call of `JenaSystem.init()` causes the process to run.
+Any subsequent calls are cheap, so calling `JenaSystem.init()`
+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.system.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
+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() ;
+```