Common XSD project

English version

Üdvözöljük a Common sémaleíró publikus tárhelyén!

1) A tárhely tartalma és célja

A tárhely abból a célból jött létre, hogy a NAV rendszereiben használt általánosan található atomi típusokat, üzleti katalógus jellegű elemeket, valamint a generikus API kommunikációt megvalósító típusokat egy külön, közös XSD-ben lehessen verziókezelni. Ez lehetővé teszi azt, hogy ezeket a séma elemeket több NAV-os projekt is felhasználhassa, ez által az API kommunikáció egységesíthető.

Kérjük figyelembe venni, hogy bár a tárhely publikusan elérhető, a véleményezéshez és a fejlesztéshez hozzájáruláshoz GitHub userre van szükség. A felhasználó ingyenesen, pár perc alatt létrehozható.

A projekt tartalma maga az XSD sémák, abból generált DTO objektumok és a olyan osztályok melyek a generálást kiszolgálják. Célja hogy ne legyenek redundáns elemek a különböző projektek között, egységes API kommunikációt biztosítva.

Maga a DTO generálás XSD Catalog alapon működik, ami lehetővé teszi a séma elemek központi kezelését és újrahasználatát.

schemaLocation vs XSD Catalog

<!-- schemaLocation megoldás -->
<xs:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/string" schemaLocation="./../nav-string"/>
<!-- catalog megoldás -->
<xs:import namespace="http://schemas.nav.gov.hu/NTCA/2.0/common/string"/> + catalog file

Mintaként szolgálhat a dto/dto-jakarta/src/main/resources/catalog/catalog.cat + dto/dto-jakarta/src/main/resources/catalog/all-in-one.xsd fájlok, majd ennek a dto/dto-jakarta/pom.xml felhasználása generálásnál. A generálás a https://github.com/highsource/jaxb-tools maven plugin használatával történik.

Projekt struktúra

Common
├── core
│   └── core-jakarta # Jakarta EE specifikus általános objektumok
├── dto
│   └── dto-jakarta  # Jakarta EE generált DTO objektumok a schemas XSD alapján
└── schemas          # XSD fájlok

2) Használat

A projekt Maven alapú, így a használatához szükséges a Maven környezet.

XSD sémák importálása

<dependency>
    <groupId>hu.gov.nav.schemas.common2</groupId>
    <artifactId>schemas</artifactId>
    <version>VERSION</version>
</dependency>

Jakarta EE ségédosztályok

<dependency>
    <groupId>hu.gov.nav.schemas.common2</groupId>
    <artifactId>core-jakarta</artifactId>
    <version>VERSION</version>
</dependency>

XSD sémák + generált DTO objektumok

<dependency>
    <groupId>hu.gov.nav.schemas.common2</groupId>
    <artifactId>dto-jakarta</artifactId>
    <version>VERSION</version>
</dependency>

2.1) Verziókezelés

A projekt jellege miatt fontos, hogy a különböző projektek kompatibilisek maradjanak egymással. Ezért megeshet hogy egy importált séma egy adott projekten korábbi verzióját használja, míg egy másik séma újabbat. Ütközést elkerülése érdekében a projekt groupId-ja tartalmazza a fő verziószámot, így a verziók elkülöníthetőek maradnak.

Több verzió párhuzamos használata

<!-- korábbi verzió használata -->
<dependency>
    <groupId>hu.gov.nav.schemas.common</groupId>
    <artifactId>schemas</artifactId>
    <version>1.0.0</version>
</dependency>
<!-- újabb verzió használata -->
<dependency>
    <groupId>hu.gov.nav.schemas.common2</groupId>
    <artifactId>schemas</artifactId>
    <version>2.0.0</version>
</dependency>