diff --git a/de/15.8/dev/plugin-architecture.rst b/de/15.8/dev/plugin-architecture.rst index e9a5aa7ba..efffcacc4 100644 --- a/de/15.8/dev/plugin-architecture.rst +++ b/de/15.8/dev/plugin-architecture.rst @@ -5,28 +5,48 @@ Plugin-Architektur Übersicht ========= -Das Plugin-System von |Fess| ermoglicht die Erweiterung der Kernfunktionen. -Plugins werden als JAR-Dateien verteilt und dynamisch geladen. +Das Plugin-System von |Fess| ermöglicht die Erweiterung der Kernfunktionen. +Plugins werden als JAR-Dateien ausgeliefert; sobald sie dem Klassenpfad +hinzugefügt werden, lädt der DI-Container (Lasta Di) die Komponenten und +registriert sie bei den entsprechenden Factory- bzw. Manager-Klassen. Plugin-Typen ============ -|Fess| unterstutzt folgende Plugin-Typen: +|Fess| unterscheidet die Plugin-Typen anhand des Präfixes des +Artefaktnamens (``PluginHelper.ArtifactType``). Die wichtigsten Typen sind: .. list-table:: :header-rows: 1 - :widths: 25 75 + :widths: 20 25 55 * - Typ + - Präfix - Beschreibung * - DataStore - - Inhaltserfassung von neuen Datenquellen (Box, Slack usw.) - * - Script-Engine - - Unterstutzung neuer Skriptsprachen - * - WebApp - - Erweiterung des Web-Interfaces + - ``fess-ds-*`` + - Inhaltserfassung aus neuen Datenquellen (Box, Slack, Git usw.) + * - Webanwendung + - ``fess-webapp-*`` + - Erweiterung der Web-Oberfläche und der Suchfunktionen + * - Skript-Engine + - ``fess-script-*`` + - Unterstützung neuer Skriptsprachen * - Ingest - - Datenverarbeitung beim Indexieren + - ``fess-ingest-*`` + - Dokumentverarbeitung bei der Index-Registrierung + * - Theme + - ``fess-theme-*`` + - Anpassung des Erscheinungsbilds der Suchoberfläche + * - Thumbnail + - ``fess-thumbnail-*`` + - Hinzufügen von Verfahren zur Thumbnail-Erzeugung + * - LLM + - ``fess-llm-*`` + - Hinzufügen von LLM-Anbietern für RAG/Chat + * - Crawler + - ``fess-crawler-*`` + - Erweiterung des Crawler-Clients Plugin-Struktur =============== @@ -34,16 +54,28 @@ Plugin-Struktur Grundstruktur ------------- +Am Beispiel von `fess-ds-example `__, +der Implementierungsvorlage für DataStore-Plugins, besteht ein Plugin aus +einer „Implementierungsklasse" und einer „DI-Registrierungsdatei": + :: fess-ds-example/ ├── pom.xml - └── src/main/java/org/codelibs/fess/ds/example/ - ├── ExampleDataStore.java # DataStore-Implementierung - └── ExampleDataStoreHandler.java # Handler (optional) + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # DataStore-Implementierung + └── resources/ + └── fess_ds++.xml # DI-Komponentenregistrierung -pom.xml-Beispiel ----------------- +Beispiel für pom.xml +--------------------- + +Das Plugin wird als jar mit ``fess-parent`` als übergeordnetem POM gebaut. +Bibliotheken wie ``fess`` und ``opensearch``, die zur Laufzeit von |Fess| +selbst bereitgestellt werden, werden mit dem Scope ``provided`` deklariert. +Versionsnummer und Build-Konfiguration (z. B. Formatter und +Lizenzkopfzeilen) werden vom übergeordneten POM geerbt. .. code-block:: xml @@ -59,86 +91,138 @@ pom.xml-Beispiel 15.8.0 jar - fess-ds-example - Example DataStore for Fess - - - 15.8.0 - 21 - + + org.codelibs.fess + fess-parent + 15.8.0 + + org.codelibs.fess fess - ${fess.version} + provided + + + org.opensearch + opensearch provided +.. note:: + + In Branches, die sich in der Entwicklung befinden, erhält die Version ein + Suffix ``-SNAPSHOT``, z. B. ``15.8.0-SNAPSHOT``. Plugin-spezifische + Abhängigkeitsbibliotheken werden als normale Maven-Abhängigkeiten + deklariert. Da diese nicht in |Fess| selbst enthalten sind, müssen sie + zusammen mit dem Plugin verteilt werden. + Plugin-Registrierung -==================== +===================== Registrierung im DI-Container ------------------------------ +------------------------------ -Plugins werden in Konfigurationsdateien wie ``fess_ds.xml`` registriert: +Ein Plugin registriert seine Komponenten in einer DI-Konfigurationsdatei, +deren Name auf ``++`` endet, wie z. B. ``fess_ds++.xml``. Lasta Di führt +Dateien mit der Endung ``++``, die im Klassenpfad gefunden werden, +automatisch mit der entsprechenden Konfigurationsdatei von |Fess| selbst +zusammen (in diesem Beispiel ``fess_ds.xml``). Durch diesen Mechanismus kann +ein Plugin eigene Komponenten hinzufügen, ohne Dateien von |Fess| selbst zu +bearbeiten. .. code-block:: xml - - - - -Automatische Registrierung --------------------------- - -Viele Plugins registrieren sich automatisch mit der ``@PostConstruct``-Annotation: + + + + + + + + +Je nach Plugin-Typ unterscheidet sich die Ziel-Datei für das Merging. +Beispielsweise verwendet die Skript-Engine ``fess_se++.xml``, Ingest +``fess_ingest++.xml``, der LLM-Anbieter ``fess_llm++.xml`` und die +Webanwendung ``app++.xml``. + +Initialisierung der Komponente +-------------------------------- + +```` ist eine Lifecycle-Konfiguration von +Lasta Di, die die nach der Erzeugung der Komponente aufzurufende Methode +angibt. Im Fall eines DataStore wird die von ``AbstractDataStore`` +bereitgestellte Methode ``register()`` aufgerufen, wodurch sich die +Komponente selbst bei ``DataStoreFactory`` registriert: .. code-block:: java - @PostConstruct + // Implementierung von AbstractDataStore (in der Regel keine Überschreibung nötig) public void register() { - ComponentUtil.getDataStoreManager().add(this); + ComponentUtil.getDataStoreFactory().add(getName(), this); } +.. note:: + + Dies ist keine Initialisierung über die Java-Annotation + ``@PostConstruct``, sondern über das Element ```` der + DI-Konfigurationsdatei. Der registrierte Name ist der Rückgabewert von + ``getName()`` und entspricht dem Namen, der bei der Auswahl des Plugins + in der Administrationsoberfläche verwendet wird. + Plugin-Lebenszyklus -=================== +===================== Initialisierung ---------------- +---------------- -1. JAR-Datei wird geladen -2. DI-Container initialisiert Komponenten -3. ``@PostConstruct``-Methoden werden aufgerufen -4. Plugin wird beim Manager registriert +1. Das Plugin-JAR wird dem Klassenpfad hinzugefügt. +2. Der DI-Container führt ``fess_*++.xml`` zusammen und erzeugt die + Komponenten. +3. Die in ```` angegebene Methode (z. B. ``register``) wird + aufgerufen. +4. Das Plugin wird bei der entsprechenden Factory- bzw. Manager-Klasse + registriert. Beendigung ---------- -1. ``@PreDestroy``-Methode wird aufgerufen (falls definiert) -2. Ressourcen werden bereinigt +1. Beim Beenden des DI-Containers wird die in ```` angegebene + Methode aufgerufen (sofern definiert). +2. Bereinigung von Ressourcen. -Abhangigkeiten -============== +.. note:: -Abhangigkeit von Fess-Core --------------------------- + Im Fall eines DataStore wird ein laufender Crawl-Vorgang durch + ``AbstractDataStore.stop()`` mit einem Stopp-Flag versehen, sodass die + Verarbeitungsschleife für die Datensätze sicher beendet wird. + +Abhängigkeiten +================ + +Abhängigkeit von Fess selbst +------------------------------- + +Da die Klassen von |Fess| selbst zur Laufzeit im Klassenpfad des Servers +vorhanden sind, wird die Abhängigkeit mit dem Scope ``provided`` deklariert +(sie ist nicht im Plugin-JAR enthalten). .. code-block:: xml org.codelibs.fess fess - ${fess.version} provided Externe Bibliotheken --------------------- +--------------------- -Plugins konnen eigene Abhangigkeitsbibliotheken enthalten: +Ein Plugin kann eigene Abhängigkeitsbibliotheken enthalten: .. code-block:: xml @@ -148,40 +232,52 @@ Plugins konnen eigene Abhangigkeitsbibliotheken enthalten: 1.0.0 -Abhangigkeitsbibliotheken konnen zusammen mit dem Plugin-JAR verteilt werden, -oder es kann ein Fat-JAR mit dem Maven Shade Plugin erstellt werden. +Da diese nicht in |Fess| selbst enthalten sind, müssen sie zusammen mit dem +Plugin verteilt werden. -Konfigurationszugriff -===================== +Abrufen der Konfiguration +============================ -Zugriff auf FessConfig ----------------------- +Abrufen von Parametern und FessConfig +---------------------------------------- + +In ``storeData()`` eines DataStore werden die in der +Administrationsoberfläche konfigurierten Parameter aus ``DataStoreParams`` +abgerufen. Zum Abrufen der Werte wird ``getAsString()`` verwendet (da +``DataStoreParams`` das Interface ``Map`` nicht implementiert, gibt +``get()`` keinen String zurück). Konfigurationswerte von |Fess| lassen sich +außerdem über ``ComponentUtil.getFessConfig()`` abrufen: .. code-block:: java public class ExampleDataStore extends AbstractDataStore { @Override - public String getName() { - return "Example"; + protected String getName() { + // Wird als Handler-Name verwendet. Es ist üblich, den einfachen Klassennamen zurückzugeben + return this.getClass().getSimpleName(); } @Override - protected void storeData(DataConfig dataConfig, IndexUpdateCallback callback, - Map paramMap, Map scriptMap, - Map defaultDataMap) { + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { - // Parameter abrufen - String apiKey = paramMap.get("api.key"); - String baseUrl = paramMap.get("base.url"); + // Abrufen der Parameter + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); - // FessConfig abrufen - FessConfig fessConfig = ComponentUtil.getFessConfig(); + // Abrufen von FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); } } +Detaillierte Informationen zur Implementierung von ``storeData()`` (Ablauf +von Datenabruf, Skriptauswertung und Index-Registrierung) finden Sie unter +:doc:`datastore-plugin`. + Build und Installation -====================== +======================== Build ----- @@ -190,30 +286,35 @@ Build mvn clean package +Im Verzeichnis ``target/`` wird eine JAR-Datei erzeugt (z. B. +``fess-ds-example-15.8.0.jar``). + Installation ------------ -1. **Uber die Administrationsoberflache**: - - - "System" -> "Plugins" -> "Installieren" - - Plugin-Namen eingeben und installieren +1. **Über die Administrationsoberfläche**: -2. **Kommandozeile**: + - Öffnen Sie „System" → „Plugin" → „Installieren". + - Wählen Sie aus der Liste des Plugin-Repositorys aus, oder laden Sie die + erstellte JAR-Datei hoch, um sie zu installieren. - :: +2. **Manuell**: - ./bin/fess-plugin install fess-ds-example + - Kopieren Sie die JAR-Datei in das Verzeichnis + ``app/WEB-INF/plugin/``. + - Starten Sie |Fess| neu. -3. **Manuell**: - - - JAR-Datei in das ``plugins/``-Verzeichnis kopieren - - |Fess| neu starten +Details zum Installationsvorgang finden Sie unter +:doc:`../admin/plugin-guide`. Debugging ========= Log-Ausgabe ------------ +------------ + +|Fess| verwendet Log4j2. Der Logger wird über ``LogManager.getLogger()`` +abgerufen: .. code-block:: java @@ -224,19 +325,26 @@ Log-Ausgabe logger.info("Info message"); } +.. note:: + + Geben Sie keine sensiblen Informationen wie Passwörter oder Token in + Logs aus. + Entwicklungsmodus ------------------ +------------------ -Wahrend der Entwicklung kann |Fess| aus der IDE zum Debuggen gestartet werden: +Während der Entwicklung können Sie |Fess| aus der IDE starten und +debuggen: -1. ``FessBoot``-Klasse im Debug-Modus ausfuhren -2. Plugin-Quellcode in das Projekt einbinden -3. Breakpoints setzen +1. Führen Sie die Klasse ``org.codelibs.fess.FessBoot`` im Debug-Modus aus. +2. Nehmen Sie den Quellcode des Plugins in das Projekt auf. +3. Setzen Sie Breakpoints. -Veroffentlichte Plugins -======================= +Liste veröffentlichter Plugins +================================ -Wichtige vom |Fess|-Projekt veroffentlichte Plugins: +Im |Fess|-Projekt sind zahlreiche Plugins veröffentlicht. Im Folgenden +finden Sie repräsentative Beispiele (diese Liste ist nicht vollständig): .. list-table:: :header-rows: 1 @@ -244,26 +352,33 @@ Wichtige vom |Fess|-Projekt veroffentlichte Plugins: * - Plugin - Beschreibung - * - fess-ds-box - - Box.com-Konnektor - * - fess-ds-dropbox + * - ``fess-ds-box`` + - Box-Konnektor + * - ``fess-ds-dropbox`` - Dropbox-Konnektor - * - fess-ds-slack + * - ``fess-ds-slack`` - Slack-Konnektor - * - fess-ds-atlassian - - Confluence/Jira-Konnektor - * - fess-ds-git + * - ``fess-ds-atlassian`` + - JIRA-/Confluence-Konnektor + * - ``fess-ds-git`` - Git-Repository-Konnektor - * - fess-theme-* + * - ``fess-llm-openai`` + - OpenAI-LLM-Anbieter + * - ``fess-theme-*`` - Benutzerdefinierte Themes -Diese Plugins sind als Entwicklungsreferenz auf -`GitHub `__ veroffentlicht. +Darüber hinaus sind DataStore-Konnektoren wie ``fess-ds-csv`` / +``fess-ds-db`` / ``fess-ds-json`` / ``fess-ds-microsoft365`` / +``fess-ds-sharepoint`` sowie LLM-Anbieter wie ``fess-llm-ollama`` / +``fess-llm-gemini`` veröffentlicht. Diese Plugins sind als Referenz für die +Entwicklung auf `GitHub `__ veröffentlicht. Referenzinformationen -===================== +======================= - :doc:`datastore-plugin` - DataStore-Plugin-Entwicklung -- :doc:`script-engine-plugin` - Script-Engine-Plugin -- :doc:`webapp-plugin` - WebApp-Plugin +- :doc:`script-engine-plugin` - Skript-Engine-Plugin +- :doc:`webapp-plugin` - Webanwendungs-Plugin - :doc:`ingest-plugin` - Ingest-Plugin +- :doc:`theme-development` - Anpassung von Themes +- :doc:`../admin/plugin-guide` - Plugin-Installation diff --git a/en/15.8/dev/plugin-architecture.rst b/en/15.8/dev/plugin-architecture.rst index c47c986e6..291054491 100644 --- a/en/15.8/dev/plugin-architecture.rst +++ b/en/15.8/dev/plugin-architecture.rst @@ -5,45 +5,78 @@ Plugin Architecture Overview ======== -The |Fess| plugin system allows you to extend core functionality. -Plugins are distributed as JAR files and are loaded dynamically. +The |Fess| plugin system lets you extend core functionality. +Plugins are distributed as JAR files, and once added to the classpath, +their components are loaded by the DI container (Lasta Di) and +registered with the corresponding factory or manager. Plugin Types ============ -|Fess| supports the following types of plugins: +|Fess| determines the plugin type from the prefix of the artifact name +(``PluginHelper.ArtifactType``). The main types are as follows: .. list-table:: :header-rows: 1 - :widths: 25 75 + :widths: 20 25 55 * - Type + - Prefix - Description - * - DataStore - - Content retrieval from new data sources (Box, Slack, etc.) - * - Script Engine - - Support for new scripting languages + * - Data Store + - ``fess-ds-*`` + - Retrieves content from new data sources (Box, Slack, Git, etc.) * - Web App - - Web interface extensions + - ``fess-webapp-*`` + - Extends the web interface and search functionality + * - Script Engine + - ``fess-script-*`` + - Adds support for new scripting languages * - Ingest - - Data processing during indexing + - ``fess-ingest-*`` + - Processes documents during index registration + * - Theme + - ``fess-theme-*`` + - Customizes the design of the search screen + * - Thumbnail + - ``fess-thumbnail-*`` + - Adds new thumbnail generation methods + * - LLM + - ``fess-llm-*`` + - Adds LLM providers used for RAG/chat + * - Crawler + - ``fess-crawler-*`` + - Extends crawler clients Plugin Structure -================ +================= Basic Structure ---------------- +---------------- + +Taking `fess-ds-example `__, +the implementation template for Data Store plugins, as an example, a +plugin consists of an "implementation class" and a "DI registration +file": :: fess-ds-example/ ├── pom.xml - └── src/main/java/org/codelibs/fess/ds/example/ - ├── ExampleDataStore.java # DataStore implementation - └── ExampleDataStoreHandler.java # Handler (optional) + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # Data Store implementation + └── resources/ + └── fess_ds++.xml # DI component registration pom.xml Example ---------------- +----------------- + +The plugin is built as a jar with ``fess-parent`` as the parent POM. +Libraries such as ``fess`` and ``opensearch``, which are supplied by +the |Fess| core at runtime, are declared with ``provided`` scope. +Version numbers and build settings (formatter, license header, etc.) +are inherited from the parent POM. .. code-block:: xml @@ -59,86 +92,135 @@ pom.xml Example 15.8.0 jar - fess-ds-example - Example DataStore for Fess - - - 15.8.0 - 21 - + + org.codelibs.fess + fess-parent + 15.8.0 + + org.codelibs.fess fess - ${fess.version} + provided + + + org.opensearch + opensearch provided -Plugin Registration -=================== +.. note:: -DI Container Registration -------------------------- + On branches under development, the version has a ``-SNAPSHOT`` + suffix, such as ``15.8.0-SNAPSHOT``. Dependencies specific to the + plugin are declared as ordinary Maven dependencies. Since these are + not bundled with the |Fess| core, they must be distributed together + with the plugin. -Plugins are registered via configuration files such as ``fess_ds.xml``: +Plugin Registration +===================== -.. code-block:: xml +Registering with the DI Container +------------------------------------ - - - +Plugins register components using a DI configuration file whose name +ends in ``++``, such as ``fess_ds++.xml``. Lasta Di automatically +merges any file with a ``++`` suffix found on the classpath into the +corresponding configuration file in the |Fess| core (``fess_ds.xml`` +in this example). This mechanism lets a plugin add its own components +without modifying any file in the |Fess| core. -Auto Registration ------------------ +.. code-block:: xml -Many plugins auto-register using the ``@PostConstruct`` annotation: + + + + + + + + +The target file for merging differs depending on the plugin type. For +example, Script Engine plugins use ``fess_se++.xml``, Ingest plugins +use ``fess_ingest++.xml``, LLM providers use ``fess_llm++.xml``, and +Web App plugins use ``app++.xml``. + +Component Initialization +-------------------------- + +```` is a Lasta Di lifecycle setting +that specifies the method to invoke after the component is created. +In the case of a Data Store, the ``register()`` method provided by +``AbstractDataStore`` is invoked, which registers the component itself +with the ``DataStoreFactory``: .. code-block:: java - @PostConstruct + // Implementation in AbstractDataStore (normally no need to override) public void register() { - ComponentUtil.getDataStoreManager().add(this); + ComponentUtil.getDataStoreFactory().add(getName(), this); } +.. note:: + + Note that this is not Java's ``@PostConstruct`` annotation, but + initialization via the ```` element in the DI + configuration file. The name registered here is the return value of + ``getName()``, and this becomes the name used when selecting the + plugin in the admin console. + Plugin Lifecycle -================ +================== Initialization --------------- +---------------- -1. JAR file is loaded -2. DI container initializes components -3. ``@PostConstruct`` methods are called -4. Plugin is registered with the manager +1. The plugin JAR is added to the classpath +2. The DI container merges ``fess_*++.xml`` and creates the components +3. The method specified in ```` (e.g., ``register``) is + invoked +4. The plugin is registered with the corresponding factory/manager -Shutdown --------- +Termination +------------ -1. ``@PreDestroy`` methods are called (if defined) +1. When the DI container shuts down, the method specified in + ```` is invoked (if defined) 2. Resources are cleaned up +.. note:: + + In the case of a Data Store, an in-progress crawl has its stop flag + set by ``AbstractDataStore.stop()``, which allows the record + processing loop to terminate safely. + Dependencies -============ +============= -Fess Core Dependency --------------------- +Dependency on the Fess Core +----------------------------- + +Since classes in the |Fess| core are present on the server's classpath +at runtime, declare the dependency with ``provided`` scope (do not +bundle it into the plugin JAR). .. code-block:: xml org.codelibs.fess fess - ${fess.version} provided External Libraries ------------------- +-------------------- -Plugins can include their own dependency libraries: +A plugin can include its own dependency libraries: .. code-block:: xml @@ -148,72 +230,86 @@ Plugins can include their own dependency libraries: 1.0.0 -Dependency libraries can be distributed with the plugin JAR or -bundled into a fat JAR using Maven Shade Plugin. +Since these are not bundled with the |Fess| core, they must be +distributed together with the plugin. -Configuration Retrieval -======================= +Retrieving Configuration +========================== -Getting from FessConfig ------------------------ +Retrieving Parameters and FessConfig +-------------------------------------- + +In a Data Store's ``storeData()``, parameters configured in the admin +console are retrieved from ``DataStoreParams``. Use ``getAsString()`` +to retrieve values (since ``DataStoreParams`` does not implement +``Map``, ``get()`` does not return a string). |Fess| configuration +values can also be retrieved from ``ComponentUtil.getFessConfig()``: .. code-block:: java public class ExampleDataStore extends AbstractDataStore { @Override - public String getName() { - return "Example"; + protected String getName() { + // Used as the handler name. Convention is to return the class's simple name + return this.getClass().getSimpleName(); } @Override - protected void storeData(DataConfig dataConfig, IndexUpdateCallback callback, - Map paramMap, Map scriptMap, - Map defaultDataMap) { + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { - // Get parameters - String apiKey = paramMap.get("api.key"); - String baseUrl = paramMap.get("base.url"); + // Retrieve parameters + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); - // Get FessConfig - FessConfig fessConfig = ComponentUtil.getFessConfig(); + // Retrieve FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); } } +For details on how to implement ``storeData()`` (the flow of data +retrieval, script evaluation, and index registration), see +:doc:`datastore-plugin`. + Build and Installation -====================== +======================== Build ------ +------ :: mvn clean package -Installation ------------- - -1. **From Admin Console**: - - - Go to "System" -> "Plugins" -> "Install" - - Enter the plugin name and install +A JAR file (e.g., ``fess-ds-example-15.8.0.jar``) is generated in the +``target/`` directory. -2. **Command Line**: +Installation +------------- - :: +1. **From the admin console**: - ./bin/fess-plugin install fess-ds-example + - Open "System" -> "Plugin" -> "Install" + - Select from the list of plugin repositories, or upload and + install the JAR file you built -3. **Manual**: +2. **Manually**: - - Copy JAR file to ``plugins/`` directory + - Copy the JAR file to the ``app/WEB-INF/plugin/`` directory - Restart |Fess| +For details on the installation procedure, see +:doc:`../admin/plugin-guide`. + Debugging -========= +========== + +Logging +-------- -Log Output ----------- +|Fess| uses Log4j2. Obtain a logger with ``LogManager.getLogger()``: .. code-block:: java @@ -224,19 +320,25 @@ Log Output logger.info("Info message"); } +.. note:: + + Do not output sensitive information such as passwords or tokens to + the log. + Development Mode ----------------- +------------------ -During development, you can debug |Fess| from your IDE: +During development, you can start |Fess| from your IDE for debugging: -1. Debug run the ``FessBoot`` class -2. Include the plugin source in your project +1. Debug-run the ``org.codelibs.fess.FessBoot`` class +2. Include the plugin's source code in the project 3. Set breakpoints -Published Plugins -================= +List of Published Plugins +=========================== -Main plugins published by the |Fess| project: +Many plugins are published by the |Fess| project. The following are +representative examples (this is not an exhaustive list): .. list-table:: :header-rows: 1 @@ -244,27 +346,35 @@ Main plugins published by the |Fess| project: * - Plugin - Description - * - fess-ds-box - - Box.com connector - * - fess-ds-dropbox + * - ``fess-ds-box`` + - Box connector + * - ``fess-ds-dropbox`` - Dropbox connector - * - fess-ds-slack + * - ``fess-ds-slack`` - Slack connector - * - fess-ds-atlassian - - Confluence/Jira connector - * - fess-ds-git + * - ``fess-ds-atlassian`` + - JIRA / Confluence connector + * - ``fess-ds-git`` - Git repository connector - * - fess-theme-* + * - ``fess-llm-openai`` + - OpenAI LLM provider + * - ``fess-theme-*`` - Custom themes -These plugins are available on -`GitHub `__ as development references. +In addition, Data Store connectors such as ``fess-ds-csv`` / +``fess-ds-db`` / ``fess-ds-json`` / ``fess-ds-microsoft365`` / +``fess-ds-sharepoint``, and LLM providers such as ``fess-llm-ollama`` / +``fess-llm-gemini``, are also published. These plugins are published +on `GitHub `__ as a reference for +development. Reference -========= - -- :doc:`datastore-plugin` - DataStore Plugin Development -- :doc:`script-engine-plugin` - Script Engine Plugin -- :doc:`webapp-plugin` - Web App Plugin -- :doc:`ingest-plugin` - Ingest Plugin - +========== + +- :doc:`datastore-plugin` - Data Store plugin development +- :doc:`script-engine-plugin` - Script Engine plugin +- :doc:`webapp-plugin` - Web App plugin +- :doc:`ingest-plugin` - Ingest plugin +- :doc:`theme-development` - Theme customization +- :doc:`../admin/plugin-guide` - Plugin installation + diff --git a/es/15.8/dev/plugin-architecture.rst b/es/15.8/dev/plugin-architecture.rst index c89b5499d..08ea39550 100644 --- a/es/15.8/dev/plugin-architecture.rst +++ b/es/15.8/dev/plugin-architecture.rst @@ -1,50 +1,85 @@ -================================== +========================== Arquitectura de Plugins -================================== +========================== -Vision General +Visión General ============== -El sistema de plugins de |Fess| permite extender la funcionalidad principal. -Los plugins se distribuyen como archivos JAR y se cargan dinamicamente. +El sistema de plugins de |Fess| permite ampliar la funcionalidad +principal. Los plugins se distribuyen como archivos JAR y, al añadirse +al classpath, el contenedor DI (Lasta Di) carga los componentes y los +registra en la fábrica o el gestor correspondiente. Tipos de Plugins ================ -|Fess| soporta los siguientes tipos de plugins: +|Fess| determina el tipo de plugin según el prefijo del nombre del +artefacto (``PluginHelper.ArtifactType``). Los tipos principales son los +siguientes: .. list-table:: :header-rows: 1 - :widths: 25 75 + :widths: 20 25 55 * - Tipo - - Descripcion - * - Almacen de datos - - Obtencion de contenido desde nuevas fuentes de datos (Box, Slack, etc.) + - Prefijo + - Descripción + * - Almacén de datos + - ``fess-ds-*`` + - Obtención de contenido desde nuevas fuentes de datos (Box, Slack, + Git, etc.) + * - Aplicación web + - ``fess-webapp-*`` + - Ampliación de la interfaz web o de las funciones de búsqueda * - Motor de scripts + - ``fess-script-*`` - Soporte para nuevos lenguajes de script - * - Aplicacion web - - Extension de la interfaz web * - Ingest - - Procesamiento de datos durante la indexacion - -Estructura de un Plugin -======================= - -Estructura Basica + - ``fess-ingest-*`` + - Procesamiento de documentos durante el registro en el índice + * - Tema + - ``fess-theme-*`` + - Personalización del diseño de la pantalla de búsqueda + * - Miniatura + - ``fess-thumbnail-*`` + - Adición de métodos de generación de miniaturas + * - LLM + - ``fess-llm-*`` + - Adición de proveedores de LLM utilizados en RAG/chat + * - Rastreador + - ``fess-crawler-*`` + - Ampliación de clientes de rastreador + +Estructura del Plugin +====================== + +Estructura Básica ----------------- +Tomando como ejemplo `fess-ds-example +`__, la plantilla de +implementación de un plugin de almacén de datos, un plugin se compone de +una «clase de implementación» y un «archivo de registro DI»: + :: fess-ds-example/ ├── pom.xml - └── src/main/java/org/codelibs/fess/ds/example/ - ├── ExampleDataStore.java # Implementacion del almacen de datos - └── ExampleDataStoreHandler.java # Manejador (opcional) + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # Implementación del almacén de datos + └── resources/ + └── fess_ds++.xml # Registro de componentes DI Ejemplo de pom.xml ------------------ +Los plugins se construyen como jar con ``fess-parent`` como POM padre. +Las bibliotecas que se proporcionan en tiempo de ejecución desde el +propio |Fess|, como ``fess`` u ``opensearch``, se declaran con el ámbito +``provided``. El número de versión y la configuración de compilación +(formateador, cabeceras de licencia, etc.) se heredan del POM padre. + .. code-block:: xml @@ -59,84 +94,134 @@ Ejemplo de pom.xml 15.8.0 jar - fess-ds-example - Example DataStore for Fess - - - 15.8.0 - 21 - + + org.codelibs.fess + fess-parent + 15.8.0 + + org.codelibs.fess fess - ${fess.version} + provided + + + org.opensearch + opensearch provided -Registro de Plugins -=================== +.. note:: -Registro en el Contenedor DI ----------------------------- + En las ramas en desarrollo, la versión llevará el sufijo + ``-SNAPSHOT``, como en ``15.8.0-SNAPSHOT``. Las bibliotecas de + dependencia propias del plugin se declaran como dependencias Maven + normales. Puesto que no están incluidas en el propio |Fess|, deben + distribuirse junto con el plugin. -Los plugins se registran en archivos de configuracion como ``fess_ds.xml``: +Registro del Plugin +==================== -.. code-block:: xml +Registro en el Contenedor DI +----------------------------- - - - +Los plugins registran sus componentes mediante un archivo de +configuración DI cuyo nombre termina en ``++``, como ``fess_ds++.xml``. +Lasta Di combina automáticamente los archivos con el sufijo ``++`` +encontrados en el classpath con el archivo de configuración +correspondiente del propio |Fess| (en este ejemplo, ``fess_ds.xml``). +Gracias a este mecanismo, el plugin puede añadir sus propios componentes +sin modificar los archivos del propio |Fess|. -Registro Automatico -------------------- +.. code-block:: xml -Muchos plugins se registran automaticamente con la anotacion ``@PostConstruct``: + + + + + + + + +Según el tipo de plugin, el archivo de destino de la fusión varía. Por +ejemplo, el motor de scripts utiliza ``fess_se++.xml``, Ingest utiliza +``fess_ingest++.xml``, los proveedores de LLM utilizan +``fess_llm++.xml``, y las aplicaciones web utilizan ``app++.xml``. + +Inicialización del Componente +------------------------------- + +```` es una configuración del ciclo de +vida de Lasta Di que especifica el método que se invoca tras la creación +del componente. En el caso de un almacén de datos, se invoca el método +``register()`` que posee ``AbstractDataStore``, y este se registra a sí +mismo en ``DataStoreFactory``: .. code-block:: java - @PostConstruct + // Implementación de AbstractDataStore (normalmente no requiere sobrescritura) public void register() { - ComponentUtil.getDataStoreManager().add(this); + ComponentUtil.getDataStoreFactory().add(getName(), this); } +.. note:: + + Esto no es la anotación ``@PostConstruct`` de Java, sino una + inicialización mediante el elemento ```` del archivo + de configuración DI. El nombre que se registra es el valor devuelto + por ``getName()``, y es el nombre que se selecciona al elegir el + plugin en la consola de administración. + Ciclo de Vida del Plugin -======================== +========================== -Inicializacion --------------- +Inicialización +--------------- -1. Se carga el archivo JAR -2. El contenedor DI inicializa los componentes -3. Se llama al metodo ``@PostConstruct`` -4. El plugin se registra en el gestor +1. El JAR del plugin se añade al classpath. +2. El contenedor DI combina ``fess_*++.xml`` y crea los componentes. +3. Se invoca el método especificado en ```` (por ejemplo, + ``register``). +4. El plugin se registra en la fábrica o el gestor correspondiente. -Finalizacion ------------- +Finalización +------------- -1. Se llama al metodo ``@PreDestroy`` (si esta definido) -2. Limpieza de recursos +1. Al finalizar el contenedor DI, se invoca el método especificado en + ```` (si está definido). +2. Limpieza de recursos. + +.. note:: + + En el caso de un almacén de datos, ``AbstractDataStore.stop()`` + activa un indicador de detención en el rastreo en curso, y el bucle + de procesamiento de registros finaliza de forma segura. Dependencias ============ -Dependencia con Fess Principal ------------------------------- +Dependencia con el Núcleo de Fess +----------------------------------- + +Puesto que las clases del propio |Fess| están presentes en el classpath +del servidor en tiempo de ejecución, se declaran como dependencia con el +ámbito ``provided`` (no se incluyen en el JAR del plugin). .. code-block:: xml org.codelibs.fess fess - ${fess.version} provided Bibliotecas Externas --------------------- +---------------------- Los plugins pueden incluir sus propias bibliotecas de dependencia: @@ -148,72 +233,88 @@ Los plugins pueden incluir sus propias bibliotecas de dependencia: 1.0.0 -Las bibliotecas de dependencia se distribuyen junto con el JAR del plugin o -se crea un fat JAR usando Maven Shade Plugin. +Puesto que estas no están incluidas en el propio |Fess|, deben +distribuirse junto con el plugin. -Obtencion de Configuracion -========================== +Obtención de la Configuración +================================ -Obtener desde FessConfig ------------------------- +Obtención de Parámetros y de FessConfig +------------------------------------------ + +En el método ``storeData()`` del almacén de datos, los parámetros +configurados en la consola de administración se obtienen desde +``DataStoreParams``. Para obtener los valores, utilice +``getAsString()`` (dado que ``DataStoreParams`` no implementa ``Map``, +``get()`` no devuelve una cadena). Además, los valores de configuración +de |Fess| se pueden obtener desde ``ComponentUtil.getFessConfig()``: .. code-block:: java public class ExampleDataStore extends AbstractDataStore { @Override - public String getName() { - return "Example"; + protected String getName() { + // Se utiliza como nombre del manejador. La convención es devolver el nombre simple de la clase + return this.getClass().getSimpleName(); } @Override - protected void storeData(DataConfig dataConfig, IndexUpdateCallback callback, - Map paramMap, Map scriptMap, - Map defaultDataMap) { + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { - // Obtener parametros - String apiKey = paramMap.get("api.key"); - String baseUrl = paramMap.get("base.url"); + // Obtención de los parámetros + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); - // Obtener FessConfig - FessConfig fessConfig = ComponentUtil.getFessConfig(); + // Obtención de FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); } } -Construccion e Instalacion -========================== +Para más detalles sobre la implementación de ``storeData()`` (el flujo +de obtención de datos, evaluación de scripts y registro en el índice), +consulte :doc:`datastore-plugin`. -Construccion ------------- +Construcción e Instalación +============================= + +Construcción +------------- :: mvn clean package -Instalacion ------------ +En el directorio ``target/`` se generará un archivo JAR (por ejemplo, +``fess-ds-example-15.8.0.jar``). -1. **Desde la pantalla de administracion**: - - - "Sistema" -> "Plugins" -> "Instalar" - - Ingrese el nombre del plugin e instale - -2. **Linea de comandos**: +Instalación +------------ - :: +1. **Desde la consola de administración**: - ./bin/fess-plugin install fess-ds-example + - Abra «Sistema» → «Plugin» → «Instalar» + - Seleccione de la lista del repositorio de plugins, o suba el + archivo JAR compilado para instalarlo -3. **Manual**: +2. **Manual**: - - Copie el archivo JAR al directorio ``plugins/`` + - Copie el archivo JAR al directorio ``app/WEB-INF/plugin/`` - Reinicie |Fess| -Depuracion +Para más detalles sobre el procedimiento de instalación, consulte +:doc:`../admin/plugin-guide`. + +Depuración ========== -Salida de Registros -------------------- +Salida de Logs +--------------- + +|Fess| utiliza Log4j2. El logger se obtiene mediante +``LogManager.getLogger()``: .. code-block:: java @@ -224,46 +325,60 @@ Salida de Registros logger.info("Info message"); } +.. note:: + + No registre en los logs información sensible, como contraseñas o + tokens. + Modo de Desarrollo ------------------- +-------------------- -Durante el desarrollo, puede depurar iniciando |Fess| desde el IDE: +Durante el desarrollo, puede depurar |Fess| iniciándolo desde el IDE: -1. Ejecute la clase ``FessBoot`` en modo de depuracion -2. Incluya el codigo fuente del plugin en el proyecto -3. Establezca puntos de interrupcion +1. Ejecute en modo depuración la clase ``org.codelibs.fess.FessBoot``. +2. Incluya el código fuente del plugin en el proyecto. +3. Establezca puntos de interrupción. -Lista de Plugins Publicos -========================= +Lista de Plugins Públicos +============================ -Principales plugins publicados por el proyecto |Fess|: +En el proyecto |Fess| se publican numerosos plugins. A continuación se +muestran algunos ejemplos representativos (esta lista no es exhaustiva): .. list-table:: :header-rows: 1 :widths: 30 70 * - Plugin - - Descripcion - * - fess-ds-box - - Conector de Box.com - * - fess-ds-dropbox + - Descripción + * - ``fess-ds-box`` + - Conector de Box + * - ``fess-ds-dropbox`` - Conector de Dropbox - * - fess-ds-slack + * - ``fess-ds-slack`` - Conector de Slack - * - fess-ds-atlassian - - Conector de Confluence/Jira - * - fess-ds-git - - Conector de repositorio Git - * - fess-theme-* - - Temas personalizados - -Estos plugins estan disponibles como referencia de desarrollo en -`GitHub `__. - -Informacion de Referencia -========================= - -- :doc:`datastore-plugin` - Desarrollo de plugins de almacen de datos -- :doc:`script-engine-plugin` - Plugins de motor de scripts -- :doc:`webapp-plugin` - Plugins de aplicacion web -- :doc:`ingest-plugin` - Plugins Ingest + * - ``fess-ds-atlassian`` + - Conector de JIRA / Confluence + * - ``fess-ds-git`` + - Conector de repositorios Git + * - ``fess-llm-openai`` + - Proveedor de LLM OpenAI + * - ``fess-theme-*`` + - Tema personalizado + +Además de estos, también se publican conectores de almacén de datos como +``fess-ds-csv`` / ``fess-ds-db`` / ``fess-ds-json`` / +``fess-ds-microsoft365`` / ``fess-ds-sharepoint``, y proveedores de LLM +como ``fess-llm-ollama`` / ``fess-llm-gemini``. Estos plugins se +publican en `GitHub `__ como referencia +para el desarrollo. + +Información de Referencia +============================ + +- :doc:`datastore-plugin` - Desarrollo de plugins de almacén de datos +- :doc:`script-engine-plugin` - Plugin de motor de scripts +- :doc:`webapp-plugin` - Plugin de aplicación web +- :doc:`ingest-plugin` - Plugin de Ingest +- :doc:`theme-development` - Personalización de temas +- :doc:`../admin/plugin-guide` - Instalación de plugins diff --git a/fr/15.8/dev/plugin-architecture.rst b/fr/15.8/dev/plugin-architecture.rst index 79376cd5a..7ba73c626 100644 --- a/fr/15.8/dev/plugin-architecture.rst +++ b/fr/15.8/dev/plugin-architecture.rst @@ -1,50 +1,84 @@ -================================== +========================= Architecture des plugins -================================== +========================= -Vue d'ensemble -============== +Aperçu +====== -Le systeme de plugins de |Fess| permet d'etendre les fonctionnalites de base. -Les plugins sont distribues sous forme de fichiers JAR et charges dynamiquement. +Le système de plugins de |Fess| permet d'étendre les fonctionnalités du cœur. +Les plugins sont distribués sous forme de fichiers JAR ; lorsqu'ils sont +ajoutés au classpath, leurs composants sont chargés par le conteneur DI +(Lasta Di) puis enregistrés auprès de la fabrique ou du gestionnaire +correspondant. Types de plugins -================ +================= -|Fess| supporte les types de plugins suivants: +|Fess| détermine le type d'un plugin à partir du préfixe du nom de +l'artefact (``PluginHelper.ArtifactType``). Les principaux types sont les +suivants : .. list-table:: :header-rows: 1 - :widths: 25 75 + :widths: 20 25 55 * - Type + - Préfixe - Description * - DataStore - - Recuperation de contenu depuis de nouvelles sources de donnees (Box, Slack, etc.) - * - Script Engine - - Support de nouveaux langages de script - * - WebApp - - Extension de l'interface web + - ``fess-ds-*`` + - Récupération de contenu depuis de nouvelles sources de données (Box, Slack, Git, etc.) + * - Application Web + - ``fess-webapp-*`` + - Extension de l'interface Web ou des fonctionnalités de recherche + * - Moteur de script + - ``fess-script-*`` + - Prise en charge de nouveaux langages de script * - Ingest - - Traitement des donnees lors de l'indexation + - ``fess-ingest-*`` + - Traitement des documents lors de leur enregistrement dans l'index + * - Thème + - ``fess-theme-*`` + - Personnalisation du design de l'écran de recherche + * - Miniature + - ``fess-thumbnail-*`` + - Ajout de méthodes de génération de miniatures + * - LLM + - ``fess-llm-*`` + - Ajout de fournisseurs LLM utilisés pour le RAG/chat + * - Crawler + - ``fess-crawler-*`` + - Extension des clients du crawler Structure d'un plugin -===================== +====================== Structure de base ----------------- +En prenant comme exemple `fess-ds-example `__, +le modèle d'implémentation d'un plugin DataStore, un plugin se compose d'une +« classe d'implémentation » et d'un « fichier d'enregistrement DI » : + :: fess-ds-example/ ├── pom.xml - └── src/main/java/org/codelibs/fess/ds/example/ - ├── ExampleDataStore.java # Implementation du DataStore - └── ExampleDataStoreHandler.java # Handler (optionnel) + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # Implémentation du DataStore + └── resources/ + └── fess_ds++.xml # Enregistrement du composant DI Exemple de pom.xml ------------------ +Le plugin est construit comme un jar ayant ``fess-parent`` pour POM parent. +Les bibliothèques telles que ``fess`` ou ``opensearch``, fournies à +l'exécution par |Fess| lui-même, doivent être déclarées avec la portée +``provided``. Le numéro de version et les paramètres de build (formateur, +en-têtes de licence, etc.) sont hérités du POM parent. + .. code-block:: xml @@ -59,86 +93,134 @@ Exemple de pom.xml 15.8.0 jar - fess-ds-example - Example DataStore for Fess - - - 15.8.0 - 21 - + + org.codelibs.fess + fess-parent + 15.8.0 + + org.codelibs.fess fess - ${fess.version} + provided + + + org.opensearch + opensearch provided +.. note:: + + Sur les branches en cours de développement, la version comporte le + suffixe ``-SNAPSHOT``, par exemple ``15.8.0-SNAPSHOT``. Les bibliothèques + dépendantes propres au plugin sont déclarées comme des dépendances Maven + classiques. Comme elles ne sont pas incluses dans |Fess| lui-même, elles + doivent être distribuées avec le plugin. + Enregistrement du plugin -======================== +========================= Enregistrement dans le conteneur DI ------------------------------------ +------------------------------------ -Les plugins sont enregistres dans des fichiers de configuration comme ``fess_ds.xml``: +Un plugin enregistre ses composants dans un fichier de configuration DI dont +le nom se termine par ``++``, comme ``fess_ds++.xml``. Lasta Di fusionne +automatiquement tout fichier suffixé par ``++`` trouvé sur le classpath avec +le fichier de configuration correspondant de |Fess| lui-même (``fess_ds.xml`` +dans cet exemple). Ce mécanisme permet à un plugin d'ajouter ses propres +composants sans modifier les fichiers de |Fess| lui-même. .. code-block:: xml - - - - -Enregistrement automatique --------------------------- - -De nombreux plugins s'enregistrent automatiquement avec l'annotation ``@PostConstruct``: + + + + + + + + +Le fichier cible de la fusion diffère selon le type de plugin. Par exemple, +un moteur de script utilise ``fess_se++.xml``, un plugin Ingest utilise +``fess_ingest++.xml``, un fournisseur LLM utilise ``fess_llm++.xml``, et une +application Web utilise ``app++.xml``. + +Initialisation du composant +---------------------------- + +```` est un paramètre de cycle de vie de +Lasta Di indiquant la méthode à appeler après la création du composant. Dans +le cas d'un DataStore, la méthode ``register()`` fournie par +``AbstractDataStore`` est appelée et enregistre celui-ci auprès de +``DataStoreFactory`` : .. code-block:: java - @PostConstruct + // Implémentation fournie par AbstractDataStore (il n'est généralement pas nécessaire de la surcharger) public void register() { - ComponentUtil.getDataStoreManager().add(this); + ComponentUtil.getDataStoreFactory().add(getName(), this); } +.. note:: + + Il ne s'agit pas de l'annotation Java ``@PostConstruct``, mais d'une + initialisation réalisée via l'élément ```` du fichier de + configuration DI. Le nom enregistré correspond à la valeur de retour de + ``getName()`` ; c'est ce nom qui sera utilisé pour sélectionner le plugin + dans l'écran d'administration. + Cycle de vie du plugin -====================== +======================= Initialisation -------------- -1. Le fichier JAR est charge -2. Le conteneur DI initialise les composants -3. Les methodes ``@PostConstruct`` sont appelees -4. Le plugin est enregistre dans le gestionnaire +1. Le fichier JAR du plugin est ajouté au classpath. +2. Le conteneur DI fusionne les fichiers ``fess_*++.xml`` et génère les composants. +3. La méthode indiquée dans ```` (par exemple ``register``) est appelée. +4. Le plugin est enregistré auprès de la fabrique ou du gestionnaire correspondant. + +Arrêt +----- + +1. À l'arrêt du conteneur DI, la méthode indiquée dans ```` est + appelée (si elle est définie). +2. Nettoyage des ressources. + +.. note:: -Terminaison ------------ + Dans le cas d'un DataStore, ``AbstractDataStore.stop()`` positionne un + indicateur d'arrêt sur l'exploration en cours, ce qui permet à la boucle + de traitement des enregistrements de se terminer de manière sûre. -1. Les methodes ``@PreDestroy`` sont appelees (si definies) -2. Nettoyage des ressources +Dépendances +============ -Dependances -=========== +Dépendance envers le cœur de Fess +----------------------------------- -Dependance avec Fess --------------------- +Les classes du cœur de |Fess| étant présentes sur le classpath du serveur au +moment de l'exécution, elles sont déclarées comme dépendance avec la portée +``provided`` (elles ne doivent pas être incluses dans le JAR du plugin). .. code-block:: xml org.codelibs.fess fess - ${fess.version} provided -Bibliotheques externes ----------------------- +Bibliothèques externes +----------------------- -Les plugins peuvent inclure leurs propres dependances: +Un plugin peut inclure ses propres bibliothèques dépendantes : .. code-block:: xml @@ -148,40 +230,52 @@ Les plugins peuvent inclure leurs propres dependances: 1.0.0 -Les bibliotheques dependantes peuvent etre distribuees avec le JAR du plugin, -ou vous pouvez creer un fat JAR avec Maven Shade Plugin. +Comme elles ne sont pas incluses dans |Fess| lui-même, elles doivent être +distribuées avec le plugin. + +Récupération de la configuration +================================== -Recuperation de la configuration -================================ +Récupération des paramètres et de FessConfig +---------------------------------------------- -Recuperation depuis FessConfig ------------------------------- +Dans la méthode ``storeData()`` d'un DataStore, les paramètres configurés +dans l'écran d'administration sont récupérés depuis ``DataStoreParams``. +Utilisez ``getAsString()`` pour récupérer les valeurs (``DataStoreParams`` +n'implémentant pas ``Map``, ``get()`` ne retourne pas de chaîne de +caractères). Les valeurs de configuration de |Fess| peuvent également être +récupérées via ``ComponentUtil.getFessConfig()`` : .. code-block:: java public class ExampleDataStore extends AbstractDataStore { @Override - public String getName() { - return "Example"; + protected String getName() { + // Utilisé comme nom de handler. Il est d'usage de retourner le nom simple de la classe + return this.getClass().getSimpleName(); } @Override - protected void storeData(DataConfig dataConfig, IndexUpdateCallback callback, - Map paramMap, Map scriptMap, - Map defaultDataMap) { + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { - // Recuperation des parametres - String apiKey = paramMap.get("api.key"); - String baseUrl = paramMap.get("base.url"); + // Récupération des paramètres + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); - // Recuperation de FessConfig - FessConfig fessConfig = ComponentUtil.getFessConfig(); + // Récupération de FessConfig + final FessConfig fessConfig = ComponentUtil.getFessConfig(); } } +Pour plus de détails sur l'implémentation de ``storeData()`` (récupération +des données, évaluation du script, enregistrement dans l'index), reportez-vous +à :doc:`datastore-plugin`. + Build et installation -===================== +====================== Build ----- @@ -190,30 +284,33 @@ Build mvn clean package +Le fichier JAR (par exemple ``fess-ds-example-15.8.0.jar``) est généré dans +le répertoire ``target/``. + Installation ------------ -1. **Depuis l'interface d'administration**: - - - "Systeme" -> "Plugins" -> "Installer" - - Entrer le nom du plugin et installer - -2. **Ligne de commande**: +1. **Depuis l'écran d'administration** : - :: + - Ouvrez « Système » → « Plugin » → « Installer ». + - Sélectionnez un plugin dans la liste du dépôt de plugins, ou téléversez + le fichier JAR construit pour l'installer. - ./bin/fess-plugin install fess-ds-example +2. **Manuellement** : -3. **Manuellement**: + - Copiez le fichier JAR dans le répertoire ``app/WEB-INF/plugin/``. + - Redémarrez |Fess|. - - Copier le fichier JAR dans le repertoire ``plugins/`` - - Redemarrer |Fess| +Pour plus de détails sur la procédure d'installation, reportez-vous à +:doc:`../admin/plugin-guide`. -Debogage +Débogage ======== -Sortie de logs --------------- +Journalisation +--------------- + +|Fess| utilise Log4j2. Le logger s'obtient avec ``LogManager.getLogger()`` : .. code-block:: java @@ -224,19 +321,26 @@ Sortie de logs logger.info("Info message"); } -Mode developpement ------------------- +.. note:: -En developpement, vous pouvez lancer |Fess| depuis l'IDE pour deboguer: + N'écrivez pas d'informations sensibles telles que mots de passe ou + jetons dans les journaux. -1. Executer la classe ``FessBoot`` en mode debug -2. Inclure les sources du plugin dans le projet -3. Definir des points d'arret +Mode de développement +----------------------- -Liste des plugins publies -========================= +Lors du développement, vous pouvez démarrer |Fess| depuis un IDE pour le +déboguer : + +1. Exécutez la classe ``org.codelibs.fess.FessBoot`` en mode débogage. +2. Incluez les sources du plugin dans le projet. +3. Définissez des points d'arrêt. + +Liste des plugins publiés +========================== -Principaux plugins publies par le projet |Fess|: +De nombreux plugins sont publiés par le projet |Fess|. Voici quelques +exemples représentatifs (cette liste n'est pas exhaustive) : .. list-table:: :header-rows: 1 @@ -244,25 +348,34 @@ Principaux plugins publies par le projet |Fess|: * - Plugin - Description - * - fess-ds-box - - Connecteur Box.com - * - fess-ds-dropbox + * - ``fess-ds-box`` + - Connecteur Box + * - ``fess-ds-dropbox`` - Connecteur Dropbox - * - fess-ds-slack + * - ``fess-ds-slack`` - Connecteur Slack - * - fess-ds-atlassian - - Connecteur Confluence/Jira - * - fess-ds-git - - Connecteur de depot Git - * - fess-theme-* - - Themes personnalises - -Ces plugins sont publies sur `GitHub `__ comme reference de developpement. - -Informations complementaires -============================ - -- :doc:`datastore-plugin` - Developpement de plugins DataStore -- :doc:`script-engine-plugin` - Plugins Script Engine -- :doc:`webapp-plugin` - Plugins WebApp -- :doc:`ingest-plugin` - Plugins Ingest + * - ``fess-ds-atlassian`` + - Connecteur JIRA / Confluence + * - ``fess-ds-git`` + - Connecteur de dépôt Git + * - ``fess-llm-openai`` + - Fournisseur LLM OpenAI + * - ``fess-theme-*`` + - Thèmes personnalisés + +D'autres connecteurs DataStore tels que ``fess-ds-csv`` / ``fess-ds-db`` / +``fess-ds-json`` / ``fess-ds-microsoft365`` / ``fess-ds-sharepoint``, ainsi +que des fournisseurs LLM tels que ``fess-llm-ollama`` / ``fess-llm-gemini``, +sont également publiés. Ces plugins sont disponibles sur +`GitHub `__ comme référence pour le +développement. + +Informations complémentaires +============================= + +- :doc:`datastore-plugin` - Développement de plugins DataStore +- :doc:`script-engine-plugin` - Plugin de moteur de script +- :doc:`webapp-plugin` - Plugin d'application Web +- :doc:`ingest-plugin` - Plugin Ingest +- :doc:`theme-development` - Personnalisation des thèmes +- :doc:`../admin/plugin-guide` - Installation des plugins diff --git a/ja/15.8/dev/plugin-architecture.rst b/ja/15.8/dev/plugin-architecture.rst index 7ec0a1cff..5d3282570 100644 --- a/ja/15.8/dev/plugin-architecture.rst +++ b/ja/15.8/dev/plugin-architecture.rst @@ -6,27 +6,47 @@ ==== |Fess| のプラグインシステムにより、コア機能を拡張できます。 -プラグインはJARファイルとして配布され、動的にロードされます。 +プラグインは JAR ファイルとして配布され、クラスパスに追加されると +DI コンテナ(Lasta Di)によってコンポーネントが読み込まれ、対応する +ファクトリーやマネージャーへ登録されます。 プラグインの種類 ================ -|Fess| は以下の種類のプラグインをサポートしています: +|Fess| は、アーティファクト名のプレフィックスによってプラグインの種類を +判別します(``PluginHelper.ArtifactType``)。主な種類は以下のとおりです: .. list-table:: :header-rows: 1 - :widths: 25 75 + :widths: 20 25 55 * - 種類 + - プレフィックス - 説明 * - データストア - - 新しいデータソースからのコンテンツ取得（Box、Slack等） + - ``fess-ds-*`` + - 新しいデータソースからのコンテンツ取得(Box、Slack、Git 等) + * - Webアプリ + - ``fess-webapp-*`` + - Web インターフェースや検索機能の拡張 * - スクリプトエンジン + - ``fess-script-*`` - 新しいスクリプト言語のサポート - * - Webアプリ - - Webインターフェースの拡張 * - Ingest - - インデックス時のデータ加工 + - ``fess-ingest-*`` + - インデックス登録時のドキュメント加工 + * - テーマ + - ``fess-theme-*`` + - 検索画面デザインのカスタマイズ + * - サムネイル + - ``fess-thumbnail-*`` + - サムネイル生成方式の追加 + * - LLM + - ``fess-llm-*`` + - RAG/チャットで使用する LLM プロバイダーの追加 + * - クローラー + - ``fess-crawler-*`` + - クローラークライアントの拡張 プラグイン構造 ============== @@ -34,17 +54,28 @@ 基本構造 -------- +データストアプラグインの実装テンプレートである +`fess-ds-example `__ を例にすると、 +プラグインは「実装クラス」と「DI 登録ファイル」で構成されます: + :: fess-ds-example/ ├── pom.xml - └── src/main/java/org/codelibs/fess/ds/example/ - ├── ExampleDataStore.java # データストア実装 - └── ExampleDataStoreHandler.java # ハンドラ（オプション） + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # データストア実装 + └── resources/ + └── fess_ds++.xml # DIコンポーネント登録 pom.xmlの例 ----------- +プラグインは ``fess-parent`` を親 POM とする jar としてビルドします。 +``fess`` や ``opensearch`` など、実行時に |Fess| 本体から提供されるライブラリは +``provided`` スコープで宣言します。バージョン番号やビルド設定(フォーマッター・ +ライセンスヘッダーなど)は親 POM から継承されます。 + .. code-block:: xml @@ -59,79 +90,118 @@ pom.xmlの例 15.8.0 jar - fess-ds-example - Example DataStore for Fess - - - 15.8.0 - 21 - + + org.codelibs.fess + fess-parent + 15.8.0 + + org.codelibs.fess fess - ${fess.version} + provided + + + org.opensearch + opensearch provided +.. note:: + + 開発中のブランチでは、バージョンは ``15.8.0-SNAPSHOT`` のように ``-SNAPSHOT`` 付きに + なります。プラグイン固有の依存ライブラリは通常の Maven 依存関係として宣言します。 + これらは |Fess| 本体には含まれないため、プラグインと一緒に配布する必要があります。 + プラグインの登録 ================ DIコンテナへの登録 ------------------ -プラグインは ``fess_ds.xml`` などの設定ファイルで登録されます: +プラグインは、``fess_ds++.xml`` のように末尾が ``++`` の DI 設定ファイルで +コンポーネントを登録します。Lasta Di は、クラスパス上に見つかった ``++`` 付きの +ファイルを、|Fess| 本体の対応する設定ファイル(この例では ``fess_ds.xml``)へ +自動的にマージします。この仕組みにより、プラグインは |Fess| 本体のファイルを +編集することなく、自身のコンポーネントを追加できます。 .. code-block:: xml - - - - -自動登録 --------- - -多くのプラグインは、``@PostConstruct`` アノテーションで自動登録します: + + + + + + + + +プラグインの種類ごとにマージ先のファイルが異なります。例えばスクリプトエンジンは +``fess_se++.xml``、Ingest は ``fess_ingest++.xml``、LLM プロバイダーは +``fess_llm++.xml``、Web アプリは ``app++.xml`` を使用します。 + +コンポーネントの初期化 +---------------------- + +```` は、コンポーネント生成後に呼び出す +メソッドを指定する Lasta Di のライフサイクル設定です。データストアの場合、 +``AbstractDataStore`` が持つ ``register()`` メソッドが呼び出され、 +自身が ``DataStoreFactory`` に登録されます: .. code-block:: java - @PostConstruct + // AbstractDataStore の実装(通常はオーバーライド不要) public void register() { - ComponentUtil.getDataStoreManager().add(this); + ComponentUtil.getDataStoreFactory().add(getName(), this); } +.. note:: + + これは Java の ``@PostConstruct`` アノテーションではなく、DI 設定ファイルの + ```` 要素による初期化です。登録される名前は ``getName()`` の + 戻り値であり、管理画面でプラグインを選択する際の名前になります。 + プラグインのライフサイクル ========================== 初期化 ------ -1. JARファイルがロードされる -2. DIコンテナがコンポーネントを初期化 -3. ``@PostConstruct`` メソッドが呼び出される -4. プラグインがマネージャに登録される +1. プラグイン JAR がクラスパスに追加される +2. DI コンテナが ``fess_*++.xml`` をマージし、コンポーネントを生成する +3. ```` で指定したメソッド(例: ``register``)が呼び出される +4. プラグインが対応するファクトリー/マネージャーに登録される 終了 ---- -1. ``@PreDestroy`` メソッドが呼び出される（定義されている場合） +1. DI コンテナの終了時に、```` で指定したメソッドが呼び出される + (定義されている場合) 2. リソースのクリーンアップ +.. note:: + + データストアの場合、実行中のクロールは ``AbstractDataStore.stop()`` によって + 停止フラグが立てられ、レコード処理ループが安全に終了します。 + 依存関係 ======== Fess本体との依存 ---------------- +|Fess| 本体のクラスは実行時にサーバーのクラスパス上に存在するため、 +``provided`` スコープで依存します(プラグイン JAR には含めません)。 + .. code-block:: xml org.codelibs.fess fess - ${fess.version} provided @@ -148,38 +218,46 @@ Fess本体との依存 1.0.0 -依存ライブラリはプラグインJARと一緒に配布するか、 -Maven Shade Pluginでfat JARを作成します。 +これらは |Fess| 本体に含まれないため、プラグインと一緒に配布する必要があります。 設定の取得 ========== -FessConfigから取得 ------------------- +パラメーターとFessConfigの取得 +------------------------------ + +データストアの ``storeData()`` では、管理画面で設定したパラメーターを +``DataStoreParams`` から取得します。値の取得には ``getAsString()`` を使用します +(``DataStoreParams`` は ``Map`` を実装していないため ``get()`` は文字列を返しません)。 +また、|Fess| の設定値は ``ComponentUtil.getFessConfig()`` から取得できます: .. code-block:: java public class ExampleDataStore extends AbstractDataStore { @Override - public String getName() { - return "Example"; + protected String getName() { + // ハンドラー名として使用される。クラスの単純名を返すのが慣例 + return this.getClass().getSimpleName(); } @Override - protected void storeData(DataConfig dataConfig, IndexUpdateCallback callback, - Map paramMap, Map scriptMap, - Map defaultDataMap) { + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { // パラメーターの取得 - String apiKey = paramMap.get("api.key"); - String baseUrl = paramMap.get("base.url"); + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); - // FessConfigの取得 - FessConfig fessConfig = ComponentUtil.getFessConfig(); + // FessConfig の取得 + final FessConfig fessConfig = ComponentUtil.getFessConfig(); } } +``storeData()`` の詳しい実装方法(データ取得・スクリプト評価・インデックス登録の +流れ)は :doc:`datastore-plugin` を参照してください。 + ビルドとインストール ==================== @@ -190,31 +268,33 @@ FessConfigから取得 mvn clean package +``target/`` ディレクトリに JAR ファイル(例: ``fess-ds-example-15.8.0.jar``)が +生成されます。 + インストール ------------ 1. **管理画面から**: - - 「システム」→「プラグイン」→「インストール」 - - プラグイン名を入力してインストール + - 「システム」→「プラグイン」→「インストール」を開く + - プラグインリポジトリの一覧から選択するか、ビルドした JAR ファイルを + アップロードしてインストール -2. **コマンドライン**: +2. **手動**: - :: - - ./bin/fess-plugin install fess-ds-example - -3. **手動**: - - - JARファイルを ``plugins/`` ディレクトリにコピー + - JAR ファイルを ``app/WEB-INF/plugin/`` ディレクトリにコピー - |Fess| を再起動 +インストール手順の詳細は :doc:`../admin/plugin-guide` を参照してください。 + デバッグ ======== ログ出力 -------- +|Fess| は Log4j2 を使用します。ロガーは ``LogManager.getLogger()`` で取得します: + .. code-block:: java private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); @@ -224,19 +304,24 @@ FessConfigから取得 logger.info("Info message"); } +.. note:: + + パスワードやトークンなどの機微な情報はログに出力しないでください。 + 開発モード ---------- -開発時は |Fess| をIDEから起動してデバッグできます: +開発時は |Fess| を IDE から起動してデバッグできます: -1. ``FessBoot`` クラスをデバッグ実行 +1. ``org.codelibs.fess.FessBoot`` クラスをデバッグ実行する 2. プラグインのソースをプロジェクトに含める -3. ブレークポイントを設定 +3. ブレークポイントを設定する 公開プラグイン一覧 ================== -|Fess| プロジェクトで公開されている主なプラグイン: +|Fess| プロジェクトでは、多数のプラグインが公開されています。以下は代表例です +(すべてを網羅したものではありません): .. list-table:: :header-rows: 1 @@ -244,19 +329,24 @@ FessConfigから取得 * - プラグイン - 説明 - * - fess-ds-box - - Box.comコネクタ - * - fess-ds-dropbox - - Dropboxコネクタ - * - fess-ds-slack - - Slackコネクタ - * - fess-ds-atlassian - - Confluence/Jiraコネクタ - * - fess-ds-git - - Gitリポジトリコネクタ - * - fess-theme-* + * - ``fess-ds-box`` + - Box コネクター + * - ``fess-ds-dropbox`` + - Dropbox コネクター + * - ``fess-ds-slack`` + - Slack コネクター + * - ``fess-ds-atlassian`` + - JIRA / Confluence コネクター + * - ``fess-ds-git`` + - Git リポジトリコネクター + * - ``fess-llm-openai`` + - OpenAI LLM プロバイダー + * - ``fess-theme-*`` - カスタムテーマ +このほかにも、``fess-ds-csv`` / ``fess-ds-db`` / ``fess-ds-json`` / +``fess-ds-microsoft365`` / ``fess-ds-sharepoint`` などのデータストアコネクターや、 +``fess-llm-ollama`` / ``fess-llm-gemini`` などの LLM プロバイダーが公開されています。 これらのプラグインは、開発の参考として `GitHub `__ で公開されています。 @@ -267,3 +357,5 @@ FessConfigから取得 - :doc:`script-engine-plugin` - スクリプトエンジンプラグイン - :doc:`webapp-plugin` - Webアプリプラグイン - :doc:`ingest-plugin` - Ingestプラグイン +- :doc:`theme-development` - テーマのカスタマイズ +- :doc:`../admin/plugin-guide` - プラグインのインストール diff --git a/ko/15.8/dev/plugin-architecture.rst b/ko/15.8/dev/plugin-architecture.rst index 88f221bfc..8cb4c7783 100644 --- a/ko/15.8/dev/plugin-architecture.rst +++ b/ko/15.8/dev/plugin-architecture.rst @@ -6,44 +6,75 @@ ==== |Fess| 의 플러그인 시스템을 통해 코어 기능을 확장할 수 있습니다. -플러그인은 JAR 파일로 배포되며 동적으로 로드됩니다. +플러그인은 JAR 파일로 배포되며, 클래스패스에 추가되면 DI 컨테이너 +(Lasta Di)에 의해 컴포넌트가 로드되어 해당 팩토리나 매니저에 +등록됩니다. 플러그인 종류 ================ -|Fess| 는 다음 종류의 플러그인을 지원합니다: +|Fess| 는 아티팩트 이름의 프리픽스로 플러그인의 종류를 +판별합니다(``PluginHelper.ArtifactType``). 주요 종류는 다음과 같습니다: .. list-table:: :header-rows: 1 - :widths: 25 75 + :widths: 20 25 55 * - 종류 + - 프리픽스 - 설명 * - 데이터스토어 - - 새로운 데이터 소스에서 콘텐츠 취득 (Box, Slack 등) + - ``fess-ds-*`` + - 새로운 데이터 소스로부터의 콘텐츠 취득(Box, Slack, Git 등) + * - 웹앱 + - ``fess-webapp-*`` + - 웹 인터페이스나 검색 기능의 확장 * - 스크립트 엔진 + - ``fess-script-*`` - 새로운 스크립트 언어 지원 - * - 웹앱 - - 웹 인터페이스 확장 * - Ingest - - 인덱싱 시 데이터 가공 + - ``fess-ingest-*`` + - 인덱스 등록 시 문서 가공 + * - 테마 + - ``fess-theme-*`` + - 검색 화면 디자인 커스터마이징 + * - 썸네일 + - ``fess-thumbnail-*`` + - 썸네일 생성 방식 추가 + * - LLM + - ``fess-llm-*`` + - RAG/채팅에서 사용하는 LLM 프로바이더 추가 + * - 크롤러 + - ``fess-crawler-*`` + - 크롤러 클라이언트 확장 플러그인 구조 ============== 기본 구조 --------- +--------- + +데이터스토어 플러그인의 구현 템플릿인 +`fess-ds-example `__ 를 예로 들면, +플러그인은 「구현 클래스」와 「DI 등록 파일」로 구성됩니다: :: fess-ds-example/ ├── pom.xml - └── src/main/java/org/codelibs/fess/ds/example/ - ├── ExampleDataStore.java # 데이터스토어 구현 - └── ExampleDataStoreHandler.java # 핸들러 (옵션) + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # 데이터스토어 구현 + └── resources/ + └── fess_ds++.xml # DI 컴포넌트 등록 + +pom.xml 예제 +------------ -pom.xml 예시 ------------ +플러그인은 ``fess-parent`` 를 부모 POM 으로 하는 jar 로 빌드합니다. +``fess`` 나 ``opensearch`` 등, 실행 시 |Fess| 본체에서 제공되는 라이브러리는 +``provided`` 스코프로 선언합니다. 버전 번호나 빌드 설정(포맷터· +라이선스 헤더 등)은 부모 POM 에서 상속됩니다. .. code-block:: xml @@ -59,86 +90,125 @@ pom.xml 예시 15.8.0 jar - fess-ds-example - Example DataStore for Fess - - - 15.8.0 - 21 - + + org.codelibs.fess + fess-parent + 15.8.0 + + org.codelibs.fess fess - ${fess.version} + provided + + + org.opensearch + opensearch provided +.. note:: + + 개발 중인 브랜치에서는 버전이 ``15.8.0-SNAPSHOT`` 처럼 ``-SNAPSHOT`` 이 붙은 + 형태가 됩니다. 플러그인 고유의 의존 라이브러리는 일반적인 Maven 의존 관계로 + 선언합니다. 이들은 |Fess| 본체에는 포함되지 않으므로, 플러그인과 함께 배포해야 합니다. + 플러그인 등록 ================ -DI 컨테이너에 등록 +DI 컨테이너 등록 ------------------ -플러그인은 ``fess_ds.xml`` 등의 설정 파일로 등록됩니다: +플러그인은 ``fess_ds++.xml`` 처럼 끝이 ``++`` 로 끝나는 DI 설정 파일로 +컴포넌트를 등록합니다. Lasta Di 는 클래스패스 상에서 발견한 ``++`` 가 붙은 +파일을, |Fess| 본체의 대응하는 설정 파일(이 예에서는 ``fess_ds.xml``)에 +자동으로 병합합니다. 이 구조를 통해 플러그인은 |Fess| 본체의 파일을 +수정하지 않고도 자신의 컴포넌트를 추가할 수 있습니다. .. code-block:: xml - - - - -자동 등록 --------- - -대부분의 플러그인은 ``@PostConstruct`` 어노테이션으로 자동 등록합니다: + + + + + + + + +플러그인 종류마다 병합 대상 파일이 다릅니다. 예를 들어 스크립트 엔진은 +``fess_se++.xml``, Ingest 는 ``fess_ingest++.xml``, LLM 프로바이더는 +``fess_llm++.xml``, 웹앱은 ``app++.xml`` 을 사용합니다. + +컴포넌트 초기화 +---------------------- + +```` 는 컴포넌트 생성 후에 호출할 +메서드를 지정하는 Lasta Di 의 라이프사이클 설정입니다. 데이터스토어의 경우, +``AbstractDataStore`` 가 가진 ``register()`` 메서드가 호출되어 +자신이 ``DataStoreFactory`` 에 등록됩니다: .. code-block:: java - @PostConstruct + // AbstractDataStore 의 구현(통상 오버라이드 불필요) public void register() { - ComponentUtil.getDataStoreManager().add(this); + ComponentUtil.getDataStoreFactory().add(getName(), this); } +.. note:: + + 이것은 Java 의 ``@PostConstruct`` 애너테이션이 아니라, DI 설정 파일의 + ```` 요소에 의한 초기화입니다. 등록되는 이름은 ``getName()`` 의 + 반환값이며, 관리 화면에서 플러그인을 선택할 때의 이름이 됩니다. + 플러그인 라이프사이클 ========================== 초기화 ------ -1. JAR 파일이 로드됨 -2. DI 컨테이너가 컴포넌트를 초기화 -3. ``@PostConstruct`` 메서드가 호출됨 -4. 플러그인이 매니저에 등록됨 +1. 플러그인 JAR 가 클래스패스에 추가된다 +2. DI 컨테이너가 ``fess_*++.xml`` 을 병합하여 컴포넌트를 생성한다 +3. ```` 에서 지정한 메서드(예: ``register``)가 호출된다 +4. 플러그인이 대응하는 팩토리/매니저에 등록된다 종료 ---- -1. ``@PreDestroy`` 메서드가 호출됨 (정의된 경우) -2. 리소스 클린업 +1. DI 컨테이너 종료 시, ```` 에서 지정한 메서드가 호출된다 + (정의되어 있는 경우) +2. 리소스 정리 + +.. note:: + + 데이터스토어의 경우, 실행 중인 크롤링은 ``AbstractDataStore.stop()`` 에 의해 + 정지 플래그가 설정되어 레코드 처리 루프가 안전하게 종료됩니다. 의존 관계 -======== +========= -Fess 본체와의 의존 +Fess 본체 의존성 ---------------- +|Fess| 본체의 클래스는 실행 시 서버의 클래스패스 상에 존재하므로, +``provided`` 스코프로 의존합니다(플러그인 JAR 에는 포함하지 않습니다). + .. code-block:: xml org.codelibs.fess fess - ${fess.version} provided 외부 라이브러리 --------------- +--------------- -플러그인은 독자적인 의존 라이브러리를 포함할 수 있습니다: +플러그인은 자체 의존 라이브러리를 포함할 수 있습니다: .. code-block:: xml @@ -148,38 +218,46 @@ Fess 본체와의 의존 1.0.0 -의존 라이브러리는 플러그인 JAR와 함께 배포하거나 -Maven Shade Plugin으로 fat JAR를 작성합니다. +이들은 |Fess| 본체에는 포함되지 않으므로, 플러그인과 함께 배포해야 합니다. 설정 취득 ========== -FessConfig에서 취득 ------------------- +파라미터와 FessConfig 취득 +------------------------------ + +데이터스토어의 ``storeData()`` 에서는 관리 화면에서 설정한 파라미터를 +``DataStoreParams`` 에서 취득합니다. 값을 가져올 때는 ``getAsString()`` 을 사용합니다 +(``DataStoreParams`` 는 ``Map`` 을 구현하지 않으므로 ``get()`` 은 문자열을 반환하지 않습니다). +또한 |Fess| 의 설정값은 ``ComponentUtil.getFessConfig()`` 에서 취득할 수 있습니다: .. code-block:: java public class ExampleDataStore extends AbstractDataStore { @Override - public String getName() { - return "Example"; + protected String getName() { + // 핸들러 이름으로 사용된다. 클래스의 단순 이름을 반환하는 것이 관례 + return this.getClass().getSimpleName(); } @Override - protected void storeData(DataConfig dataConfig, IndexUpdateCallback callback, - Map paramMap, Map scriptMap, - Map defaultDataMap) { + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { // 파라미터 취득 - String apiKey = paramMap.get("api.key"); - String baseUrl = paramMap.get("base.url"); + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); // FessConfig 취득 - FessConfig fessConfig = ComponentUtil.getFessConfig(); + final FessConfig fessConfig = ComponentUtil.getFessConfig(); } } +``storeData()`` 의 자세한 구현 방법(데이터 취득·스크립트 평가·인덱스 등록의 +흐름)은 :doc:`datastore-plugin` 을 참조하십시오. + 빌드와 설치 ==================== @@ -190,30 +268,32 @@ FessConfig에서 취득 mvn clean package +``target/`` 디렉터리에 JAR 파일(예: ``fess-ds-example-15.8.0.jar``)이 +생성됩니다. + 설치 ------------ 1. **관리 화면에서**: - - "시스템" → "플러그인" → "설치" - - 플러그인 이름을 입력하여 설치 + - [시스템 > 플러그인 > 설치]를 연다 + - 플러그인 리포지토리 목록에서 선택하거나, 빌드한 JAR 파일을 + 업로드하여 설치 -2. **명령줄**: +2. **수동**: - :: - - ./bin/fess-plugin install fess-ds-example - -3. **수동**: - - - JAR 파일을 ``plugins/`` 디렉토리에 복사 + - JAR 파일을 ``app/WEB-INF/plugin/`` 디렉터리에 복사 - |Fess| 를 재시작 -디버그 +설치 절차의 자세한 내용은 :doc:`../admin/plugin-guide` 를 참조하십시오. + +디버깅 ======== 로그 출력 --------- +--------- + +|Fess| 는 Log4j2 를 사용합니다. 로거는 ``LogManager.getLogger()`` 로 취득합니다: .. code-block:: java @@ -224,19 +304,24 @@ FessConfig에서 취득 logger.info("Info message"); } +.. note:: + + 비밀번호나 토큰 등의 민감한 정보는 로그에 출력하지 마십시오. + 개발 모드 ---------- -개발 시 |Fess| 를 IDE에서 시작하여 디버그할 수 있습니다: +개발 시에는 |Fess| 를 IDE 에서 실행하여 디버깅할 수 있습니다: -1. ``FessBoot`` 클래스를 디버그 실행 -2. 플러그인 소스를 프로젝트에 포함 -3. 브레이크포인트 설정 +1. ``org.codelibs.fess.FessBoot`` 클래스를 디버그 실행한다 +2. 플러그인의 소스를 프로젝트에 포함시킨다 +3. 브레이크포인트를 설정한다 공개 플러그인 목록 ================== -|Fess| 프로젝트에서 공개하고 있는 주요 플러그인: +|Fess| 프로젝트에서는 다수의 플러그인이 공개되어 있습니다. 다음은 대표적인 예입니다 +(전부를 망라한 것은 아닙니다): .. list-table:: :header-rows: 1 @@ -244,26 +329,33 @@ FessConfig에서 취득 * - 플러그인 - 설명 - * - fess-ds-box - - Box.com 커넥터 - * - fess-ds-dropbox + * - ``fess-ds-box`` + - Box 커넥터 + * - ``fess-ds-dropbox`` - Dropbox 커넥터 - * - fess-ds-slack + * - ``fess-ds-slack`` - Slack 커넥터 - * - fess-ds-atlassian - - Confluence/Jira 커넥터 - * - fess-ds-git + * - ``fess-ds-atlassian`` + - JIRA / Confluence 커넥터 + * - ``fess-ds-git`` - Git 리포지토리 커넥터 - * - fess-theme-* + * - ``fess-llm-openai`` + - OpenAI LLM 프로바이더 + * - ``fess-theme-*`` - 커스텀 테마 -이러한 플러그인은 개발 참고로 -`GitHub `__ 에서 공개되어 있습니다. +이 밖에도 ``fess-ds-csv`` / ``fess-ds-db`` / ``fess-ds-json`` / +``fess-ds-microsoft365`` / ``fess-ds-sharepoint`` 등의 데이터스토어 커넥터나, +``fess-llm-ollama`` / ``fess-llm-gemini`` 등의 LLM 프로바이더가 공개되어 있습니다. +이들 플러그인은 개발 참고용으로 +`GitHub `__ 에 공개되어 있습니다. 참고 정보 -======== +========= - :doc:`datastore-plugin` - 데이터스토어 플러그인 개발 - :doc:`script-engine-plugin` - 스크립트 엔진 플러그인 - :doc:`webapp-plugin` - 웹앱 플러그인 - :doc:`ingest-plugin` - Ingest 플러그인 +- :doc:`theme-development` - 테마 커스터마이징 +- :doc:`../admin/plugin-guide` - 플러그인 설치 diff --git a/zh-cn/15.8/dev/plugin-architecture.rst b/zh-cn/15.8/dev/plugin-architecture.rst index eb5e91179..078b1093c 100644 --- a/zh-cn/15.8/dev/plugin-architecture.rst +++ b/zh-cn/15.8/dev/plugin-architecture.rst @@ -5,28 +5,47 @@ 概述 ==== -|Fess| 的插件系统允许您扩展核心功能。 -插件以JAR文件形式分发，并动态加载。 +通过 |Fess| 的插件系统，可以扩展核心功能。 +插件以 JAR 文件的形式分发，添加到类路径后，会由 DI 容器（Lasta Di） +加载其中的组件，并注册到相应的工厂或管理器中。 插件类型 ======== -|Fess| 支持以下类型的插件: +|Fess| 通过构件（artifact）名称的前缀来判断插件的类型 +（``PluginHelper.ArtifactType``）。主要类型如下： .. list-table:: :header-rows: 1 - :widths: 25 75 + :widths: 20 25 55 * - 类型 + - 前缀 - 说明 * - 数据存储 - - 从新数据源获取内容（Box、Slack等） + - ``fess-ds-*`` + - 从新数据源获取内容（Box、Slack、Git 等） + * - Web应用 + - ``fess-webapp-*`` + - 扩展Web界面或搜索功能 * - 脚本引擎 + - ``fess-script-*`` - 支持新的脚本语言 - * - Web应用 - - 扩展Web界面 * - Ingest - - 索引时的数据处理 + - ``fess-ingest-*`` + - 索引注册时对文档进行加工处理 + * - 主题 + - ``fess-theme-*`` + - 自定义搜索界面设计 + * - 缩略图 + - ``fess-thumbnail-*`` + - 添加缩略图生成方式 + * - LLM + - ``fess-llm-*`` + - 添加 RAG/聊天功能中使用的 LLM 提供方 + * - 爬虫 + - ``fess-crawler-*`` + - 扩展爬虫客户端 插件结构 ======== @@ -34,17 +53,27 @@ 基本结构 -------- +以数据存储插件的实现模板 +`fess-ds-example `__ 为例， +插件由"实现类"和"DI 注册文件"构成： + :: fess-ds-example/ ├── pom.xml - └── src/main/java/org/codelibs/fess/ds/example/ - ├── ExampleDataStore.java # 数据存储实现 - └── ExampleDataStoreHandler.java # 处理器（可选） + └── src/main/ + ├── java/org/codelibs/fess/ds/example/ + │ └── ExampleDataStore.java # 数据存储实现 + └── resources/ + └── fess_ds++.xml # DI组件注册 pom.xml示例 ----------- +插件以 ``fess-parent`` 作为父 POM，构建为 jar。``fess``、``opensearch`` +等在运行时由 |Fess| 本体提供的库，需以 ``provided`` 作用域声明。版本号 +及构建配置（格式化工具、许可证头等）均从父 POM 继承。 + .. code-block:: xml @@ -59,86 +88,123 @@ pom.xml示例 15.8.0 jar - fess-ds-example - Example DataStore for Fess - - - 15.8.0 - 21 - + + org.codelibs.fess + fess-parent + 15.8.0 + + org.codelibs.fess fess - ${fess.version} + provided + + + org.opensearch + opensearch provided +.. note:: + + 在开发中的分支上，版本号会带有 ``-SNAPSHOT`` 后缀，例如 + ``15.8.0-SNAPSHOT``。插件特有的依赖库以普通的 Maven 依赖关系声明。 + 由于这些库不包含在 |Fess| 本体中，因此需要与插件一起分发。 + 插件注册 ======== DI容器注册 ---------- -插件在 ``fess_ds.xml`` 等配置文件中注册: +插件通过文件名以 ``++`` 结尾的 DI 配置文件（如 ``fess_ds++.xml``）来 +注册组件。Lasta Di 会将在类路径中找到的带 ``++`` 的文件，自动合并到 +|Fess| 本体对应的配置文件中（本例中为 ``fess_ds.xml``）。借助这一机 +制，插件无需修改 |Fess| 本体的文件，即可添加自身的组件。 .. code-block:: xml - - - - -自动注册 --------- + + + + + + + + +不同类型的插件，合并目标文件也不同。例如脚本引擎使用 +``fess_se++.xml``、Ingest 使用 ``fess_ingest++.xml``、LLM 提供方使用 +``fess_llm++.xml``、Web应用使用 ``app++.xml``。 + +组件初始化 +---------- -许多插件使用 ``@PostConstruct`` 注解自动注册: +```` 是 Lasta Di 的生命周期设置，用于 +指定组件生成后要调用的方法。对于数据存储而言，会调用 +``AbstractDataStore`` 所具有的 ``register()`` 方法，将自身注册到 +``DataStoreFactory`` 中： .. code-block:: java - @PostConstruct + // AbstractDataStore 的实现（通常无需重写） public void register() { - ComponentUtil.getDataStoreManager().add(this); + ComponentUtil.getDataStoreFactory().add(getName(), this); } +.. note:: + + 这并非 Java 的 ``@PostConstruct`` 注解，而是通过 DI 配置文件中的 + ```` 元素进行的初始化。注册的名称即为 ``getName()`` + 的返回值，也就是在管理界面中选择插件时使用的名称。 + 插件生命周期 ============ 初始化 ------ -1. JAR文件被加载 -2. DI容器初始化组件 -3. 调用 ``@PostConstruct`` 方法 -4. 插件注册到管理器 +1. 插件 JAR 被添加到类路径中 +2. DI 容器合并 ``fess_*++.xml``，生成组件 +3. 调用 ```` 中指定的方法（例如 ``register``） +4. 插件注册到对应的工厂/管理器中 终止 ---- -1. 调用 ``@PreDestroy`` 方法（如果定义） +1. DI 容器终止时，会调用 ```` 中指定的方法（如果已定义） 2. 清理资源 +.. note:: + + 对于数据存储而言，正在运行的爬取会通过 ``AbstractDataStore.stop()`` + 设置停止标志，使记录处理循环安全结束。 + 依赖关系 ======== 与Fess本体的依赖 ---------------- +由于 |Fess| 本体的类在运行时已存在于服务器的类路径中，因此以 +``provided`` 作用域进行依赖（不会包含在插件 JAR 中）。 + .. code-block:: xml org.codelibs.fess fess - ${fess.version} provided 外部库 ------ -插件可以包含自己的依赖库: +插件可以包含自己的依赖库： .. code-block:: xml @@ -148,39 +214,48 @@ DI容器注册 1.0.0 -依赖库与插件JAR一起分发， -或使用Maven Shade Plugin创建fat JAR。 +由于这些库不包含在 |Fess| 本体中，因此需要与插件一起分发。 获取配置 ======== -从FessConfig获取 ----------------- +获取参数和FessConfig +-------------------- + +在数据存储的 ``storeData()`` 中，可从 ``DataStoreParams`` 获取在管理 +界面中设置的参数。获取值时请使用 ``getAsString()``（由于 +``DataStoreParams`` 并未实现 ``Map`` 接口，``get()`` 不会返回字符 +串）。此外，|Fess| 的配置值可通过 ``ComponentUtil.getFessConfig()`` +获取： .. code-block:: java public class ExampleDataStore extends AbstractDataStore { @Override - public String getName() { - return "Example"; + protected String getName() { + // 用作处理器名。按照惯例返回类的简单名称 + return this.getClass().getSimpleName(); } @Override - protected void storeData(DataConfig dataConfig, IndexUpdateCallback callback, - Map paramMap, Map scriptMap, - Map defaultDataMap) { + protected void storeData(final DataConfig dataConfig, final IndexUpdateCallback callback, + final DataStoreParams paramMap, final Map scriptMap, + final Map defaultDataMap) { // 获取参数 - String apiKey = paramMap.get("api.key"); - String baseUrl = paramMap.get("base.url"); + final String apiKey = paramMap.getAsString("api.key"); + final String baseUrl = paramMap.getAsString("base.url"); // 获取FessConfig - FessConfig fessConfig = ComponentUtil.getFessConfig(); + final FessConfig fessConfig = ComponentUtil.getFessConfig(); } } -构建和安装 +关于 ``storeData()`` 的详细实现方法（数据获取、脚本求值、索引注册的 +流程），请参考 :doc:`datastore-plugin`。 + +构建与安装 ========== 构建 @@ -190,31 +265,33 @@ DI容器注册 mvn clean package +会在 ``target/`` 目录下生成 JAR 文件（例如 +``fess-ds-example-15.8.0.jar``）。 + 安装 ---- -1. **从管理界面**: - - - "系统" -> "插件" -> "安装" - - 输入插件名称进行安装 +1. **从管理界面**： -2. **命令行**: + - 打开[系统 > 插件 > 安装] + - 从插件仓库列表中选择，或上传已构建的 JAR 文件进行安装 - :: +2. **手动安装**： - ./bin/fess-plugin install fess-ds-example - -3. **手动**: - - - 将JAR文件复制到 ``plugins/`` 目录 + - 将 JAR 文件复制到 ``app/WEB-INF/plugin/`` 目录 - 重启 |Fess| +安装步骤的详细信息请参考 :doc:`../admin/plugin-guide`。 + 调试 ==== 日志输出 -------- +|Fess| 使用 Log4j2。日志记录器（logger）可通过 +``LogManager.getLogger()`` 获取： + .. code-block:: java private static final Logger logger = LogManager.getLogger(ExampleDataStore.class); @@ -224,19 +301,23 @@ DI容器注册 logger.info("Info message"); } +.. note:: + + 请不要将密码、令牌等敏感信息输出到日志中。 + 开发模式 -------- -开发时可以从IDE启动 |Fess| 进行调试: +开发时可以从 IDE 启动 |Fess| 进行调试： -1. 以调试模式运行 ``FessBoot`` 类 -2. 将插件源代码包含在项目中 +1. 以调试模式运行 ``org.codelibs.fess.FessBoot`` 类 +2. 将插件的源代码包含在项目中 3. 设置断点 公开插件列表 ============ -|Fess| 项目公开的主要插件: +|Fess| 项目公开了大量插件，以下是其中的代表示例（并非全部列举）： .. list-table:: :header-rows: 1 @@ -244,20 +325,24 @@ DI容器注册 * - 插件 - 说明 - * - fess-ds-box - - Box.com连接器 - * - fess-ds-dropbox - - Dropbox连接器 - * - fess-ds-slack - - Slack连接器 - * - fess-ds-atlassian - - Confluence/Jira连接器 - * - fess-ds-git - - Git仓库连接器 - * - fess-theme-* + * - ``fess-ds-box`` + - Box 连接器 + * - ``fess-ds-dropbox`` + - Dropbox 连接器 + * - ``fess-ds-slack`` + - Slack 连接器 + * - ``fess-ds-atlassian`` + - JIRA / Confluence 连接器 + * - ``fess-ds-git`` + - Git 仓库连接器 + * - ``fess-llm-openai`` + - OpenAI LLM 提供方 + * - ``fess-theme-*`` - 自定义主题 -这些插件在 +除此之外，还公开了 ``fess-ds-csv`` / ``fess-ds-db`` / ``fess-ds-json`` / +``fess-ds-microsoft365`` / ``fess-ds-sharepoint`` 等数据存储连接器，以及 +``fess-llm-ollama`` / ``fess-llm-gemini`` 等 LLM 提供方。这些插件已在 `GitHub `__ 上公开，可作为开发参考。 参考信息 @@ -267,4 +352,5 @@ DI容器注册 - :doc:`script-engine-plugin` - 脚本引擎插件 - :doc:`webapp-plugin` - Web应用插件 - :doc:`ingest-plugin` - Ingest插件 - +- :doc:`theme-development` - 主题自定义 +- :doc:`../admin/plugin-guide` - 插件安装