diff --git a/de/15.8/dev/overview.rst b/de/15.8/dev/overview.rst index 07cf2252..d79d523b 100644 --- a/de/15.8/dev/overview.rst +++ b/de/15.8/dev/overview.rst @@ -6,63 +6,95 @@ Entwicklerdokumentation Übersicht ========= Dieser Abschnitt beschreibt die Erweiterungsentwicklung von |Fess|. -Er bietet Informationen zur Plugin-Entwicklung, Erstellung benutzerdefinierter Konnektoren, -Theme-Anpassung und anderen Moglichkeiten zur Erweiterung von |Fess|. +Er bietet Informationen zur Plugin-Entwicklung, zur Erstellung benutzerdefinierter Konnektoren, +zur Theme-Anpassung und zu weiteren Möglichkeiten, |Fess| zu erweitern. Zielgruppe ========== -- Entwickler, die benutzerdefinierte Funktionen fur |Fess| entwickeln mochten -- Entwickler, die Plugins erstellen mochten -- Entwickler, die den Quellcode von |Fess| verstehen mochten +- Entwickler, die benutzerdefinierte Funktionen für |Fess| entwickeln möchten +- Entwickler, die Plugins erstellen möchten +- Entwickler, die den Quellcode von |Fess| verstehen möchten Voraussetzungen ---------------- +---------------- - Grundkenntnisse in Java 21 - Grundlagen von Maven (Build-System) - Erfahrung in der Webanwendungsentwicklung +- Grundkenntnisse von OpenSearch (|Fess| verwendet OpenSearch als Suchmaschine) Entwicklungsumgebung -==================== +===================== Empfohlene Umgebung -------------------- +-------------------- -- **JDK**: OpenJDK 21 oder hoher +- **JDK**: OpenJDK 21 oder höher - **IDE**: IntelliJ IDEA / Eclipse / VS Code -- **Build-Tool**: Maven 3.9 oder hoher +- **Build-Tool**: Maven (für den Build ist keine Mindestversion vorgeschrieben, empfohlen wird jedoch eine neuere 3.x-Version, die Java 21 unterstützt) - **Git**: Versionskontrolle +- **OpenSearch**: Backend der Suchmaschine (beim Start aus der IDE werden die benötigten Module und Plugins beim Build heruntergeladen) Setup ----- +|Fess| wird als Maven-Projekt gebaut. Bei der Entwicklung ist es am einfachsten, es aus der IDE zu starten. + 1. Quellcode abrufen: -:: + :: - git clone https://github.com/codelibs/fess.git - cd fess + git clone https://github.com/codelibs/fess.git -2. Build: +2. Import in die IDE: -:: + Importieren Sie das abgerufene Verzeichnis als Maven-Projekt in Ihre IDE. - mvn package -DskipTests +3. Module und Plugins für OpenSearch herunterladen: -3. Entwicklungsserver starten: + Nur beim ersten Mal werden mit folgendem Befehl die Module und Plugins der Suchmaschine in das Verzeichnis ``plugins`` geladen. -:: + :: - ./bin/fess + mvn antrun:run -Architekturuberblick -==================== +4. Entwicklungsserver starten (aus der IDE): + + Führen Sie in der IDE ``org.codelibs.fess.FessBoot`` aus oder starten Sie ihn im Debug-Modus, + und öffnen Sie im Browser http://localhost:8080/. + Der Administrationsbereich ist unter http://localhost:8080/admin/ erreichbar (Standardkonto: ``admin`` / ``admin``). + +5. Paket bauen (Erstellung des Verteilungspakets): + + Falls ein Verteilungspaket benötigt wird, führen Sie das Ziel ``package`` aus. + Die Artefakte werden unter ``target/releases`` erzeugt (um Unit-Tests zu überspringen, fügen Sie ``-DskipTests`` hinzu). + + :: + + mvn package + + Entpacken Sie das erzeugte Verteilungspaket, um das Startskript ``bin/fess`` nutzen zu können. -|Fess| besteht aus folgenden Hauptkomponenten: + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + Das Startskript ``bin/fess`` ist im Verteilungspaket (zip/rpm/deb) enthalten. + Wird ``mvn package`` lediglich im Quellverzeichnis ausgeführt, wird ``bin/fess`` nicht direkt im Wurzelverzeichnis des Repositorys erzeugt. + Führen Sie bei der Entwicklung aus dem Quellcode wie oben beschrieben ``FessBoot`` in der IDE aus, + oder verwenden Sie ``bin/fess`` aus dem entpackten Verteilungspaket. + +Architekturüberblick +===================== + +|Fess| besteht aus den folgenden Hauptkomponenten: Komponentenstruktur -------------------- +-------------------- .. list-table:: :header-rows: 1 @@ -71,25 +103,27 @@ Komponentenstruktur * - Komponente - Beschreibung * - Web-Schicht - - MVC-Implementierung mit LastaFlute-Framework + - MVC-Implementierung mit dem LastaFlute-Framework * - Service-Schicht - - Geschaftslogik + - Geschäftslogik * - Datenzugriffsschicht - - OpenSearch-Integration mit DBFlute + - Typsicherer OpenSearch-Zugriff mit DBFlute (ESFlute/FreeGen) * - Crawler - Inhaltserfassung mit der fess-crawler-Bibliothek * - Suchmaschine - Volltextsuche mit OpenSearch Hauptframeworks ---------------- +---------------- - **LastaFlute**: Web-Framework (Actions, Forms, Validierung) -- **DBFlute**: Datenzugriffs-Framework (OpenSearch-Integration) +- **DBFlute**: Datenzugriffs-Framework. Die typsicheren Zugriffsklassen für OpenSearch (``Bhv`` / ``ConditionBean``) + werden durch die FreeGen-Funktion von DBFlute und ESFlute-Templates generiert + (zur Neugenerierung: ``mvn dbflute:freegen``) - **Lasta Di**: Dependency-Injection-Container Verzeichnisstruktur -=================== +===================== :: @@ -98,54 +132,67 @@ Verzeichnisstruktur │ ├── app/ │ │ ├── web/ # Controller (Action) │ │ ├── service/ # Services + │ │ ├── logic/ # Logik │ │ └── pager/ # Paginierung - │ ├── api/ # REST API + │ ├── api/ # REST API (z. B. api/v2) │ ├── helper/ # Hilfsklassen │ ├── crawler/ # Crawler-bezogen - │ ├── opensearch/ # OpenSearch-Integration (DBFlute-generiert) + │ ├── indexer/ # Indexverarbeitung + │ ├── opensearch/ # OpenSearch-Zugriff (ESFlute/FreeGen-generiert) │ ├── llm/ # LLM-Integration - │ └── ds/ # DataStore-Konnektoren + │ ├── ds/ # DataStore-Konnektoren + │ ├── ingest/ # Ingest (Datenverarbeitung beim Indexieren) + │ ├── script/ # Skript-Engine + │ ├── entity/ # Entitäten + │ └── mylasta/ # LastaFlute-Konfiguration (DI, Meldungen, typsichere Einstellungen) ├── src/main/resources/ │ ├── fess_config.properties # Konfiguration - │ └── fess_*.xml # DI-Konfiguration + │ └── fess_*.xml # DI-Konfiguration (app.xml, fess_ds.xml usw.) └── src/main/webapp/ └── WEB-INF/view/ # JSP-Templates Erweiterungspunkte -================== +==================== |Fess| bietet folgende Erweiterungspunkte: Plugins ------- -Mit Plugins konnen Funktionen hinzugefugt werden. +Mit Plugins können Funktionen hinzugefügt werden. -- **DataStore-Plugins**: Crawling von neuen Datenquellen -- **Script-Engine-Plugins**: Unterstutzung neuer Skriptsprachen -- **WebApp-Plugins**: Erweiterung des Web-Interfaces -- **Ingest-Plugins**: Datenverarbeitung beim Indexieren +- **DataStore-Plugin**: Crawling von neuen Datenquellen (erbt von ``AbstractDataStore``) +- **Script-Engine-Plugin**: Unterstützung neuer Skriptsprachen (implementiert ``ScriptEngine``) +- **WebApp-Plugin**: Erweiterung der Weboberfläche (Überschreiben von Lasta-Di-Komponenten und Zusammenführen von Ressourcen) +- **Ingest-Plugin**: Datenverarbeitung beim Indexieren (erbt von ``Ingester``) Details: :doc:`plugin-architecture` +.. note:: + + |Fess| selbst wird als ``war`` paketiert. Wenn beim lokalen Erstellen eines Plugins + |Fess| nicht als Abhängigkeit aufgelöst werden kann, ändern Sie in der ``pom.xml`` das ```` + vorübergehend auf ``jar``, führen Sie ``mvn clean install -DskipTests`` aus + und setzen Sie es anschließend wieder auf ``war`` zurück. + Themes ------ -Das Design der Suchoberflache kann angepasst werden. +Das Design der Suchoberfläche kann angepasst werden. Details: :doc:`theme-development` Konfiguration -------------- +-------------- -Viele Verhaltensweisen konnen uber ``fess_config.properties`` angepasst werden. +Viele Verhaltensweisen können über ``fess_config.properties`` angepasst werden. Details: :doc:`../config/intro` Plugin-Entwicklung -================== +==================== -Fur Details zur Plugin-Entwicklung siehe: +Für Details zur Plugin-Entwicklung siehe: - :doc:`plugin-architecture` - Plugin-Architektur - :doc:`datastore-plugin` - DataStore-Plugin-Entwicklung @@ -154,25 +201,26 @@ Fur Details zur Plugin-Entwicklung siehe: - :doc:`ingest-plugin` - Ingest-Plugin Theme-Entwicklung -================= +==================== - :doc:`theme-development` - Theme-Anpassung Best Practices -============== +================ Coding-Konventionen -------------------- +--------------------- - Dem bestehenden Codestil von |Fess| folgen -- ``mvn formatter:format`` fur Code-Formatierung -- ``mvn license:format`` fur Lizenz-Header +- ``mvn formatter:format`` für die Code-Formatierung +- ``mvn license:format`` zum Hinzufügen des Lizenz-Headers Tests ----- -- Unit-Tests schreiben (``*Test.java``) -- Integrationstests sind ``*Tests.java`` +- Unit-Tests (``*Test.java``): werden mit dem Standardprofil ``build`` über ``mvn test`` ausgeführt +- Integrationstests (``*Tests.java``): werden mit ``mvn test -P integrationTests`` ausgeführt. + Für die Ausführung der Integrationstests sind ein laufender |Fess|-Server und OpenSearch erforderlich Logging ------- @@ -182,7 +230,7 @@ Logging - Keine sensiblen Informationen in Logs ausgeben Ressourcen -========== +=========== - `GitHub Repository `__ - `Issue Tracker `__ diff --git a/en/15.8/dev/overview.rst b/en/15.8/dev/overview.rst index 9164c17b..2faed227 100644 --- a/en/15.8/dev/overview.rst +++ b/en/15.8/dev/overview.rst @@ -5,12 +5,12 @@ Developer Documentation Overview Overview ======== -This section explains how to extend |Fess|. -It provides information on plugin development, custom connector creation, theme customization, -and other ways to extend |Fess|. +This section explains extension development for |Fess|. +It provides information for extending |Fess|, including plugin development, +custom connector creation, and theme customization. Target Audience -=============== +================ - Developers who want to create custom features for |Fess| - Developers who want to create plugins @@ -22,47 +22,79 @@ Prerequisites - Basic knowledge of Java 21 - Basics of Maven (build system) - Experience with web application development +- Basic knowledge of OpenSearch (|Fess| uses OpenSearch as its search engine) Development Environment -======================= +======================== Recommended Environment ------------------------ +------------------------ - **JDK**: OpenJDK 21 or higher - **IDE**: IntelliJ IDEA / Eclipse / VS Code -- **Build Tool**: Maven 3.9 or higher +- **Build Tool**: Maven (the build does not enforce a minimum version, but a recent 3.x release that supports Java 21 is recommended) - **Git**: Version control +- **OpenSearch**: Search engine backend (when launching from the IDE, the required modules and plugins are downloaded during the build) Setup ----- +|Fess| is built as a Maven project. During development, the easiest way is to launch it from an IDE. + 1. Get the source code: -:: + :: - git clone https://github.com/codelibs/fess.git - cd fess + git clone https://github.com/codelibs/fess.git -2. Build: +2. Import into the IDE: -:: + Import the cloned directory into your IDE as a Maven project. - mvn package -DskipTests +3. Download the OpenSearch modules and plugins: -3. Start the development server: + The first time only, run the following command to fetch the search engine's modules and plugins into the ``plugins`` directory. -:: + :: + + mvn antrun:run + +4. Start the development server (from the IDE): + + Run or debug ``org.codelibs.fess.FessBoot`` in your IDE, then open + http://localhost:8080/ in your browser. + The admin screen is at http://localhost:8080/admin/ (default account: ``admin`` / ``admin``). + +5. Build the package (create a distribution): + + If you need a distribution package, run the ``package`` goal. + The artifact is generated in ``target/releases`` (add ``-DskipTests`` to skip unit tests). + + :: + + mvn package + + After extracting the generated distribution, the ``bin/fess`` startup script becomes available. + + :: - ./bin/fess + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + The ``bin/fess`` startup script is included in the distribution packages (zip/rpm/deb). + Simply running ``mvn package`` in the source tree does not generate ``bin/fess`` at the + root of the repository. For development from source, either run ``FessBoot`` in your IDE + as described above, or use ``bin/fess`` from an extracted distribution. Architecture Overview -===================== +====================== |Fess| consists of the following major components: Component Structure -------------------- +-------------------- .. list-table:: :header-rows: 1 @@ -71,25 +103,27 @@ Component Structure * - Component - Description * - Web Layer - - MVC implementation using LastaFlute framework + - MVC implementation using the LastaFlute framework * - Service Layer - Business logic * - Data Access Layer - - OpenSearch integration using DBFlute + - Type-safe OpenSearch access using DBFlute (ESFlute/FreeGen) * - Crawler - - Content collection using fess-crawler library + - Content collection using the fess-crawler library * - Search Engine - Full-text search using OpenSearch Major Frameworks ----------------- +----------------- - **LastaFlute**: Web framework (actions, forms, validation) -- **DBFlute**: Data access framework (OpenSearch integration) +- **DBFlute**: Data access framework. The type-safe access classes for OpenSearch + (``Bhv`` / ``ConditionBean``) are generated by DBFlute's FreeGen feature together with + ESFlute templates (regenerate with ``mvn dbflute:freegen``) - **Lasta Di**: Dependency injection container Directory Structure -=================== +==================== :: @@ -98,21 +132,27 @@ Directory Structure │ ├── app/ │ │ ├── web/ # Controllers (Action) │ │ ├── service/ # Services + │ │ ├── logic/ # Logic │ │ └── pager/ # Pagination - │ ├── api/ # REST API + │ ├── api/ # REST API (api/v2, etc.) │ ├── helper/ # Helper classes │ ├── crawler/ # Crawler related - │ ├── opensearch/ # OpenSearch integration (DBFlute generated) + │ ├── indexer/ # Index processing + │ ├── opensearch/ # OpenSearch access (ESFlute/FreeGen generated) │ ├── llm/ # LLM integration - │ └── ds/ # DataStore connectors + │ ├── ds/ # DataStore connectors + │ ├── ingest/ # Ingest (data processing during indexing) + │ ├── script/ # Script engine + │ ├── entity/ # Entities + │ └── mylasta/ # LastaFlute configuration (DI, messages, type-safe settings) ├── src/main/resources/ │ ├── fess_config.properties # Configuration - │ └── fess_*.xml # DI configuration + │ └── fess_*.xml # DI configuration (app.xml, fess_ds.xml, etc.) └── src/main/webapp/ └── WEB-INF/view/ # JSP templates Extension Points -================ +================= |Fess| provides the following extension points: @@ -121,13 +161,19 @@ Plugins You can add features using plugins. -- **DataStore Plugin**: Crawl from new data sources -- **Script Engine Plugin**: Support for new scripting languages -- **Web App Plugin**: Extend the web interface -- **Ingest Plugin**: Process data during indexing +- **DataStore Plugin**: Crawl from new data sources (extend ``AbstractDataStore``) +- **Script Engine Plugin**: Support for new scripting languages (implement ``ScriptEngine``) +- **Web App Plugin**: Extend the web interface (override Lasta Di components and merge resources) +- **Ingest Plugin**: Process data during indexing (extend ``Ingester``) Details: :doc:`plugin-architecture` +.. note:: + + The |Fess| core is packaged as a ``war``. When building a plugin locally, if |Fess| + cannot be resolved as a dependency, temporarily change ```` in ``pom.xml`` + to ``jar``, run ``mvn clean install -DskipTests``, and then change it back to ``war``. + Themes ------ @@ -143,26 +189,26 @@ Many behaviors can be customized via ``fess_config.properties``. Details: :doc:`../config/intro` Plugin Development -================== +=================== For details on plugin development, see the following: -- :doc:`plugin-architecture` - Plugin Architecture -- :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:`plugin-architecture` - Plugin architecture +- :doc:`datastore-plugin` - DataStore plugin development +- :doc:`script-engine-plugin` - Script engine plugin +- :doc:`webapp-plugin` - Web app plugin +- :doc:`ingest-plugin` - Ingest plugin Theme Development -================= +================== -- :doc:`theme-development` - Theme Customization +- :doc:`theme-development` - Theme customization Best Practices -============== +================ Coding Standards ----------------- +----------------- - Follow the existing |Fess| code style - Format code with ``mvn formatter:format`` @@ -171,14 +217,15 @@ Coding Standards Testing ------- -- Write unit tests (``*Test.java``) -- Integration tests use ``*Tests.java`` +- Unit tests (``*Test.java``): Run as ``mvn test`` under the default ``build`` profile +- Integration tests (``*Tests.java``): Run via ``mvn test -P integrationTests``. + Running integration tests requires a running |Fess| server and OpenSearch Logging ------- -- Use Log4j2 -- Use ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` +- Uses Log4j2 +- ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` - Do not log sensitive information Resources @@ -187,4 +234,3 @@ Resources - `GitHub Repository `__ - `Issue Tracker `__ - `Discussions `__ - diff --git a/es/15.8/dev/overview.rst b/es/15.8/dev/overview.rst index 841fbf6c..386d746c 100644 --- a/es/15.8/dev/overview.rst +++ b/es/15.8/dev/overview.rst @@ -1,27 +1,28 @@ -================================== -Vision General de Documentacion para Desarrolladores -================================== +======================================================= +Visión General de la Documentación para Desarrolladores +======================================================= -Vision General +Visión General ============== -Esta seccion explica el desarrollo de extensiones de |Fess|. -Proporciona informacion para extender |Fess|, incluyendo desarrollo de plugins, -creacion de conectores personalizados y personalizacion de temas. +Esta sección explica el desarrollo de extensiones para |Fess|. +Proporciona información para extender |Fess|, incluyendo el desarrollo de plugins, +la creación de conectores personalizados y la personalización de temas. Audiencia Objetivo ================== - Desarrolladores que desean crear funciones personalizadas para |Fess| - Desarrolladores que desean crear plugins -- Desarrolladores que desean entender el codigo fuente de |Fess| +- Desarrolladores que desean comprender el código fuente de |Fess| Conocimientos Previos --------------------- -- Conocimientos basicos de Java 21 -- Conceptos basicos de Maven (sistema de construccion) +- Conocimientos básicos de Java 21 +- Conceptos básicos de Maven (sistema de compilación) - Experiencia en desarrollo de aplicaciones web +- Conocimientos básicos de OpenSearch (|Fess| utiliza OpenSearch como motor de búsqueda) Entorno de Desarrollo ===================== @@ -31,35 +32,68 @@ Entorno Recomendado - **JDK**: OpenJDK 21 o superior - **IDE**: IntelliJ IDEA / Eclipse / VS Code -- **Herramienta de construccion**: Maven 3.9 o superior +- **Herramienta de compilación**: Maven (no se exige una versión mínima para la compilación, pero se recomienda una versión 3.x reciente compatible con Java 21) - **Git**: Control de versiones +- **OpenSearch**: Backend del motor de búsqueda (si se inicia desde el IDE, los módulos y plugins necesarios se descargan durante la compilación) -Configuracion -------------- +Configuración Inicial +--------------------- -1. Obtener el codigo fuente: +|Fess| se compila como un proyecto Maven. Durante el desarrollo, lo más sencillo es iniciarlo desde el IDE. -:: +1. Obtención del código fuente: - git clone https://github.com/codelibs/fess.git - cd fess + :: -2. Construir: + git clone https://github.com/codelibs/fess.git -:: +2. Importación al IDE: - mvn package -DskipTests + Importe el directorio obtenido al IDE como un proyecto Maven. -3. Iniciar el servidor de desarrollo: +3. Descarga de los módulos y plugins de OpenSearch: -:: + Solo la primera vez, utilice el siguiente comando para obtener en el directorio ``plugins`` + los módulos y plugins del motor de búsqueda. + + :: + + mvn antrun:run + +4. Inicio del servidor de desarrollo (desde el IDE): + + Ejecute o depure ``org.codelibs.fess.FessBoot`` en el IDE y abra + http://localhost:8080/ en el navegador. + La pantalla de administración está en http://localhost:8080/admin/ (cuenta inicial: ``admin`` / ``admin``). + +5. Compilación del paquete (creación de la distribución): - ./bin/fess + Si necesita un paquete de distribución, ejecute el objetivo ``package``. + Los artefactos se generan en ``target/releases`` (agregue ``-DskipTests`` para omitir las pruebas unitarias). -Vision General de la Arquitectura + :: + + mvn package + + Al descomprimir la distribución generada, dispondrá del script de inicio ``bin/fess``. + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + El script de inicio ``bin/fess`` se incluye en el paquete de distribución (zip/rpm/deb). + Con solo ejecutar ``mvn package`` en el árbol del código fuente, no se genera ``bin/fess`` + directamente en la raíz del repositorio. + Para desarrollar desde el código fuente, ejecute ``FessBoot`` en el IDE como se indicó + anteriormente, o utilice el ``bin/fess`` de la distribución descomprimida. + +Visión General de la Arquitectura ================================= -|Fess| esta compuesto por los siguientes componentes principales: +|Fess| está compuesto por los siguientes componentes principales: Estructura de Componentes ------------------------- @@ -69,24 +103,26 @@ Estructura de Componentes :widths: 25 75 * - Componente - - Descripcion + - Descripción * - Capa Web - - Implementacion MVC con el framework LastaFlute + - Implementación MVC mediante el framework LastaFlute * - Capa de Servicios - - Logica de negocio + - Lógica de negocio * - Capa de Acceso a Datos - - Integracion con OpenSearch mediante DBFlute + - Acceso a OpenSearch con seguridad de tipos mediante DBFlute (ESFlute/FreeGen) * - Rastreador - - Recoleccion de contenido con la biblioteca fess-crawler - * - Motor de Busqueda - - Busqueda de texto completo con OpenSearch + - Recopilación de contenido mediante la biblioteca fess-crawler + * - Motor de Búsqueda + - Búsqueda de texto completo mediante OpenSearch Frameworks Principales ---------------------- -- **LastaFlute**: Framework web (Acciones, Formularios, Validacion) -- **DBFlute**: Framework de acceso a datos (integracion con OpenSearch) -- **Lasta Di**: Contenedor de inyeccion de dependencias +- **LastaFlute**: Framework web (acciones, formularios, validación) +- **DBFlute**: Framework de acceso a datos. Las clases de acceso con seguridad de tipos para + OpenSearch (``Bhv`` / ``ConditionBean``) se generan mediante la función FreeGen de DBFlute + y las plantillas de ESFlute (para regenerarlas, ejecute ``mvn dbflute:freegen``) +- **Lasta Di**: Contenedor de inyección de dependencias Estructura de Directorios ========================= @@ -98,92 +134,105 @@ Estructura de Directorios │ ├── app/ │ │ ├── web/ # Controladores (Action) │ │ ├── service/ # Servicios - │ │ └── pager/ # Paginacion - │ ├── api/ # REST API + │ │ ├── logic/ # Lógica + │ │ └── pager/ # Paginación + │ ├── api/ # REST API (api/v2, etc.) │ ├── helper/ # Clases auxiliares │ ├── crawler/ # Relacionado con el rastreador - │ ├── opensearch/ # Integracion con OpenSearch (generado por DBFlute) - │ ├── llm/ # Integracion con LLM - │ └── ds/ # Conectores de almacen de datos + │ ├── indexer/ # Procesamiento de indexación + │ ├── opensearch/ # Acceso a OpenSearch (generado por ESFlute/FreeGen) + │ ├── llm/ # Integración con LLM + │ ├── ds/ # Conectores de almacén de datos + │ ├── ingest/ # Ingest (procesamiento de datos durante la indexación) + │ ├── script/ # Motor de scripts + │ ├── entity/ # Entidades + │ └── mylasta/ # Configuración de LastaFlute (DI, mensajes, configuración con seguridad de tipos) ├── src/main/resources/ - │ ├── fess_config.properties # Configuracion - │ └── fess_*.xml # Configuracion DI + │ ├── fess_config.properties # Configuración + │ └── fess_*.xml # Configuración DI (app.xml, fess_ds.xml, etc.) └── src/main/webapp/ └── WEB-INF/view/ # Plantillas JSP -Puntos de Extension +Puntos de Extensión =================== -|Fess| proporciona los siguientes puntos de extension: +|Fess| ofrece los siguientes puntos de extensión: Plugins ------- -Puede agregar funcionalidad utilizando plugins. +Puede agregar funciones utilizando plugins. -- **Plugin de almacen de datos**: Rastreo desde nuevas fuentes de datos -- **Plugin de motor de scripts**: Soporte para nuevos lenguajes de script -- **Plugin de aplicacion web**: Extension de la interfaz web -- **Plugin Ingest**: Procesamiento de datos durante la indexacion +- **Plugin de almacén de datos**: Rastreo desde nuevas fuentes de datos (extiende ``AbstractDataStore``) +- **Plugin de motor de scripts**: Compatibilidad con nuevos lenguajes de script (implementa ``ScriptEngine``) +- **Plugin de aplicación web**: Extensión de la interfaz web (sobrescritura de componentes de Lasta Di y fusión de recursos) +- **Plugin Ingest**: Procesamiento de datos durante la indexación (extiende ``Ingester``) Detalles: :doc:`plugin-architecture` +.. note:: + + El propio |Fess| se empaqueta como ``war``. Al compilar plugins localmente, si no se puede + resolver |Fess| como dependencia, cambie temporalmente ```` en ``pom.xml`` a ``jar``, + ejecute ``mvn clean install -DskipTests`` y luego vuelva a cambiarlo a ``war``. + Temas ----- -Puede personalizar el diseno de la pantalla de busqueda. +Puede personalizar el diseño de la pantalla de búsqueda. Detalles: :doc:`theme-development` -Configuracion +Configuración ------------- -Puede personalizar muchos comportamientos en ``fess_config.properties``. +Puede personalizar muchos comportamientos mediante ``fess_config.properties``. Detalles: :doc:`../config/intro` Desarrollo de Plugins ===================== -Para detalles sobre el desarrollo de plugins, consulte lo siguiente: +Para obtener más detalles sobre el desarrollo de plugins, consulte lo siguiente: - :doc:`plugin-architecture` - Arquitectura de plugins -- :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 +- :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 Ingest Desarrollo de Temas =================== -- :doc:`theme-development` - Personalizacion de temas +- :doc:`theme-development` - Personalización de temas -Mejores Practicas +Mejores Prácticas ================= -Convenciones de Codificacion +Convenciones de Codificación ---------------------------- -- Seguir el estilo de codigo existente de |Fess| -- Formatear codigo con ``mvn formatter:format`` +- Seguir el estilo de código existente de |Fess| +- Formatear el código con ``mvn formatter:format`` - Agregar encabezados de licencia con ``mvn license:format`` Pruebas ------- -- Escribir pruebas unitarias (``*Test.java``) -- Las pruebas de integracion son ``*Tests.java`` +- Pruebas unitarias (``*Test.java``): se ejecutan con ``mvn test`` en el perfil ``build`` predeterminado +- Pruebas de integración (``*Tests.java``): se ejecutan con ``mvn test -P integrationTests``. + Para ejecutar las pruebas de integración se necesita un servidor |Fess| en ejecución y OpenSearch Registro -------- -- Usar Log4j2 +- Utiliza Log4j2 - ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` -- No registrar informacion sensible +- No registrar información sensible en los registros Recursos ======== -- `Repositorio GitHub `__ -- `Rastreador de Problemas `__ +- `Repositorio de GitHub `__ +- `Seguimiento de problemas `__ - `Discusiones `__ diff --git a/fr/15.8/dev/overview.rst b/fr/15.8/dev/overview.rst index 64303e79..e8ca1f9f 100644 --- a/fr/15.8/dev/overview.rst +++ b/fr/15.8/dev/overview.rst @@ -1,68 +1,110 @@ -================================== -Vue d'ensemble developpeur -================================== +==================================================== +Aperçu de la documentation pour les développeurs +==================================================== Vue d'ensemble ============== -Cette section decrit le developpement d'extensions pour |Fess|. -Elle fournit des informations sur le developpement de plugins, la creation de connecteurs personnalises, -la personnalisation de themes, etc. +Cette section décrit le développement d'extensions pour |Fess|. +Elle fournit des informations pour étendre |Fess|, telles que le développement +de plugins, la création de connecteurs personnalisés et la personnalisation +de thèmes. Public cible ============ -- Developpeurs souhaitant creer des fonctionnalites personnalisees pour |Fess| -- Developpeurs souhaitant creer des plugins -- Developpeurs souhaitant comprendre le code source de |Fess| +- Développeurs souhaitant développer des fonctionnalités personnalisées pour |Fess| +- Développeurs souhaitant créer des plugins +- Développeurs souhaitant comprendre le code source de |Fess| -Connaissances prealables ------------------------- +Connaissances préalables +------------------------- - Connaissances de base de Java 21 -- Bases de Maven (systeme de build) -- Experience en developpement d'applications web +- Bases de Maven (système de build) +- Expérience en développement d'applications web +- Connaissances de base d'OpenSearch (|Fess| utilise OpenSearch comme moteur de recherche) -Environnement de developpement -============================== +Environnement de développement +=============================== -Environnement recommande ------------------------- +Environnement recommandé +-------------------------- -- **JDK**: OpenJDK 21 ou superieur -- **IDE**: IntelliJ IDEA / Eclipse / VS Code -- **Outil de build**: Maven 3.9 ou superieur -- **Git**: Gestion de versions +- **JDK** : OpenJDK 21 ou supérieur +- **IDE** : IntelliJ IDEA / Eclipse / VS Code +- **Outil de build** : Maven (le build n'impose pas de version minimale, mais une version 3.x récente prenant en charge Java 21 est recommandée) +- **Git** : gestion de versions +- **OpenSearch** : moteur de recherche backend (si vous démarrez depuis l'IDE, les modules et plugins nécessaires sont téléchargés lors du build) -Configuration +Installation ------------- -1. Recuperation du code source: +|Fess| se construit comme un projet Maven. Lors du développement, il est plus +simple de le démarrer depuis l'IDE. -:: +1. Récupération du code source : - git clone https://github.com/codelibs/fess.git - cd fess + :: -2. Build: + git clone https://github.com/codelibs/fess.git -:: +2. Importation dans l'IDE : - mvn package -DskipTests + Importez le répertoire récupéré dans l'IDE en tant que projet Maven. -3. Demarrage du serveur de developpement: +3. Téléchargement des modules et plugins pour OpenSearch : -:: + Uniquement lors de la première exécution, récupérez les modules et plugins + du moteur de recherche dans le répertoire ``plugins`` avec la commande + suivante : + + :: + + mvn antrun:run + +4. Démarrage du serveur de développement (depuis l'IDE) : + + Exécutez ou déboguez ``org.codelibs.fess.FessBoot`` dans l'IDE, puis ouvrez + http://localhost:8080/ dans votre navigateur. + L'écran d'administration se trouve à l'adresse http://localhost:8080/admin/ + (compte initial : ``admin`` / ``admin``). + +5. Construction du package (création de la distribution) : + + Si vous avez besoin d'un package de distribution, exécutez le goal + ``package``. Le résultat est généré dans ``target/releases`` (ajoutez + ``-DskipTests`` pour ignorer les tests unitaires). + + :: + + mvn package + + Une fois la distribution générée décompressée, le script de démarrage + ``bin/fess`` est disponible. + + :: - ./bin/fess + unzip target/releases/fess-*.zip + ./fess-*/bin/fess -Apercu de l'architecture -======================== +.. note:: -|Fess| est compose des composants principaux suivants: + Le script de démarrage ``bin/fess`` est inclus dans le package de + distribution (zip/rpm/deb). + Le simple fait d'exécuter ``mvn package`` dans l'arborescence source ne + génère pas ``bin/fess`` à la racine du dépôt. + Pour développer à partir des sources, exécutez ``FessBoot`` dans l'IDE + comme indiqué ci-dessus, ou utilisez le ``bin/fess`` de la distribution + décompressée. + +Aperçu de l'architecture +========================= + +|Fess| est composé des composants principaux suivants : Structure des composants ------------------------- +-------------------------- .. list-table:: :header-rows: 1 @@ -71,118 +113,136 @@ Structure des composants * - Composant - Description * - Couche Web - - Implementation MVC avec le framework LastaFlute + - Implémentation MVC avec le framework LastaFlute * - Couche Service - - Logique metier - * - Couche d'acces aux donnees - - Integration OpenSearch via DBFlute + - Logique métier + * - Couche d'accès aux données + - Accès type-safe à OpenSearch via DBFlute (ESFlute/FreeGen) * - Crawler - - Collecte de contenu via la bibliotheque fess-crawler + - Collecte de contenu via la bibliothèque fess-crawler * - Moteur de recherche - Recherche plein texte avec OpenSearch Frameworks principaux ---------------------- +----------------------- -- **LastaFlute**: Framework web (actions, formulaires, validation) -- **DBFlute**: Framework d'acces aux donnees (integration OpenSearch) -- **Lasta Di**: Conteneur d'injection de dependances +- **LastaFlute** : framework web (actions, formulaires, validation) +- **DBFlute** : framework d'accès aux données. Les classes d'accès type-safe + pour OpenSearch (``Bhv`` / ``ConditionBean``) sont générées par la + fonctionnalité FreeGen de DBFlute et les templates ESFlute (régénération + via ``mvn dbflute:freegen``) +- **Lasta Di** : conteneur d'injection de dépendances -Structure des repertoires -========================= +Structure des répertoires +=========================== :: fess/ ├── src/main/java/org/codelibs/fess/ │ ├── app/ - │ │ ├── web/ # Controleurs (Action) + │ │ ├── web/ # Contrôleurs (Action) │ │ ├── service/ # Services + │ │ ├── logic/ # Logique │ │ └── pager/ # Pagination - │ ├── api/ # API REST + │ ├── api/ # API REST (api/v2, etc.) │ ├── helper/ # Classes utilitaires - │ ├── crawler/ # Fonctionnalites du crawler - │ ├── opensearch/ # Integration OpenSearch (genere par DBFlute) - │ ├── llm/ # Integration LLM - │ └── ds/ # Connecteurs de datastore + │ ├── crawler/ # Fonctionnalités liées au crawler + │ ├── indexer/ # Traitement d'indexation + │ ├── opensearch/ # Accès OpenSearch (généré par ESFlute/FreeGen) + │ ├── llm/ # Intégration LLM + │ ├── ds/ # Connecteurs de datastore + │ ├── ingest/ # Ingest (traitement des données lors de l'indexation) + │ ├── script/ # Moteur de script + │ ├── entity/ # Entités + │ └── mylasta/ # Configuration LastaFlute (DI, messages, configuration type-safe) ├── src/main/resources/ │ ├── fess_config.properties # Configuration - │ └── fess_*.xml # Configuration DI + │ └── fess_*.xml # Configuration DI (app.xml, fess_ds.xml, etc.) └── src/main/webapp/ └── WEB-INF/view/ # Templates JSP Points d'extension -================== +==================== -|Fess| fournit les points d'extension suivants: +|Fess| fournit les points d'extension suivants : Plugins -------- +-------- -Vous pouvez ajouter des fonctionnalites via des plugins. +Vous pouvez ajouter des fonctionnalités à l'aide de plugins. -- **Plugins DataStore**: Crawl depuis de nouvelles sources de donnees -- **Plugins Script Engine**: Support de nouveaux langages de script -- **Plugins WebApp**: Extension de l'interface web -- **Plugins Ingest**: Traitement des donnees lors de l'indexation +- **Plugin DataStore** : exploration depuis de nouvelles sources de données (hérite de ``AbstractDataStore``) +- **Plugin de moteur de script** : prise en charge de nouveaux langages de script (implémente ``ScriptEngine``) +- **Plugin d'application Web** : extension de l'interface web (surcharge de composants Lasta Di et fusion de ressources) +- **Plugin Ingest** : traitement des données lors de l'indexation (hérite de ``Ingester``) -Details: :doc:`plugin-architecture` +Détails : :doc:`plugin-architecture` -Themes ------- +.. note:: -Vous pouvez personnaliser le design de l'ecran de recherche. + |Fess| lui-même est empaqueté sous forme de ``war``. Si vous ne parvenez + pas à résoudre |Fess| comme dépendance lors de la construction locale + d'un plugin, modifiez temporairement ```` dans ``pom.xml`` en + ``jar``, exécutez ``mvn clean install -DskipTests``, puis revenez à + ``war``. -Details: :doc:`theme-development` +Thèmes +------- + +Vous pouvez personnaliser le design de l'écran de recherche. + +Détails : :doc:`theme-development` Configuration -------------- +--------------- -De nombreux comportements peuvent etre personnalises via ``fess_config.properties``. +``fess_config.properties`` permet de personnaliser de nombreux comportements. -Details: :doc:`../config/intro` +Détails : :doc:`../config/intro` -Developpement de plugins -======================== +Développement de plugins +========================== -Pour plus de details sur le developpement de plugins, consultez: +Pour plus de détails sur le développement de plugins, consultez : - :doc:`plugin-architecture` - Architecture des plugins -- :doc:`datastore-plugin` - Developpement de plugins DataStore -- :doc:`script-engine-plugin` - Plugins Script Engine -- :doc:`webapp-plugin` - Plugins WebApp -- :doc:`ingest-plugin` - Plugins Ingest +- :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 -Developpement de themes -======================= +Développement de thèmes +========================= -- :doc:`theme-development` - Personnalisation des themes +- :doc:`theme-development` - Personnalisation des thèmes Bonnes pratiques -================ +================== Conventions de codage ---------------------- +----------------------- - Suivre le style de code existant de |Fess| - Formater le code avec ``mvn formatter:format`` -- Ajouter les en-tetes de licence avec ``mvn license:format`` +- Ajouter les en-têtes de licence avec ``mvn license:format`` Tests ------ +------ -- Ecrire des tests unitaires (``*Test.java``) -- Les tests d'integration sont ``*Tests.java`` +- Tests unitaires (``*Test.java``) : exécutés via ``mvn test`` dans le profil ``build`` par défaut +- Tests d'intégration (``*Tests.java``) : exécutés via ``mvn test -P integrationTests``. + L'exécution des tests d'intégration nécessite un serveur |Fess| et une instance OpenSearch en cours de fonctionnement Journalisation --------------- +--------------- -- Utiliser Log4j2 +- Utilise Log4j2 - ``logger.debug()`` / ``logger.info()`` / ``logger.warn()`` / ``logger.error()`` - Ne pas journaliser d'informations sensibles Ressources -========== +=========== - `GitHub Repository `__ - `Issue Tracker `__ diff --git a/ja/15.8/dev/overview.rst b/ja/15.8/dev/overview.rst index 3c23aee5..a31b45f0 100644 --- a/ja/15.8/dev/overview.rst +++ b/ja/15.8/dev/overview.rst @@ -22,6 +22,7 @@ - Java 21の基本的な知識 - Maven（ビルドシステム）の基本 - Webアプリケーション開発の経験 +- OpenSearchの基本的な知識（|Fess| は検索エンジンとして OpenSearch を使用します） 開発環境 ======== @@ -31,30 +32,61 @@ - **JDK**: OpenJDK 21以上 - **IDE**: IntelliJ IDEA / Eclipse / VS Code -- **ビルドツール**: Maven 3.9以上 +- **ビルドツール**: Maven（ビルドで最小バージョンは強制されていませんが、Java 21 に対応する新しめの 3.x を推奨） - **Git**: バージョン管理 +- **OpenSearch**: 検索エンジンのバックエンド（IDEから起動する場合、必要なモジュールとプラグインはビルド時にダウンロードされます） セットアップ ------------ +|Fess| は Maven プロジェクトとしてビルドします。開発時は IDE から起動するのが最も簡単です。 + 1. ソースコードの取得: -:: + :: - git clone https://github.com/codelibs/fess.git - cd fess + git clone https://github.com/codelibs/fess.git -2. ビルド: +2. IDEへのインポート: -:: + 取得したディレクトリを Maven プロジェクトとして IDE にインポートします。 - mvn package -DskipTests +3. OpenSearch用モジュール・プラグインのダウンロード: -3. 開発サーバーの起動: + 初回のみ、以下のコマンドで検索エンジンのモジュールとプラグインを ``plugins`` ディレクトリに取得します。 -:: + :: + + mvn antrun:run + +4. 開発サーバーの起動（IDEから）: + + IDE上で ``org.codelibs.fess.FessBoot`` を実行またはデバッグ実行し、 + ブラウザで http://localhost:8080/ を開きます。 + 管理画面は http://localhost:8080/admin/ （初期アカウント: ``admin`` / ``admin``）です。 + +5. パッケージのビルド（配布物の作成）: + + 配布パッケージが必要な場合は ``package`` ゴールを実行します。 + 成果物は ``target/releases`` に生成されます（ユニットテストを省略するには ``-DskipTests`` を付与）。 - ./bin/fess + :: + + mvn package + + 生成された配布物を展開すると ``bin/fess`` 起動スクリプトが利用できます。 + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + ``bin/fess`` 起動スクリプトは配布パッケージ（zip/rpm/deb）に含まれるものです。 + ソースツリーで ``mvn package`` を実行しただけでは、リポジトリ直下に ``bin/fess`` は生成されません。 + ソースからの開発では、上記のように IDE で ``FessBoot`` を実行するか、 + 展開した配布物の ``bin/fess`` を使用してください。 アーキテクチャ概要 ================== @@ -75,7 +107,7 @@ * - サービス層 - ビジネスロジック * - データアクセス層 - - DBFluteによるOpenSearch連携 + - DBFlute（ESFlute/FreeGen）による型安全なOpenSearchアクセス * - クローラー - fess-crawlerライブラリによるコンテンツ収集 * - 検索エンジン @@ -85,7 +117,9 @@ ------------------ - **LastaFlute**: Webフレームワーク（アクション、フォーム、バリデーション） -- **DBFlute**: データアクセスフレームワーク（OpenSearch連携） +- **DBFlute**: データアクセスフレームワーク。OpenSearch向けの型安全なアクセスクラス（``Bhv`` / ``ConditionBean``）は、 + DBFlute の FreeGen 機能と ESFlute テンプレートによって生成されます + （再生成は ``mvn dbflute:freegen``） - **Lasta Di**: 依存性注入コンテナ ディレクトリ構造 @@ -98,16 +132,22 @@ │ ├── app/ │ │ ├── web/ # コントローラー（Action） │ │ ├── service/ # サービス + │ │ ├── logic/ # ロジック │ │ └── pager/ # ページネーション - │ ├── api/ # REST API + │ ├── api/ # REST API（api/v2 など） │ ├── helper/ # ヘルパークラス │ ├── crawler/ # クローラー関連 - │ ├── opensearch/ # OpenSearch連携（DBFlute生成） + │ ├── indexer/ # インデックス処理 + │ ├── opensearch/ # OpenSearchアクセス（ESFlute/FreeGen生成） │ ├── llm/ # LLM統合 - │ └── ds/ # データストアコネクタ + │ ├── ds/ # データストアコネクタ + │ ├── ingest/ # Ingest（インデックス時のデータ加工） + │ ├── script/ # スクリプトエンジン + │ ├── entity/ # エンティティ + │ └── mylasta/ # LastaFlute設定（DI・メッセージ・型安全設定） ├── src/main/resources/ │ ├── fess_config.properties # 設定 - │ └── fess_*.xml # DI設定 + │ └── fess_*.xml # DI設定（app.xml, fess_ds.xml など） └── src/main/webapp/ └── WEB-INF/view/ # JSPテンプレート @@ -121,13 +161,19 @@ プラグインを使用して機能を追加できます。 -- **データストアプラグイン**: 新しいデータソースからのクロール -- **スクリプトエンジンプラグイン**: 新しいスクリプト言語のサポート -- **Webアプリプラグイン**: Webインターフェースの拡張 -- **Ingestプラグイン**: インデックス時のデータ加工 +- **データストアプラグイン**: 新しいデータソースからのクロール（``AbstractDataStore`` を継承） +- **スクリプトエンジンプラグイン**: 新しいスクリプト言語のサポート（``ScriptEngine`` を実装） +- **Webアプリプラグイン**: Webインターフェースの拡張（Lasta Di のコンポーネント上書きとリソースのマージ） +- **Ingestプラグイン**: インデックス時のデータ加工（``Ingester`` を継承） 詳細: :doc:`plugin-architecture` +.. note:: + + |Fess| 本体は ``war`` としてパッケージングされます。プラグインをローカルでビルドする際に、 + |Fess| を依存関係として解決できない場合は、``pom.xml`` の ```` を一時的に ``jar`` に変更して + ``mvn clean install -DskipTests`` を実行し、その後 ``war`` に戻してください。 + テーマ ------ @@ -171,8 +217,9 @@ テスト ------ -- ユニットテストを記述（``*Test.java``） -- 統合テストは ``*Tests.java`` +- ユニットテスト（``*Test.java``）: デフォルトの ``build`` プロファイルで ``mvn test`` として実行されます +- 統合テスト（``*Tests.java``）: ``mvn test -P integrationTests`` で実行されます。 + 統合テストの実行には、稼働中の |Fess| サーバーと OpenSearch が必要です ロギング -------- diff --git a/ko/15.8/dev/overview.rst b/ko/15.8/dev/overview.rst index e910ce7c..424279ec 100644 --- a/ko/15.8/dev/overview.rst +++ b/ko/15.8/dev/overview.rst @@ -10,51 +10,83 @@ |Fess| 를 확장하기 위한 정보를 제공합니다. 대상 독자 -======== +========== - |Fess| 의 커스텀 기능을 개발하고 싶은 개발자 - 플러그인을 작성하고 싶은 개발자 - |Fess| 의 소스 코드를 이해하고 싶은 개발자 필요 지식 --------- +---------- - Java 21의 기본적인 지식 - Maven(빌드 시스템)의 기본 - 웹 애플리케이션 개발 경험 +- OpenSearch에 대한 기본적인 지식(|Fess| 는 검색 엔진으로 OpenSearch를 사용합니다) 개발 환경 -======== +========== 권장 환경 --------- +---------- - **JDK**: OpenJDK 21 이상 - **IDE**: IntelliJ IDEA / Eclipse / VS Code -- **빌드 도구**: Maven 3.9 이상 +- **빌드 도구**: Maven(빌드에서 최소 버전이 강제되지는 않지만, Java 21에 대응하는 최신 3.x를 권장) - **Git**: 버전 관리 +- **OpenSearch**: 검색 엔진의 백엔드(IDE에서 실행하는 경우, 필요한 모듈과 플러그인은 빌드 시 다운로드됩니다) 설정 ------------ +|Fess| 는 Maven 프로젝트로 빌드합니다. 개발 시에는 IDE에서 실행하는 것이 가장 간단합니다. + 1. 소스 코드 취득: -:: + :: - git clone https://github.com/codelibs/fess.git - cd fess + git clone https://github.com/codelibs/fess.git -2. 빌드: +2. IDE로 임포트: -:: + 취득한 디렉토리를 Maven 프로젝트로 IDE에 임포트합니다. - mvn package -DskipTests +3. OpenSearch용 모듈·플러그인 다운로드: -3. 개발 서버 시작: + 최초 한 번만 다음 명령으로 검색 엔진의 모듈과 플러그인을 ``plugins`` 디렉토리에 취득합니다. -:: + :: + + mvn antrun:run - ./bin/fess +4. 개발 서버 시작(IDE에서): + + IDE에서 ``org.codelibs.fess.FessBoot`` 를 실행 또는 디버그 실행하고, + 브라우저에서 http://localhost:8080/ 을 엽니다. + 관리 화면은 http://localhost:8080/admin/ (초기 계정: ``admin`` / ``admin``)입니다. + +5. 패키지 빌드(배포물 생성): + + 배포 패키지가 필요한 경우 ``package`` 골을 실행합니다. + 결과물은 ``target/releases`` 에 생성됩니다(유닛 테스트를 건너뛰려면 ``-DskipTests`` 를 지정). + + :: + + mvn package + + 생성된 배포물을 압축 해제하면 ``bin/fess`` 실행 스크립트를 사용할 수 있습니다. + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + ``bin/fess`` 실행 스크립트는 배포 패키지(zip/rpm/deb)에 포함되어 있는 것입니다. + 소스 트리에서 ``mvn package`` 를 실행하는 것만으로는 저장소 바로 아래에 ``bin/fess`` 가 생성되지 않습니다. + 소스에서 개발할 때는 위와 같이 IDE에서 ``FessBoot`` 를 실행하거나, + 압축을 해제한 배포물의 ``bin/fess`` 를 사용하세요. 아키텍처 개요 ================== @@ -75,7 +107,7 @@ * - 서비스층 - 비즈니스 로직 * - 데이터 액세스층 - - DBFlute에 의한 OpenSearch 연계 + - DBFlute(ESFlute/FreeGen)에 의한 타입 세이프 OpenSearch 액세스 * - 크롤러 - fess-crawler 라이브러리에 의한 콘텐츠 수집 * - 검색 엔진 @@ -84,8 +116,10 @@ 주요 프레임워크 ------------------ -- **LastaFlute**: 웹 프레임워크 (액션, 폼, 밸리데이션) -- **DBFlute**: 데이터 액세스 프레임워크 (OpenSearch 연계) +- **LastaFlute**: 웹 프레임워크(액션, 폼, 밸리데이션) +- **DBFlute**: 데이터 액세스 프레임워크. OpenSearch용 타입 세이프 액세스 클래스(``Bhv`` / ``ConditionBean``)는 + DBFlute의 FreeGen 기능과 ESFlute 템플릿에 의해 생성됩니다 + (재생성은 ``mvn dbflute:freegen``) - **Lasta Di**: 의존성 주입 컨테이너 디렉토리 구조 @@ -98,16 +132,22 @@ │ ├── app/ │ │ ├── web/ # 컨트롤러(Action) │ │ ├── service/ # 서비스 + │ │ ├── logic/ # 로직 │ │ └── pager/ # 페이지네이션 - │ ├── api/ # REST API + │ ├── api/ # REST API(api/v2 등) │ ├── helper/ # 헬퍼 클래스 │ ├── crawler/ # 크롤러 관련 - │ ├── opensearch/ # OpenSearch 연계(DBFlute 생성) + │ ├── indexer/ # 인덱스 처리 + │ ├── opensearch/ # OpenSearch 액세스(ESFlute/FreeGen 생성) │ ├── llm/ # LLM 통합 - │ └── ds/ # 데이터스토어 커넥터 + │ ├── ds/ # 데이터스토어 커넥터 + │ ├── ingest/ # Ingest(인덱싱 시 데이터 가공) + │ ├── script/ # 스크립트 엔진 + │ ├── entity/ # 엔티티 + │ └── mylasta/ # LastaFlute 설정(DI·메시지·타입 세이프 설정) ├── src/main/resources/ │ ├── fess_config.properties # 설정 - │ └── fess_*.xml # DI 설정 + │ └── fess_*.xml # DI 설정(app.xml, fess_ds.xml 등) └── src/main/webapp/ └── WEB-INF/view/ # JSP 템플릿 @@ -121,13 +161,19 @@ 플러그인을 사용하여 기능을 추가할 수 있습니다. -- **데이터스토어 플러그인**: 새로운 데이터 소스에서 크롤링 -- **스크립트 엔진 플러그인**: 새로운 스크립트 언어 지원 -- **웹앱 플러그인**: 웹 인터페이스 확장 -- **Ingest 플러그인**: 인덱싱 시 데이터 가공 +- **데이터스토어 플러그인**: 새로운 데이터 소스로부터의 크롤링(``AbstractDataStore`` 를 상속) +- **스크립트 엔진 플러그인**: 새로운 스크립트 언어 지원(``ScriptEngine`` 을 구현) +- **웹앱 플러그인**: 웹 인터페이스 확장(Lasta Di의 컴포넌트 오버라이드와 리소스 병합) +- **Ingest 플러그인**: 인덱싱 시 데이터 가공(``Ingester`` 를 상속) 상세: :doc:`plugin-architecture` +.. note:: + + |Fess| 본체는 ``war`` 로 패키징됩니다. 플러그인을 로컬에서 빌드할 때 + |Fess| 를 의존성으로 해결할 수 없는 경우에는, ``pom.xml`` 의 ```` 을 일시적으로 ``jar`` 로 변경하여 + ``mvn clean install -DskipTests`` 를 실행한 후, ``war`` 로 되돌리세요. + 테마 ------ @@ -171,8 +217,9 @@ 테스트 ------ -- 유닛 테스트 작성 (``*Test.java``) -- 통합 테스트는 ``*Tests.java`` +- 유닛 테스트(``*Test.java``): 기본 ``build`` 프로파일에서 ``mvn test`` 로 실행됩니다 +- 통합 테스트(``*Tests.java``): ``mvn test -P integrationTests`` 로 실행됩니다. + 통합 테스트를 실행하려면 실행 중인 |Fess| 서버와 OpenSearch가 필요합니다 로깅 -------- diff --git a/zh-cn/15.8/dev/overview.rst b/zh-cn/15.8/dev/overview.rst index 28df2898..25c72994 100644 --- a/zh-cn/15.8/dev/overview.rst +++ b/zh-cn/15.8/dev/overview.rst @@ -22,6 +22,7 @@ - Java 21的基本知识 - Maven（构建系统）基础 - Web应用程序开发经验 +- OpenSearch的基本知识（|Fess| 使用OpenSearch作为搜索引擎） 开发环境 ======== @@ -31,30 +32,61 @@ - **JDK**: OpenJDK 21以上 - **IDE**: IntelliJ IDEA / Eclipse / VS Code -- **构建工具**: Maven 3.9以上 +- **构建工具**: Maven（构建过程未强制规定最低版本，但推荐使用支持Java 21的较新3.x版本） - **Git**: 版本管理 +- **OpenSearch**: 搜索引擎后端（从IDE启动时，所需的模块和插件会在构建时下载） 环境配置 -------- +|Fess| 作为Maven项目进行构建。开发时最简单的方式是从IDE启动。 + 1. 获取源代码: -:: + :: - git clone https://github.com/codelibs/fess.git - cd fess + git clone https://github.com/codelibs/fess.git -2. 构建: +2. 导入到IDE: -:: + 将获取到的目录作为Maven项目导入到IDE中。 - mvn package -DskipTests +3. 下载OpenSearch所需的模块和插件: -3. 启动开发服务器: + 仅首次需要执行以下命令，将搜索引擎的模块和插件获取到 ``plugins`` 目录中。 -:: + :: + + mvn antrun:run + +4. 启动开发服务器（从IDE）: + + 在IDE中运行或以调试方式运行 ``org.codelibs.fess.FessBoot``， + 然后在浏览器中打开 http://localhost:8080/。 + 管理界面为 http://localhost:8080/admin/ （初始账号: ``admin`` / ``admin``）。 + +5. 构建软件包（生成分发包）: + + 如果需要分发包，请执行 ``package`` 目标。 + 生成的成果物会输出到 ``target/releases`` 中（如需跳过单元测试，请添加 ``-DskipTests``）。 - ./bin/fess + :: + + mvn package + + 展开生成的分发包后，即可使用 ``bin/fess`` 启动脚本。 + + :: + + unzip target/releases/fess-*.zip + ./fess-*/bin/fess + +.. note:: + + ``bin/fess`` 启动脚本包含在分发包（zip/rpm/deb）中。 + 仅在源代码目录中执行 ``mvn package``，并不会在仓库根目录下生成 ``bin/fess``。 + 在基于源代码进行开发时，请按照上文所述在IDE中运行 ``FessBoot``， + 或使用展开后的分发包中的 ``bin/fess``。 架构概述 ======== @@ -75,7 +107,7 @@ * - 服务层 - 业务逻辑 * - 数据访问层 - - 通过DBFlute与OpenSearch集成 + - 通过DBFlute（ESFlute/FreeGen）实现的类型安全的OpenSearch访问 * - 爬虫 - 使用fess-crawler库进行内容收集 * - 搜索引擎 @@ -85,7 +117,9 @@ -------- - **LastaFlute**: Web框架（Action、Form、Validation） -- **DBFlute**: 数据访问框架（OpenSearch集成） +- **DBFlute**: 数据访问框架。面向OpenSearch的类型安全访问类（``Bhv`` / ``ConditionBean``） + 由DBFlute的FreeGen功能与ESFlute模板生成 + （重新生成命令为 ``mvn dbflute:freegen``） - **Lasta Di**: 依赖注入容器 目录结构 @@ -98,16 +132,22 @@ │ ├── app/ │ │ ├── web/ # 控制器（Action） │ │ ├── service/ # 服务 + │ │ ├── logic/ # 逻辑 │ │ └── pager/ # 分页 - │ ├── api/ # REST API + │ ├── api/ # REST API（如api/v2） │ ├── helper/ # 辅助类 │ ├── crawler/ # 爬虫相关 - │ ├── opensearch/ # OpenSearch集成（DBFlute生成） + │ ├── indexer/ # 索引处理 + │ ├── opensearch/ # OpenSearch访问（ESFlute/FreeGen生成） │ ├── llm/ # LLM集成 - │ └── ds/ # 数据存储连接器 + │ ├── ds/ # 数据存储连接器 + │ ├── ingest/ # Ingest（索引时的数据加工） + │ ├── script/ # 脚本引擎 + │ ├── entity/ # 实体 + │ └── mylasta/ # LastaFlute配置（DI、消息、类型安全配置） ├── src/main/resources/ │ ├── fess_config.properties # 配置 - │ └── fess_*.xml # DI配置 + │ └── fess_*.xml # DI配置（如app.xml、fess_ds.xml） └── src/main/webapp/ └── WEB-INF/view/ # JSP模板 @@ -121,13 +161,19 @@ 使用插件可以添加功能。 -- **数据存储插件**: 从新数据源爬取 -- **脚本引擎插件**: 支持新的脚本语言 -- **Web应用插件**: 扩展Web界面 -- **Ingest插件**: 索引时的数据处理 +- **数据存储插件**: 从新数据源进行爬取（继承 ``AbstractDataStore``） +- **脚本引擎插件**: 支持新的脚本语言（实现 ``ScriptEngine``） +- **Web应用插件**: 扩展Web界面（通过Lasta Di的组件覆盖与资源合并） +- **Ingest插件**: 索引时的数据加工（继承 ``Ingester``） 详情: :doc:`plugin-architecture` +.. note:: + + |Fess| 本体以 ``war`` 形式打包。在本地构建插件时， + 如果无法将 |Fess| 解析为依赖项，请将 ``pom.xml`` 中的 ```` 临时改为 ``jar``， + 执行 ``mvn clean install -DskipTests``，然后再改回 ``war``。 + 主题 ---- @@ -171,8 +217,9 @@ 测试 ---- -- 编写单元测试（``*Test.java``） -- 集成测试使用 ``*Tests.java`` +- 单元测试（``*Test.java``）: 在默认的 ``build`` 配置文件下作为 ``mvn test`` 执行 +- 集成测试（``*Tests.java``）: 通过 ``mvn test -P integrationTests`` 执行。 + 执行集成测试需要运行中的 |Fess| 服务器与OpenSearch 日志 ---- @@ -187,4 +234,3 @@ - `GitHub Repository `__ - `Issue Tracker `__ - `Discussions `__ -