Vytvoření nového rozšíření

Následující dokument popisuje, jak vytvořit vlastní rozšíření.

Vytvoření nového rozšířeníZkopírovat odkaz na sekci

Nové rozšíření musí implementovat rozhraní com.fg.cps.eshop.feature.ModuleFeature. Význam jednotlivých metod je popsán v samotném rozhraní. Pro zjednodušení implementace je připraven abstraktní předek com.fg.cps.eshop.feature.AbstractBaseEdeeShopFeature, ze kterého lze vyjít a případně přetížit potřebné metody.

Rozšíření lze dále definovat pomocí anotací (viz Anotace pro rozšíření).

Nakonec je potřeba provést registraci rozšíření (viz Registrace rozšíření).

Registrace rozšířeníZkopírovat odkaz na sekci

Registrace rozšíření probíhá pomocí souboru /META-INF/edeeModuleFeature.init, ve kterém je uvedena plně kvalifikovaná třída rozšíření na samostatném řádku. Nové rozšíření musí tedy obsahovat tento soubor v rámci svého JAR balíčku.

Příklad:

1com.fg.cps.eshop.order.OrderFeature2com.fg.cps.eshop.product.ProductFeature

Anotace pro rozšířeníZkopírovat odkaz na sekci

Rozšíření dále specifikují anotace z následujících balíčků:

• com.fg.cps.eshop.feature.annotation
• com.fg.cps.eshop.registration.model.annotation

Níže je přehled všech klíčových anotací, jejich význam, hlavní parametry a ukázky použití.

@FeatureSpringConfigZkopírovat odkaz na sekci

• Popis: Registrace Java Spring konfigurací v rámci rozšíření; podporuje podmíněnou aktivaci podle zapnutých rozšíření a/nebo SpEL podmínky.
• Parametry:
  • javaConfigs: povinné, seznam konfiguračních tříd (označených @Configuration).
  • featureEnabled: seznam tříd rozšíření, které musí být aktivní.
  • condition: SpEL výraz vyhodnocovaný nad instancí rozšíření (root-context).
• Příklad:

1@FeatureSpringConfig(2    javaConfigs = {ProductFeatureContextConfiguration.class},3    featureEnabled = RestApiFeature.class,4    condition = RestApiFeatureConfiguration.BACKEND_API_ENABLED5)

@FeatureSpringConfigsZkopírovat odkaz na sekci

• Popis: Kontejner pro více konfigurací.
• Příklad:

1@FeatureSpringConfigs({2    @FeatureSpringConfig(javaConfigs = {ProductFeatureContextConfiguration.class}),3    @FeatureSpringConfig(4        featureEnabled = RestApiFeature.class,5        javaConfigs = {ProductApiConfig.class},6        condition = RestApiFeatureConfiguration.BACKEND_API_ENABLED7    )8})

@MessageSourceZkopírovat odkaz na sekci

• Popis: Registrace zdrojů zpráv (i18n) pro danou feature.
• Parametry: value – seznam classpath umístění se soubory lokalizací.
• Příklad:

1@MessageSource({"classpath:/META-INF/lib_eshop_edee/product/i18n/messagesAdmin"})

@MailZkopírovat odkaz na sekci

• Popis: Registrace e-mailových šablon a listenerů pomocí konfiguračních XML na classpath; lze podmínit SpEL výrazem.
• Parametry:
  • value – seznam umístění;
  • condition – SpEL podmínka.
• Příklad:

1@Mail("classpath:/META-INF/lib_eshop_order/mail/module-mail-listeners-order.xml")

@DataModelZkopírovat odkaz na sekci

• Popis: Rozšíření datového a ADaM modelu (XML konfigurace).
• Parametry:
  • modelConfiguration: Resource cesta na ADaM model (XML).
  • modelVersion: @ModelVersion s údaji pro verzování DB (name, version, scriptDir).
  • featureEnabled: další rozšíření, která musí být aktivní.
  • priority: priorita zpracování.
  • condition: SpEL podmínka.
• Příklad:

1@DataModel(2    modelConfiguration = "classpath:/META-INF/lib_eshop_edee/product/model/productModel.xml",3    modelVersion = @ModelVersion(4        name = "lib_eshop_product",5        version = "2025.09.15.13.30",6        scriptDir = "classpath:/META-INF/lib_eshop_edee/product/sql/"7    )8)

@DataModelsZkopírovat odkaz na sekci

• Popis: Umožňuje definovat více položek (@DataModel) s možností podmínění.
• Příklad:

1@DataModels(models = {2    @DataModel(modelConfiguration = "classpath:/path/to/modelA.xml"),3    @DataModel(modelConfiguration = "classpath:/path/to/modelB.xml", priority = "10")4})

@ModelVersionZkopírovat odkaz na sekci

• Popis: Popis verzování datového modelu pro SQL autoupdate.
• Parametry: name (unikátní jméno modelu), version (verze), scriptDir (Resource cesta ke skriptům).
• Příklad:

1@ModelVersion(name = "lib_eshop_product", version = "2025.09.15.13.30", scriptDir = "classpath:/META-INF/lib_eshop_edee/product/sql/")

@FeatureTreeNodeConfigZkopírovat odkaz na sekci

• Popis: Registrace uzlů do navigačního stromu admin UI (obal pro více @TreeNode).
• Příklad:

1@FeatureTreeNodeConfig({2    @TreeNode(3        localizedIdentifierId = "edeeShopCatalog",4        localizedIdentifierCode = "edeeShop.edeeShopCatalog.title",5        localizedIdentifierDefault = "Produkty",6        onClickPageRelativeId = "productListingPage",7        securityIdentifierId = "product",8        securityIdentifierName = "product",9        edeeShopRootTreeNode = true,10        icon = "icon-edee-product icon-blue",11        priority = "500"12    ),13    @TreeNode(14        localizedIdentifierId = "edeeShopObsoleteProducts",15        localizedIdentifierCode = "edeeShop.edeeShopObsoleteProducts.title",16        localizedIdentifierDefault = "Ukončené produkty",17        onClickPageRelativeId = "obsoleteProductListingPage",18        securityIdentifierId = "product",19        securityIdentifierName = "product",20        edeeShopParentTreeNodeId = "edeeShopCatalog",21        icon = "icon-edee-product-obsolete icon-blue",22        priority = "1000"23    )24})

@TreeNodeZkopírovat odkaz na sekci

• Popis: Registrace jednoho uzlu do navigačního stromu admin UI.
• Parametry (výběr):
  • localizedIdentifierId - identifikátor uzlu (unikátní v rámci stromu).
  • localizedIdentifierCode - kód pro i18n (messages.properties).
  • localizedIdentifierDefault - výchozí text (pokud chybí překlad).
  • onClickPageRelativeId nebo onClickPageUrl - cílová stránka (relativní ID v rámci modulu nebo absolutní URL).
  • securityIdentifierId / securityIdentifierName - zabezpečení uzlu.
  • edeeShopParentTreeNodeId, edeeShopRootTreeNode: umístění ve stromu.
  • icon, priority: vzhled a pořadí.
  • stateCompact / stateSelectable / stateHidden, skipContextMenu: stav uzlu.
  • featureEnabled, condition: podmínky vytvoření uzlu.
• Příklad:

1@TreeNode(2    localizedIdentifierId = "eshopOrder/orderList",3    localizedIdentifierCode = "eshopOrderModule.orderListingPage.title",4    localizedIdentifierDefault = "Objednávky",5    onClickPageRelativeId = "orderListingPage",6    securityIdentifierId = "order",7    securityIdentifierName = "order",8    edeeShopRootTreeNode = true,9    icon = "icon-edee-orders icon-blue",10    priority = "1000"11)

@RefreshEventUiZkopírovat odkaz na sekci

• Popis: Uvede entity (entityView), pro které se má do UI vypalovat refreshEvent pro aktualizace AR widgetů.
• Parametry: value – seznam názvů entit.
• Příklad:

1@RefreshEventUi({Order.ENTITY_NAME, OrderDispatch.ENTITY_NAME, OrderForPickUp.ENTITY_NAME})

@CacheConfigZkopírovat odkaz na sekci

• Popis: Definice cache pro feature; registruje GenericCacheConfiguration.
• Parametry (výběr): name, scope, copyOnRead/copyOnWrite, diskPersistent, statistics, maxElementsInMemory/OnDisk, memoryStoreEvictionPolicy, TTL/TTI, catalogSpecific, featureEnabled, condition.
• Příklad:

1@CacheConfig(2    name = "orderRounding",3    maxElementsInMemory = 304)

@CacheConfigsZkopírovat odkaz na sekci

• Popis: Kontejner pro více @CacheConfig.
• Příklad:

1@CacheConfigs(cacheConfigs = {2    @CacheConfig(name = SHOPPING_CART_CACHE, maxElementsInMemory = 500, timeToLiveSeconds = 3600, scope = CacheScope.DISTRIBUTED),3    @CacheConfig(name = CACHE_BILLING_COUNTRIES, maxElementsInMemory = 15),4    @CacheConfig(name = CACHE_DELIVERY_COUNTRIES, maxElementsInMemory = 15)5})

@FeatureSpringBeanZkopírovat odkaz na sekci

• Popis: Označí pole v rozšíření jako Spring bean, který má být k dispozici v kontextu pod daným názvem.
• Parametry: value – název beanu.
• Příklad:

1public class OrderFeature extends AbstractBaseEdeeShopFeature<EdeeShopModuleConfig> {2    @FeatureSpringBean("orderModelDescriptor")3    private OrderModelDescriptor orderModelDescriptor = new OrderModelDescriptor();4}

@FulltextResourceZkopírovat odkaz na sekci

• Popis: Umožňuje definovat novou fulltextovou sekci, která bude využita v rámci publikovaných dat pro koncové uživatele. Pokud je anotace přítomna, systém se pokusí pro každý katalog (případně i region) vytvořit a zaregistrovat fulltextovou sekci (FulltextSection). Pokud již stejné sekce existují (např. byly registrovány fulltext modulem nebo konfigurací implementující FulltextConfig), nedojde k duplicitní registraci.
• Parametry:
  • value – název/fragment sekce; musí být unikátní. Používá se jako část identifikátoru sekce (viz SectionConfig#getName(), FulltextSection.Key#fragment()).
  • withoutCatalog – pokud true, vytvoří se jediná sekce bez vazby na katalog (default false = sekce po katalozích).
• Příklad:

1@FulltextResource(OrderFeature.FULLTEXT_SECTION_FRAGMENT)

• Anotace MessageSource, Documentation, RefreshEventUi a další výše zmíněné jsou zpracovány v předkovi AbstractBaseEdeeShopFeature – viz zdrojový kód pro detaily načítání a aplikace.

@SecurityZkopírovat odkaz na sekci

• Popis: Agreguje veškeré bezpečnostní nastavení rozšíření – přidaná práva a definice chráněných zdrojů.
• Parametry:
  • rights – pole @Right pro definici nadstandardních práv, která nejsou definována v RegistrationIntegrationFeature. Obvykle není potřeba.
  • resources – pole @SecuredResource s definicemi chráněných zdrojů a jejich práv; pokud rozšíření poskytuje chráněné zdroje, je nutné je zde uvést.
• Příklad:

1@Security(2    rights = {3        @Right(value = 'R', name = "Čtení", description = "Čtení objednávek"),4        @Right(value = 'W', name = "Zápis", description = "Upravit objednávky")5    },6    resources = {7        @SecuredResource(8            name = "order",9            description = "Objednávky",10            rights = {11                @SecuredResourceRightDescription(right = 'R', description = "Čtení objednávky"),12                @SecuredResourceRightDescription(right = 'W', description = "Upravit objednávku")13            },14            defaultResourceRightAssignments = {15                @DefaultResourceRightAssignment(role = ROLE_ALL_USERS, rights = {'R'}),16                @DefaultResourceRightAssignment(role = ROLE_LOGGED_IN_USER, rights = {'R','W'})17            }18        )19    }20)

@RightZkopírovat odkaz na sekci

• Popis: Definuje nové oprávnění (právo). Každé právo je v systému unikátní (jednoznakový kód).
• Parametry: value (char kód, např. R/W/D), name (název), description (popis).
• Příklad:

1@Right(value = 'D', name = "Mazání", description = "Smazat objednávky")

@SecuredResourceZkopírovat odkaz na sekci

• Popis: Definuje chráněný zdroj v systému (unikátní název), ke kterému se vážou práva.
• Parametry: name (unikátní identifikátor zdroje), description (popis), featureEnabled (podmíněné povolení), rights (pole @SecuredResourceRightDescription), defaultResourceRightAssignments (výchozí přiřazení práv rolím při absenci předdefinovaných rolí).
• Příklad:

1@SecuredResource(name = "order", description = "Objednávky")

@SecuredResourceRightDescriptionZkopírovat odkaz na sekci

• Popis: Popis konkrétního práva vztahujícího se k danému zdroji.
• Parametry: right (char), description (popis).
• Příklad:

1@SecuredResourceRightDescription(right = 'R', description = "Číst zdroj")

@DefaultResourceRightAssignmentZkopírovat odkaz na sekci

• Popis: Výchozí přiřazení práv ke zdroji pro danou roli.
• Parametry: role (kód role), rights (pole char s právy).
• Příklad:

1@DefaultResourceRightAssignment(role = ROLE_ALL_USERS, rights = {'R'})

Rozšiřování datového modelu a registrace konvertorů (ADaM / MetadataManager)Zkopírovat odkaz na sekci

V rámci rozšíření je často potřeba:

• doplnit/rozšířit datový model (proxy rozhraní, "traits" pro entity a sub‑entity),
• zaregistrovat konvertory do ADaMu (MetadataConversionService),
• registrovat nebo konfigurovat ADaM interceptory (query, SQL query, before-persistence),

Toto se obvykle provádí v lifecycle metodách rozšíření:

• beforeSpringInitialization() – přidání traitů na modelové deskriptory,
• afterSpringInitialization(ctx) – práce s MetadataManagerem a registrace konvertorů/interceptorů,
• prepareStart(ctx) – finální promítnutí modelových deskriptorů do ADaM Pojo kontraktů.

Důležité: EdeeShopModule má pouze JEDEN MetadataManager. K instanci se vždy přistupuje jako ke Spring beanu pod konstantním jménem COMMON_EDEE_SHOP_METADATA_MANAGER (viz com.fg.cps.eshop.feature.config.spring.SharedBeanNames). Vždy jej proto získávejte přes modulový Spring kontext.

Ukázka (zjednodušeně inspirováno com.fg.cps.eshop.order.OrderFeature#afterSpringInitialization):

1import com.fg.metadata.business.MetadataManager;2import com.fg.metadata.business.conversionService.MetadataConversionService;3import static com.fg.cps.eshop.feature.config.spring.SharedBeanNames.COMMON_EDEE_SHOP_METADATA_MANAGER;4
5@Override6public void beforeSpringInitialization() {7    super.beforeSpringInitialization();8    if (!isFeatureEnabled()) return;9
10    // 1) Rozšíření modelu pomocí traitů (příklad)11    myEntityModelDescriptor.addTrait(MyEntityWithSomething.class);12    myEntityModelDescriptor.addTraitForSubModel(MySubEntity.class, MySubEntityExtraTrait.class);13}14
15@Override16public void afterSpringInitialization(AbstractRefreshableApplicationContext moduleContext) {17    super.afterSpringInitialization(moduleContext);18
19    // 2) Přístup k jedinému MetadataManageru a registrace konvertorů20    MetadataManager metadataManager = moduleContext.getBean(21        COMMON_EDEE_SHOP_METADATA_MANAGER, MetadataManager.class22    );23
24    MetadataConversionService conversionService = metadataManager25        .getMetadataConfiguration()26        .getConversionService();27
28    conversionService.addConverter(new MyDomainToStringConverter());29    conversionService.addConverter(new StringToMyDomainConverter());30
31    final MetadataConfiguration metadataConfiguration = metadataManager.getMetadataConfiguration();32    QueryInterceptor interceptor = new MyQueryInterceptor(...);33    metadataConfiguration.addQueryInterceptor(interceptor);34    // a další addSqlQueryInterceptor, addEntityBeforePersistenceInterceptor...35}36
37@Override38public void prepareStart(AbstractRefreshableApplicationContext moduleContext) {39    super.prepareStart(moduleContext);40
41    // 3) Promítnutí deskriptorů do ADaM Pojo kontraktů42    MetadataConfiguration cfg = moduleContext43        .getBean(COMMON_EDEE_SHOP_METADATA_MANAGER, MetadataManager.class)44        .getMetadataConfiguration();45
46    cfg.addOrUpdatePojoContract(47        myEntityModelDescriptor.getEntityName(),48        myEntityModelDescriptor.toProxyInterfaceDescriptor()49    );50}

Poznámky a doporučení:

• MetadataManager nikdy neinicializujte vlastní instancí – vždy používejte bean COMMON_EDEE_SHOP_METADATA_MANAGER.
• Konvertory registrujte v afterSpringInitialization, kdy je již k dispozici plně sestavený MetadataManager a jeho ConversionService.
• Traity přidávejte v beforeSpringInitialization, aby byly modelové deskriptory kompletní ještě před přípravou startu.
• V prepareStart nezapomeňte zavolat addOrUpdatePojoContract pro každý modelový deskriptor, který vaše rozšíření modifikuje (entity i sub‑entity).
• Interceptory v ADaMu lze rovněž registrovat i konfigurovat:
  • registrace nového interceptoru: metadataManager.getMetadataConfiguration().addQueryInterceptor(new MyQueryInterceptor(...));
  • registrace SQL query interceptoru: metadataManager.getMetadataConfiguration().addSqlQueryInterceptor(new MySqlQueryInterceptor(...));
  • registrace persistence interceptoru: metadataManager.getMetadataConfiguration().addEntityBeforePersistenceInterceptor(new MyBeforePersistenceInterceptor(...));
  • úprava již existujícího interceptoru: použijte AdamUtils.findQueryInterceptorByType(metadataManager, SomeInterceptor.class) a poté jej nakonfigurujte.
• Reálné příklady:
  • com.fg.cps.eshop.productAlias.ProductAliasFeature#afterSpringInitialization – registrace query, SQL query i persistence interceptorů a úprava LocalizedNameQueryInterceptor.
  • com.fg.eshop.rest.RestApiFeature#afterSpringInitialization – registrace CatalogEntityIdTranslateInterceptor přes addQueryInterceptor.
  • com.fg.cps.eshop.order.OrderFeature – ukázka práce s query interceptorem přes AdamUtils a registrace konvertorů.

Definice GUIZkopírovat odkaz na sekci

Každé rozšíření umožňuje definovat vlastní GUI. Stačí implementovat rozhraní com.fg.cps.eshop.feature.type.EdeeModuleFeatureWithGui. Více zde.

Konfigurace rozšířeníZkopírovat odkaz na sekci

Každé rozšíření může být aktivováno vždy nebo aktivace může být podmíněna například konfigurací.

V případě, že má být rozšíření zapnuté vždy, stačí implementovat metodu isFeatureEnabled() a vrátit true.

V ostatních případech musí tato metoda implementovat vlastní logiku, která rozhodne, zda je rozšíření aktivní či nikoliv. Např. pokud bude rozšíření závislé na nějaké konfiguraci, bude implementace vypadat nějak takto:

1@Override2public boolean isFeatureEnabled() {3    return someConfigElement != null;4}

Kde someConfigElement představuje konkrétní konfiguraci a může se jednat např. o pole, které je označeno anotací com.fg.config.annotation.ConfigElement.

1@ConfigElement(path = "someConfigElement")2private SomeConfigElement someConfigElement;

Tato anotace zajistí, že pokud je konfigurace dostupná (existuje v konfiguraci EdeeShopModulu), bude do pole someConfigElement inicializována instance SomeConfigElement. Pokud konfigurace neexistuje, zůstane pole null.

V tomto případě bude konfigurace modulu vypadat nějak takto:

1<module customName="edeeShop" classname="com.fg.cps.eshop.cps.EdeeShopModule">2    ...3    <config>4        <someConfigElement>5            <!-- konfigurace pro SomeConfigElement -->6        </someConfigElement>7    </config>8    ...9</module>

Publikace dat do evitaDBZkopírovat odkaz na sekci

Detailní popis publikace dat do evitaDB, včetně anotací schématu, vytváření nových publikovaných entit a projektového rozšiřování existujících entit, najdete v samostatné kapitole Publikace dat do evitaDB.