feat: handle item ordering.

kovaren · kovaren · commit 1776e3f6d26c · 2025-11-13T17:16:36.000+01:00
https://gravitee.atlassian.net/browse/APIM-11696
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-management-v2/gravitee-apim-rest-api-management-v2-rest/src/main/java/io/gravitee/rest/api/management/v2/rest/mapper/PortalNavigationItemsMapper.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-management-v2/gravitee-apim-rest-api-management-v2-rest/src/main/java/io/gravitee/rest/api/management/v2/rest/mapper/PortalNavigationItemsMapper.java
@@ -38,25 +38,29 @@ default BasePortalNavigationItem map(io.gravitee.apim.core.portal_page.model.Por
         final var id = portalNavigationItem.getId().toString();
         final var title = portalNavigationItem.getTitle();
         final var area = BasePortalNavigationItem.AreaEnum.fromValue(portalNavigationItem.getArea().name());
+        final var order = portalNavigationItem.getOrder();
         final var parentId = mapParentId(portalNavigationItem.getParentId());
 
         return switch (portalNavigationItem) {
             case io.gravitee.apim.core.portal_page.model.PortalNavigationFolder ignored -> new PortalNavigationFolder()
                 .id(id)
                 .title(title)
                 .area(area)
+                .order(order)
                 .parentId(parentId);
             case io.gravitee.apim.core.portal_page.model.PortalNavigationPage page -> new PortalNavigationPage()
-                .contentId(page.getContentId().toString())
+                .contentId(page.getPortalPageContentId().toString())
                 .id(id)
                 .title(title)
                 .area(area)
+                .order(order)
                 .parentId(parentId);
             case io.gravitee.apim.core.portal_page.model.PortalNavigationLink link -> new PortalNavigationLink()
                 .url(link.getHref())
                 .id(id)
                 .title(title)
                 .area(area)
+                .order(order)
                 .parentId(parentId);
         };
     }
@@ -69,24 +73,24 @@ default io.gravitee.apim.core.portal_page.model.PortalNavigationItem map(
         final var id = PortalNavigationItemId.random();
         final var title = createPortalNavigationItem.getTitle();
         final var area = PortalArea.valueOf(createPortalNavigationItem.getArea().getValue());
-        final var parentId = mapParentId(createPortalNavigationItem.getParentId());
+        final var order = createPortalNavigationItem.getOrder() == null ? Integer.MAX_VALUE : createPortalNavigationItem.getOrder();
 
-        return switch (createPortalNavigationItem) {
+        final var item = switch (createPortalNavigationItem) {
             case CreatePortalNavigationFolder ignored -> new io.gravitee.apim.core.portal_page.model.PortalNavigationFolder(
                 id,
                 organizationId,
                 environmentId,
                 title,
                 area,
-                parentId
+                order
             );
             case CreatePortalNavigationPage page -> new io.gravitee.apim.core.portal_page.model.PortalNavigationPage(
                 id,
                 organizationId,
                 environmentId,
                 title,
                 area,
-                parentId,
+                order,
                 PortalPageContentId.of(page.getContentId())
             );
             case CreatePortalNavigationLink link -> new io.gravitee.apim.core.portal_page.model.PortalNavigationLink(
@@ -95,13 +99,16 @@ default io.gravitee.apim.core.portal_page.model.PortalNavigationItem map(
                 environmentId,
                 title,
                 area,
-                parentId,
+                order,
                 link.getUrl()
             );
             default -> throw new TechnicalDomainException(
                 String.format("Unknown PortalNavigationItem class %s", createPortalNavigationItem.getClass().getSimpleName())
             );
         };
+        item.setParentId(mapParentId(createPortalNavigationItem.getParentId()));
+
+        return item;
     }
 
     private PortalNavigationItemId mapParentId(String parentId) {
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-management-v2/gravitee-apim-rest-api-management-v2-rest/src/main/java/io/gravitee/rest/api/management/v2/rest/resource/environment/PortalNavigationItemsResource.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-management-v2/gravitee-apim-rest-api-management-v2-rest/src/main/java/io/gravitee/rest/api/management/v2/rest/resource/environment/PortalNavigationItemsResource.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.gravitee.rest.api.management.v2.rest.resource.ui;
+package io.gravitee.rest.api.management.v2.rest.resource.environment;
 
 import io.gravitee.apim.core.portal_page.use_case.CreatePortalNavigationItemUseCase;
 import io.gravitee.common.http.MediaType;
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-management-v2/gravitee-apim-rest-api-management-v2-rest/src/main/java/io/gravitee/rest/api/management/v2/rest/resource/installation/EnvironmentResource.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-management-v2/gravitee-apim-rest-api-management-v2-rest/src/main/java/io/gravitee/rest/api/management/v2/rest/resource/installation/EnvironmentResource.java
@@ -26,11 +26,11 @@
 import io.gravitee.rest.api.management.v2.rest.resource.environment.EnvironmentAnalyticsResource;
 import io.gravitee.rest.api.management.v2.rest.resource.environment.EnvironmentNewtAIResource;
 import io.gravitee.rest.api.management.v2.rest.resource.environment.EnvironmentScoringResource;
+import io.gravitee.rest.api.management.v2.rest.resource.environment.PortalNavigationItemsResource;
 import io.gravitee.rest.api.management.v2.rest.resource.environment.SharedPolicyGroupsResource;
 import io.gravitee.rest.api.management.v2.rest.resource.group.GroupsResource;
 import io.gravitee.rest.api.management.v2.rest.resource.kafka_console.ProxyKafkaConsoleResource;
 import io.gravitee.rest.api.management.v2.rest.resource.ui.PortalMenuLinksResource;
-import io.gravitee.rest.api.management.v2.rest.resource.ui.PortalNavigationItemsResource;
 import io.gravitee.rest.api.management.v2.rest.resource.ui.ThemesResource;
 import io.gravitee.rest.api.service.EnvironmentService;
 import io.gravitee.rest.api.service.common.GraviteeContext;
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-management-v2/gravitee-apim-rest-api-management-v2-rest/src/main/resources/openapi/openapi-environments.yaml b/gravitee-apim-rest-api/gravitee-apim-rest-api-management-v2/gravitee-apim-rest-api-management-v2-rest/src/main/resources/openapi/openapi-environments.yaml
@@ -1670,31 +1670,32 @@ components:
             published:
               type: boolean
               description: Whether the page is published or not
+        PortalArea:
+          type: string
+          description: The portal area (used by portal navigation items)
+          enum: [HOMEPAGE, TOP_NAVBAR]
+          example: TOP_NAVBAR
         BaseCreatePortalNavigationItem:
           type: object
           properties:
             title:
               type: string
-              description: Navigation item title
+              description: Portal navigation item title
               example: APIs, Guides
             type:
               type: string
-              description: Navigation item type
+              description: Portal navigation item type
               example: FOLDER
               enum:
                 - FOLDER
                 - PAGE
                 - LINK
             area:
-              type: string
-              description: Portal area to create navigation item in
-              enum:
-                - HOMEPAGE
-                - TOP_NAVBAR
-              example: TOP_NAVBAR
+              $ref: "#/components/schemas/PortalArea"
             order:
               type: integer
-              description: Order of navigation item (zero based)
+              minimum: 0
+              description: Portal navigation item order (zero-based)
               example: 2
             parentId:
               type: string
@@ -1710,7 +1711,6 @@ components:
             - title
             - type
             - area
-            - order
         CreatePortalNavigationFolder:
           type: object
           title: "CreatePortalNavigationFolder"
@@ -1772,7 +1772,7 @@ components:
               example: TOP_NAVBAR
             order:
               type: integer
-              description: Portal navigation item order (zero based)
+              description: Portal navigation item order (zero-based)
               example: 2
             parentId:
               type: string
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/exception/HomepageAlreadyExistsException.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/exception/HomepageAlreadyExistsException.java
@@ -0,0 +1,25 @@
+/*
+ * Copyright © 2015 The Gravitee team (http://gravitee.io)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.gravitee.apim.core.portal_page.exception;
+
+import io.gravitee.apim.core.exception.ValidationDomainException;
+
+public class HomepageAlreadyExistsException extends ValidationDomainException {
+
+    public HomepageAlreadyExistsException(String message) {
+        super(message);
+    }
+}
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/model/PortalNavigationFolder.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/model/PortalNavigationFolder.java
@@ -16,7 +16,6 @@
 package io.gravitee.apim.core.portal_page.model;
 
 import jakarta.annotation.Nonnull;
-import jakarta.annotation.Nullable;
 
 public final class PortalNavigationFolder extends PortalNavigationItem {
 
@@ -26,8 +25,8 @@ public PortalNavigationFolder(
         @Nonnull String environmentId,
         @Nonnull String title,
         @Nonnull PortalArea area,
-        @Nullable PortalNavigationItemId parentId
+        @Nonnull Integer order
     ) {
-        super(id, organizationId, environmentId, title, area, parentId);
+        super(id, organizationId, environmentId, title, area, order);
     }
 }
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/model/PortalNavigationItem.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/model/PortalNavigationItem.java
@@ -43,7 +43,7 @@ public abstract sealed class PortalNavigationItem permits PortalNavigationPage,
     private PortalArea area;
 
     @Setter
-    @Nullable
+    @Nonnull
     private Integer order;
 
     @Setter
@@ -56,14 +56,14 @@ protected PortalNavigationItem(
         @Nonnull String environmentId,
         @Nonnull String title,
         @Nonnull PortalArea area,
-        @Nullable PortalNavigationItemId parentId
+        @Nonnull Integer order
     ) {
         this.id = id;
         this.organizationId = organizationId;
         this.environmentId = environmentId;
         this.title = title;
         this.area = area;
-        this.parentId = parentId;
+        this.order = order;
     }
 
     @Override
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/model/PortalNavigationLink.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/model/PortalNavigationLink.java
@@ -33,10 +33,10 @@ public PortalNavigationLink(
         @Nonnull String environmentId,
         @Nonnull String title,
         @Nonnull PortalArea area,
-        @Nullable PortalNavigationItemId parentId,
+        @Nonnull Integer order,
         @Nonnull String href
     ) {
-        super(id, organizationId, environmentId, title, area, parentId);
+        super(id, organizationId, environmentId, title, area, order);
         this.href = href;
     }
 }
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/model/PortalNavigationPage.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/model/PortalNavigationPage.java
@@ -33,10 +33,10 @@ public PortalNavigationPage(
         @Nonnull String environmentId,
         @Nonnull String title,
         @Nonnull PortalArea area,
-        @Nullable PortalNavigationItemId parentId,
+        @Nonnull Integer order,
         @Nonnull PortalPageContentId portalPageContentId
     ) {
-        super(id, organizationId, environmentId, title, area, parentId);
+        super(id, organizationId, environmentId, title, area, order);
         this.portalPageContentId = portalPageContentId;
     }
 }
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/query_service/PortalNavigationItemsQueryService.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/query_service/PortalNavigationItemsQueryService.java
@@ -21,6 +21,8 @@
 import java.util.List;
 
 public interface PortalNavigationItemsQueryService {
+    PortalNavigationItem findByIdAndEnvironmentId(String environmentId, PortalNavigationItemId id);
+
     List<PortalNavigationItem> findByParentIdAndEnvironmentId(String environmentId, PortalNavigationItemId id);
 
     List<PortalNavigationItem> findTopLevelItemsByEnvironmentIdAndPortalArea(String environmentId, PortalArea portalArea);
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/use_case/CreatePortalNavigationItemUseCase.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/core/portal_page/use_case/CreatePortalNavigationItemUseCase.java
@@ -17,13 +17,17 @@
 
 import io.gravitee.apim.core.UseCase;
 import io.gravitee.apim.core.portal_page.crud_service.PortalNavigationItemCrudService;
+import io.gravitee.apim.core.portal_page.exception.HomepageAlreadyExistsException;
 import io.gravitee.apim.core.portal_page.exception.ParentAreaMismatchException;
 import io.gravitee.apim.core.portal_page.exception.ParentNotFoundException;
 import io.gravitee.apim.core.portal_page.exception.ParentTypeMismatchException;
+import io.gravitee.apim.core.portal_page.model.PortalArea;
 import io.gravitee.apim.core.portal_page.model.PortalNavigationFolder;
 import io.gravitee.apim.core.portal_page.model.PortalNavigationItem;
 import io.gravitee.apim.core.portal_page.model.PortalNavigationPage;
 import io.gravitee.apim.core.portal_page.query_service.PortalNavigationItemsQueryService;
+import java.util.List;
+import java.util.Objects;
 import lombok.Builder;
 import lombok.RequiredArgsConstructor;
 
@@ -35,11 +39,27 @@ public class CreatePortalNavigationItemUseCase {
     private final PortalNavigationItemsQueryService portalNavigationItemsQueryService;
 
     public Output execute(Input input) {
-        final PortalNavigationItem item = input.item();
+        final PortalNavigationItem itemToCreate = input.item();
 
-        validate(item);
+        validate(itemToCreate);
 
-        return new Output(this.portalNavigationItemCrudService.create(item));
+        final var maxOrder = this.retrieveSiblingItems(itemToCreate).stream().mapToInt(PortalNavigationItem::getOrder).max().orElse(-1);
+        // Limit the new item's order to at most one position after the current maximum
+        itemToCreate.setOrder(Math.min(itemToCreate.getOrder(), maxOrder + 1));
+
+        final var output = new Output(this.portalNavigationItemCrudService.create(itemToCreate));
+
+        // Update orders of all following items
+        this.retrieveSiblingItems(itemToCreate)
+            .stream()
+            .filter(item -> !Objects.equals(item.getId(), itemToCreate.getId()))
+            .filter(item -> item.getOrder() >= itemToCreate.getOrder())
+            .forEach(item -> {
+                item.setOrder(item.getOrder() + 1);
+                this.portalNavigationItemCrudService.update(item);
+            });
+
+        return output;
     }
 
     @Builder
@@ -64,9 +84,25 @@ private void validate(PortalNavigationItem item) {
             }
         }
 
+        if (item.getArea().equals(PortalArea.HOMEPAGE)) {
+            final var existingHomepage = portalNavigationItemsQueryService.findTopLevelItemsByEnvironmentIdAndPortalArea(
+                item.getEnvironmentId(),
+                item.getArea()
+            );
+            if (!existingHomepage.isEmpty()) {
+                throw new HomepageAlreadyExistsException("Homepage already exists");
+            }
+        }
+
         if (item instanceof PortalNavigationPage page) {
-            final var contentId = page.getContentId();
+            final var contentId = page.getPortalPageContentId();
             // TODO check that content with provided id exists, when portal page content dev is ready
         }
     }
+
+    private List<PortalNavigationItem> retrieveSiblingItems(PortalNavigationItem item) {
+        return item.getParentId() != null
+            ? portalNavigationItemsQueryService.findByParentIdAndEnvironmentId(item.getEnvironmentId(), item.getParentId())
+            : portalNavigationItemsQueryService.findTopLevelItemsByEnvironmentIdAndPortalArea(item.getEnvironmentId(), item.getArea());
+    }
 }
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/infra/query_service/portal_page/PortalNavigationItemsQueryServiceImpl.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/main/java/io/gravitee/apim/infra/query_service/portal_page/PortalNavigationItemsQueryServiceImpl.java
@@ -38,6 +38,24 @@ public PortalNavigationItemsQueryServiceImpl(@Lazy final PortalNavigationItemRep
         this.portalNavigationItemRepository = portalNavigationItemRepository;
     }
 
+    @Override
+    public PortalNavigationItem findByIdAndEnvironmentId(String environmentId, PortalNavigationItemId id) {
+        try {
+            var result = portalNavigationItemRepository.findById(id.json());
+            if (result.isPresent() && result.get().getEnvironmentId().equals(environmentId)) {
+                return portalNavigationItemAdapter.toEntity(result.get());
+            }
+            return null;
+        } catch (TechnicalException e) {
+            String errorMessage = String.format(
+                "An error occurred while finding portal navigation item by id %s and environmentId %s",
+                id,
+                environmentId
+            );
+            throw new TechnicalDomainException(errorMessage, e);
+        }
+    }
+
     @Override
     public List<PortalNavigationItem> findByParentIdAndEnvironmentId(String environmentId, PortalNavigationItemId parentId) {
         try {
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/fixtures/core/model/PortalNavigationItemFixtures.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/fixtures/core/model/PortalNavigationItemFixtures.java
@@ -42,7 +42,8 @@ public static PortalNavigationFolder aFolder(String id, String title) {
     }
 
     public static PortalNavigationFolder aFolder(String id, String title, PortalNavigationItemId parentId) {
-        var folder = new PortalNavigationFolder(PortalNavigationItemId.of(id), ORG_ID, ENV_ID, title, PortalArea.TOP_NAVBAR, parentId);
+        var folder = new PortalNavigationFolder(PortalNavigationItemId.of(id), ORG_ID, ENV_ID, title, PortalArea.TOP_NAVBAR, 0);
+        folder.setParentId(parentId);
         return folder;
     }
 
@@ -53,9 +54,10 @@ public static PortalNavigationPage aPage(String id, String title, PortalNavigati
             ENV_ID,
             title,
             PortalArea.TOP_NAVBAR,
-            parentId,
+            0,
             PortalPageContentId.random()
         );
+        page.setParentId(parentId);
         return page;
     }
 
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/inmemory/PortalNavigationItemsQueryServiceInMemory.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/inmemory/PortalNavigationItemsQueryServiceInMemory.java
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/io/gravitee/apim/core/portal_page/use_case/CreatePortalNavigationItemUseCaseTest.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/io/gravitee/apim/core/portal_page/use_case/CreatePortalNavigationItemUseCaseTest.java
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/io/gravitee/apim/infra/adapter/PortalNavigationItemAdapterTest.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/io/gravitee/apim/infra/adapter/PortalNavigationItemAdapterTest.java
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/io/gravitee/apim/infra/query_service/portal_page/PortalNavigationItemsCrudServiceImplTest.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/io/gravitee/apim/infra/query_service/portal_page/PortalNavigationItemsCrudServiceImplTest.java
diff --git a/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/io/gravitee/apim/infra/query_service/portal_page/PortalNavigationItemsQueryServiceImplTest.java b/gravitee-apim-rest-api/gravitee-apim-rest-api-service/src/test/java/io/gravitee/apim/infra/query_service/portal_page/PortalNavigationItemsQueryServiceImplTest.java

Original file line number	Diff line number	Diff line change
`@@ -33,10 +33,10 @@ public PortalNavigationLink(`
`33`	`33`	`@Nonnull String environmentId,`
`34`	`34`	`@Nonnull String title,`
`35`	`35`	`@Nonnull PortalArea area,`
`36`		`- @Nullable PortalNavigationItemId parentId,`
	`36`	`+ @Nonnull Integer order,`
`37`	`37`	`@Nonnull String href`
`38`	`38`	`) {`
`39`		`- super(id, organizationId, environmentId, title, area, parentId);`
	`39`	`+ super(id, organizationId, environmentId, title, area, order);`
`40`	`40`	`this.href = href;`
`41`	`41`	`}`
`42`	`42`	`}`