You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by an...@apache.org on 2021/11/02 11:30:17 UTC
[jena-site] branch main updated: Documentation for Fuseki Modules
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 b1d9c08 Documentation for Fuseki Modules
b1d9c08 is described below
commit b1d9c087ef48975c8e3b88409727fe4c3e81e471
Author: Andy Seaborne <an...@apache.org>
AuthorDate: Fri Oct 29 14:57:22 2021 +0100
Documentation for Fuseki Modules
---
source/documentation/fuseki2/__index.md | 22 ++--
.../documentation/fuseki2/fuseki-configuration.md | 3 -
source/documentation/fuseki2/fuseki-modules.md | 119 +++++++++++++++++++++
3 files changed, 130 insertions(+), 14 deletions(-)
diff --git a/source/documentation/fuseki2/__index.md b/source/documentation/fuseki2/__index.md
index 2f8daca..22ac8a7 100644
--- a/source/documentation/fuseki2/__index.md
+++ b/source/documentation/fuseki2/__index.md
@@ -122,20 +122,20 @@ Development builds (not a formal release):
Source code:
[https://github.com/apache/jena/tree/main/jena-fuseki2](https://github.com/apache/jena/tree/main/jena-fuseki2)
-The Fuseki module are under "jena-fuseki2/":
+The Fuseki code is under "jena-fuseki2/":
-| Fuseki Module | Purpose |
-|---------------|-|
+| Code | Purpose |
+|---------------|--|
| jena-fuseki-core | The Fuseki engine. All SPARQL operations.
-| <b>Webapp </b> | |
-| jena-fuseki-webapp | Web application and command line startup |
-| jena-fuseki-fulljar | Build the combined jar for Fuseki/UI server |
-| jena-fuseki-war | Build the war file for Fusek/UI server |
-| apache-jena-fuseki | The download for Fuskei |
| <b>Fuseki/Main</b> | |
-| jena-fuseki-main | Embedded server and command line
+| jena-fuseki-main | Embedded server and command line
| jena-fuseki-server | Build the combined jar for Fusek/main server |
| jena-fuseki-docker | Build a docker conntained based on Fusek/main |
-| <b>Other</b> | |
-| jena-fuseki-access | [Data access control](fuseki-data-access-control.html) |
+| <b>Webapp </b> | |
+| jena-fuseki-webapp | Web application and command line startup |
+| jena-fuseki-fulljar | Build the combined jar for Fuseki/UI server |
+| jena-fuseki-war | Build the war file for Fusek/UI server |
+| apache-jena-fuseki | The download for Fuskei |
+| <b>Other</b> | |
+| jena-fuseki-access | [Data access control](fuseki-data-access-control.html) |
| jena-fuseki-geosparql | Integration for GeoSPARQL |
diff --git a/source/documentation/fuseki2/fuseki-configuration.md b/source/documentation/fuseki2/fuseki-configuration.md
index ceaa746..8f33b52 100644
--- a/source/documentation/fuseki2/fuseki-configuration.md
+++ b/source/documentation/fuseki2/fuseki-configuration.md
@@ -188,9 +188,6 @@ by searching the configuration file for the type `fuseki:Service`.
# See java doc for ARQ.queryTimeout
# ja:context [ ja:cxtName "arq:queryTimeout" ; ja:cxtValue "10000" ] ;
- # Load custom code (rarely needed)
- # ja:loadClass "your.code.Class" ;
-
# Explicitly choose which services to add to the server.
# If absent, include all descriptions of type `fuseki:Service`.
# fuseki:services (<#service1> <#service2>)
diff --git a/source/documentation/fuseki2/fuseki-modules.md b/source/documentation/fuseki2/fuseki-modules.md
new file mode 100644
index 0000000..bbeb8e6
--- /dev/null
+++ b/source/documentation/fuseki2/fuseki-modules.md
@@ -0,0 +1,119 @@
+---
+title: Fuseki Modules
+---
+
+<em>Fuseki modules</em> are a mechanism to include extension code into a Fuseki
+server. Modules are invoked during the process of building a [Fuseki
+Main](./fuseki-main.html) server. The module can modify the server
+configuration, add new functionality, or react to a server being built and
+started.
+
+This feature was added in Jena version 4.3.0.
+
+Fuseki Modules are loaded use the JDK
+[ServiceLoader](https://www.baeldung.com/java-spi) by being placing a jar file on the classpath,
+together with any additional dependencies. The service loader looks for files
+`META-INF/services/org.apache.jena.fuseki.main.sys.FusekiModule` in the jar
+file.
+This is often done by placing the file in the development code in
+`src/main/resources/META-INF/services/`).
+The file containing a line with the implementation full class name. If
+[repacking](../notes/jena-repack.html) Fuseki with the maven-shade-plugin, make
+sure the `ServicesResourceTransformer` is used. The module must have a no
+argument constructor.
+
+If using Fuseki as an [embedded server](./fuseki-embedded.html), the module is
+added in code as:
+
+```
+ FusekiModule module = new MyModule();
+ FusekiModules.add(module);
+```
+
+The method `start` is called when the module is loaded. Custom operations can
+be globally registered at this point (see the [Fuseki
+examples](https://github.com/apache/jena/tree/main/jena-fuseki2/jena-fuseki-main/src/test/java/org/apache/jena/fuseki/main/examples) directory).
+
+The module lifecycle during creating a Fuseki server is:
+
+* `configuration` - access and modify the setup.
+ This is called after the server has been configured, just before the server is built.
+* `server` - access the built server
+* `serverBeforeStarting` - about to call "server.start()"
+* `serverAfterStarting` - just after calling "server.start()"
+* `serverStopped` - called as the server stop
+ (note, this is not always called because a server can simply exit the JVM).
+
+A Fuseki module does not need to implement all these steps, the default for all
+of them is "do nothing". Usually, an extension will only be interested in
+certain stpes, like the configuration and registry information of
+`configuration`.
+
+During the configuration step, the Fuskei configuration file for the server is
+available. If the server is built programmatically without a configuration file,
+this is null.
+
+The configuration file can contain RDF information to build resources (e.g.
+contains assembler descriptions not directly linked to the server).
+
+There is an [example Fuseki
+Module](https://github.com/apache/jena/blob/main/jena-fuseki2/jena-fuseki-main/src/test/java/org/apache/jena/fuseki/main/examples/ExFusekiMain_3_FusekiModule.java)
+in the Fuseki examples directory.
+
+`FusekiModule` interface:
+
+```java
+/**
+ * Module interface for Fuseki.
+ * <p>
+ * A module is additional code, usually in a separate jar,
+ * but can also be part of the application code.
+ */
+public interface FusekiModule extends SubsystemLifecycle {
+ /**
+ * Unique (within this server) name to identify this module.
+ * The default is to generate an UUID.
+ */
+ public String name();
+
+ /** Module loaded */
+ @Override
+ public default void start() {}
+
+ // ---- Build cycle
+
+ /**
+ * Called at the start of "build" step. The builder has been set according to the
+ * configuration. The "configModel" parameter is set if a configuration file was
+ * used otherwise it is null.
+ */
+ public default void configuration(FusekiServer.Builder builder, DataAccessPointRegistry dapRegistry, Model configModel) {}
+
+ /**
+ * Built, not started, about to be returned to the builder caller.
+ */
+ public default void server(FusekiServer server) { }
+
+ /**
+ * Server starting - called just before server.start happens.
+ */
+ public default void serverBeforeStarting(FusekiServer server) { }
+
+ /**
+ * Server started - called just after server.start happens, and before server
+ * .start() returns to the application.
+ */
+ public default void serverAfterStarting(FusekiServer server) { }
+
+ /** Server stopping.
+ * Do not rely on this to clear up external resources.
+ * Usually there is no stop phase and the JVM just exits or is killed externally.
+ *
+ */
+ public default void serverStopped(FusekiServer server) { }
+
+ /** Module unloaded */
+ @Override
+ public default void stop() {}
+}
+```