Projekt beállítás

2.1   Előfeltételek

2.2   Maven repository beállítása

A platform-sdk és a platform-bom a platform privát Apache Archiva repository-jából érhető el. A hozzáférési adatokat (felhasználónév, jelszó) a platform üzemeltetőjétől kell igényelni; ezeket a Maven settings.xml fájlba kell felvenni (~/.m2/settings.xml):

<settings>
  <servers>
    <server>
      <id>maven.private-ai.hu</id>
      <username>FELHASZNÁLÓNÉV</username>
      <password>JELSZÓ</password>
    </server>
  </servers>
</settings>

A repository URL-ek a parent POM-ban már elő vannak konfigurálva (lásd 2.3), ezért a settings.xml-be csak a hitelesítés kerül.

2.3   A projekt struktúrája

Egy plugin projekt két POM-rétegből áll:

• plugin-parent – a platform által biztosított szülő POM. Tartalmazza a platform-bom importot, az SDK függőséget, a build konfigurációt (JAR elnevezés, lib/ másolás) és a repository URL-eket. Ezt a POM-ot nem kell módosítani.
• Saját plugin modul – a plugin-parent-ből örökölő, minimális POM. Ide kerülnek a plugin saját függőségei (ha vannak). A platform SDK-t és BOM-ot nem kell megismételni.

A könyvtárstruktúra:

my-plugins/                          ← a plugin projekt gyökere
  pom.xml                            ← plugin-parent POM (platform adja)
  hu.medical.rag.plugin.myplugin/    ← saját plugin modul
    pom.xml                          ← minimális modul POM
    src/
      main/
        java/
          hu/medical/rag/plugin/myplugin/
            tool/
              MyTool.java
            tool/beans/
              MyRequest.java
            configurer/
              MyPluginConfigurer.java  ← opcionális (ha extra Spring bean kell)
        resources/
          META-INF/services/
            hu.medical.rag.common.tool.intf.IChatbotTool      ← tool-ok regisztrációja
            hu.medical.rag.common.plugin.IPluginConfigurer    ← opcionális, ha van configurer
          plugin.properties                                    ← opcionális konfiguráció

A plugin.properties az egyetlen fájl, amelyet a platform a JAR-on kívülről olvas – a deploy könyvtárból (nem a JAR belsejéből). Ha a plugin konfigurálható értékeket igényel (pl. adatbázis host, külső API végpont), ide kerülnek. A @Value("${plugin.mydb.host}") annotált mezők automatikusan feltöltődnek. Részletek: 11. fejezet.

2.4   A plugin-parent POM

A plugin-parent/pom.xml-t a platform biztosítja. A legfontosabb részek:

Platform BOM import

A BOM gondoskodik arról, hogy a platform összes tranzitív függősége (Spring, Jackson, ArangoDB driver stb.) provided scope-ot kapjon. Így a build csak a plugin saját egyedi függőségeit másolja a lib/ könyvtárba.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>hu.medical.rag</groupId>
      <artifactId>platform-bom</artifactId>
      <version>${medical.rag.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Platform SDK függőség

Az SDK tartalmazza az összes publikus interfészt (IChatbotTool, ILlmAssistant stb.), az abstract alaposztályokat és a bean-eket. A scope és verzió a platform-bom importból automatikusan öröklődik.

<dependency>
  <groupId>hu.medical.rag</groupId>
  <artifactId>platform-sdk</artifactId>
  <!-- scope és version: platform-bom-ból jön -->
</dependency>

Build: JAR elnevezés és könyvtár

A build mindig plugin.jar nevű fájlt hoz létre a target/plugins/{artifactId}/ könyvtárban. Ez a struktúra egyezik a production deploy könyvtárstruktúrával – a fejlesztő egyszerűen átmásolja a könyvtárat a szerver plugins/ mappájába.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <configuration>
    <finalName>plugin</finalName>
    <outputDirectory>
      ${project.build.directory}/plugins/${project.artifactId}
    </outputDirectory>
  </configuration>
</plugin>

Build: saját függőségek másolása lib/-be

A maven-dependency-plugin a runtime scope-os JAR-okat másolja a lib/ könyvtárba. A provided scope-os platformfüggőségek – amelyeket a BOM import állított be – automatikusan kimaradnak.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <id>copy-plugin-dependencies</id>
      <phase>package</phase>
      <goals><goal>copy-dependencies</goal></goals>
      <configuration>
        <outputDirectory>
          ${project.build.directory}/plugins/${project.artifactId}/lib
        </outputDirectory>
        <includeScope>runtime</includeScope>
      </configuration>
    </execution>
  </executions>
</plugin>

2.5   A saját modul POM-ja

Ha a plugin-nek nincs saját külső függősége (például egy egyszerű, külső REST API-t a Java beépített HTTP kliensével hívó tool esetén), a modul POM minimális:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="...">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>hu.medical.rag.plugins</groupId>
    <artifactId>plugin-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>plugin-myplugin</artifactId>
  <name>My Plugin</name>

  <!-- Ha nincs extra függőség, a <dependencies> blokk elhagyható -->

</project>

Ha a plugin saját függőséget igényel (pl. egy külső adatbázis driver), azt compile scope-ban kell felvenni:

<dependencies>
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>my-driver</artifactId>
    <version>1.2.3</version>
    <!-- compile scope → bekerül a lib/-be -->
  </dependency>
</dependencies>

2.6   ServiceLoader regisztráció

A platform Java ServiceLoader mechanizmussal fedezi fel a plugin tool-okat. A JAR-ban létre kell hozni egy szöveges fájlt az alábbi elérési úton:

src/main/resources/META-INF/services/hu.medical.rag.common.tool.intf.IChatbotTool

A fájl tartalma soronként egy teljes osztálynév – minden tool, amelyet a platform-nak regisztrálni szeretnél:

hu.medical.rag.plugin.myplugin.tool.MyTool

Ha a plugin több tool-t tartalmaz:

hu.medical.rag.plugin.myplugin.tool.MyFirstTool
hu.medical.rag.plugin.myplugin.tool.MySecondTool

2.7   Build és kimeneti struktúra

A plugin buildelése:

mvn clean package

Sikeres build után a target/plugins/ könyvtárban megjelenik a kész plugin struktúra:

target/
  plugins/
    plugin-myplugin/         ← ezt a könyvtárat kell a szerverre másolni
      plugin.jar             ← a tool implementációk
      plugin.properties      ← opcionális konfiguráció (ha van)
      lib/                   ← saját függőségek (ha vannak)
        my-driver-1.2.3.jar

Ha a pluginnek nincs saját külső függősége, a lib/ könyvtár üres marad vagy el sem készül – ez helyes.

A plugin.properties a Maven build által a src/main/resources/-ból kerül ide (a parent POM resources plugin konfigurációja gondoskodik róla, hogy ne a JAR-ba, hanem mellé másolódjon). Deploy esetén ez a fájl környezetenként cserélhető – pl. a CI/CD pipeline felülírhatja az éles értékekkel.

A deploy lépésekről a 11. fejezet szól részletesen, de a lényeg: a plugin-myplugin/ könyvtárat kell átmásolni a szerver plugins/ mappájába.

2.8   Lombok használata

A parent POM konfigurálja a Lombok annotation processort, így a plugin kódjában közvetlenül használható a @Data, @Builder, @AllArgsConstructor és a többi Lombok annotáció – külön konfiguráció nélkül. Egy tool request bean-je például egyszerű getter/setter nélküli POJO-ként is megírható Lombok-kal:

import lombok.Data;

@Data
public class MyRequest {
    private String location;
    private Integer days;
}