Support for Reserved Indices (#4)

* Support for Reserved Indices

* Updating doc

* More validation in test

AdvancedFeatures.md

@@ -45,4 +45,28 @@ AbstractPibifyHandlerCache handlerCache = AbstractPibifyHandlerCache.getConcrete
                 "<<FQDN.Of.PibifyHandlerCache>>");
 ```
 
-This ensure that the IDE is able to resolve the class and the code compiles without any issues.
+This ensures that the IDE is able to resolve the class and the code compiles without any issues.
+
+### Reserved Indices
+
+If the client is deprecating a field and removing it from the codebase, it is recommended to mark the index as reserved.
+This can be done by using the `@PibifyClassMetadata` annotation on the pojo and mark the indices which should not be
+used.
+Once this is in place, a validation step will ensure any Pojo that attempts to use a reserved index will fail during
+compile time and the client must choose a different index for their field.
+This helps prevent accidental reuse of indices from deprecated fields, which could cause backward compatibility issues
+when deserializing older data.
+
+For example, if you remove a field that used index 2, you should mark index 2 as reserved to ensure
+it's not accidentally reused by a new field in the future.
+
+```java
+// Indices 2 and 3 were previously used for deprecated fields 'oldStatus' and 'legacyId'
+@PibifyClassMetadata(reservedIndices = {2, 3})
+public class ClassWithSimpleFields {
+    @Pibify(1)
+    private String name;
+    @Pibify(4) // Note: Skipping indices 2 and 3 as they are reserved
+    private int count;
+}
+```

README.md

@@ -62,7 +62,7 @@ This is the class that the clients use to get an instance of Handler for the sup
     <groupId>com.flipkart.pibify</groupId>
     <artifactId>pibify-core</artifactId>
     <scope>compile</scope>
-   <version>1.5</version>
+   <version>1.6</version>
 </dependency>
 
 ```
@@ -71,7 +71,7 @@ This is the class that the clients use to get an instance of Handler for the sup
 <plugin>
     <groupId>com.flipkart.pibify</groupId>
     <artifactId>pibify-maven-plugin</artifactId>
-   <version>1.5</version>
+   <version>1.6</version>
    <configuration>
       <excludes>
          <exclude>com/flipkart/pibify/toskip/**</exclude>

pibify-core/pom.xml

@@ -22,7 +22,7 @@
     <groupId>com.flipkart.pibify</groupId>
     <artifactId>pibify-core</artifactId>
     <packaging>jar</packaging>
-    <version>1.5</version>
+    <version>1.6</version>
     <name>pibify-core</name>
     <properties>
         <protobuf-java.version>4.28.2</protobuf-java.version>

pibify-core/src/main/java/com/flipkart/pibify/core/PibifyClassMetadata.java

@@ -0,0 +1,37 @@
+/*
+ *
+ *  *Copyright [2025] [Original Author]
+ *  *
+ *  * 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 com.flipkart.pibify.core;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation can be used to provide additional metadata to Pibify at class level
+ * Author bageshwar.pn
+ * Date 15/01/25
+ */
+@Documented
+@Target({ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface PibifyClassMetadata {
+    int[] reservedIndices() default {};
+}

pibify-maven-plugin/pom.xml

@@ -20,7 +20,7 @@
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <packaging>maven-plugin</packaging>
-    <version>1.5</version>
+    <version>1.6</version>
     <groupId>com.flipkart.pibify</groupId>
     <artifactId>pibify-maven-plugin</artifactId>
 
@@ -172,7 +172,7 @@
         <dependency>
             <groupId>com.flipkart.pibify</groupId>
             <artifactId>pibify-core</artifactId>
-            <version>1.5</version>
+            <version>1.6</version>
         </dependency>
 
         <dependency>

pibify-maven-plugin/src/main/java/com/flipkart/pibify/codegen/BeanIntrospectorBasedCodeGenSpecCreator.java

@@ -28,6 +28,7 @@
 import com.flipkart.pibify.codegen.log.SpecGenLog;
 import com.flipkart.pibify.codegen.log.SpecGenLogLevel;
 import com.flipkart.pibify.core.Pibify;
+import com.flipkart.pibify.core.PibifyClassMetadata;
 import com.pibify.shaded.com.google.common.collect.ArrayListMultimap;
 import com.pibify.shaded.com.google.common.collect.Multimap;
 import com.squareup.javapoet.ArrayTypeName;
@@ -375,6 +376,8 @@ private CodeGenSpec createImpl(Class<?> type) throws CodeGenException {
                 validateAllArgsConstructor(spec);
             }
 
+            checkForUsageOfReservedIndices(type, spec);
+
             return spec;
         } catch (IntrospectionException e) {
             throw new CodeGenException(e.getMessage(), e);
@@ -421,6 +424,17 @@ private void validate(Class<?> type, CodeGenSpec spec) {
         checkValidConstructor(type, spec);
     }
 
+    private void checkForUsageOfReservedIndices(Class<?> type, CodeGenSpec spec) {
+        PibifyClassMetadata meta = type.getAnnotation(PibifyClassMetadata.class);
+        if (meta != null) {
+            for (int reservedIndex : meta.reservedIndices()) {
+                if (spec.getFields().stream().anyMatch(f -> f.getIndex() == reservedIndex)) {
+                    log(new CodeSpecGenLog(SpecGenLogLevel.ERROR, "Reserved index " + reservedIndex + " is already in use"));
+                }
+            }
+        }
+    }
+
     private void checkValidConstructor(Class<?> type, CodeGenSpec spec) {
 
         // No need to validate constructor for abstract classes

pibify-maven-plugin/src/test/java/com/flipkart/pibify/codegen/BeanIntrospectorBasedCodeGenSpecCreatorTest.java

@@ -32,6 +32,7 @@
 import com.flipkart.pibify.test.data.ClassWithNativeCollectionsOfCollections2;
 import com.flipkart.pibify.test.data.ClassWithNativeFields;
 import com.flipkart.pibify.test.data.ClassWithReferences;
+import com.flipkart.pibify.test.data.ClassWithSimpleFields;
 import com.flipkart.pibify.test.data.jsoncreator.DuplicatePropertyNames;
 import com.flipkart.pibify.test.data.jsoncreator.MismatchedPropertyNames;
 import com.flipkart.pibify.test.data.jsoncreator.PartialConstructor;
@@ -680,4 +681,18 @@ public void testRenamedBooleanInConstructor() throws CodeGenException {
         assertEquals(SpecGenLogLevel.INFO, creator.status(forTest));
         assertEquals(0, creator.getLogsForCurrentEntity().size());
     }
+
+    @Test
+    public void testReservedIndices() throws CodeGenException {
+        Class<?> forTest = ClassWithSimpleFields.class;
+        BeanIntrospectorBasedCodeGenSpecCreator creator = new BeanIntrospectorBasedCodeGenSpecCreator();
+        CodeGenSpec codeGenSpec = creator.create(forTest);
+        assertNotNull(codeGenSpec);
+        List<SpecGenLog> logs = new ArrayList<>(creator.getLogsForCurrentEntity());
+        logs.forEach(l -> System.out.println(l.getLogMessage()));
+        assertEquals(SpecGenLogLevel.ERROR, creator.status(forTest));
+        assertEquals(2, logs.size());
+        assertEquals("com.flipkart.pibify.test.data.ClassWithSimpleFields Reserved index 2 is already in use", logs.get(0).getLogMessage());
+        assertEquals("com.flipkart.pibify.test.data.ClassWithSimpleFields Reserved index 3 is already in use", logs.get(1).getLogMessage());
+    }
 }

pibify-maven-plugin/src/test/java/com/flipkart/pibify/test/data/ClassWithSimpleFields.java

@@ -0,0 +1,42 @@
+/*
+ *
+ *  *Copyright [2025] [Original Author]
+ *  *
+ *  * 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 com.flipkart.pibify.test.data;
+
+import com.flipkart.pibify.core.Pibify;
+import com.flipkart.pibify.core.PibifyClassMetadata;
+
+/**
+ * This class is used for testing reserved indicices
+ * Author bageshwar.pn
+ * Date 25/07/24
+ */
+
+@PibifyClassMetadata(reservedIndices = {2, 3})
+public class ClassWithSimpleFields {
+
+    @Pibify(1)
+    public String aString = "1";
+
+    @Pibify(2)
+    public int anInt = 2;
+
+    @Pibify(3)
+    public long aLong = 3L;
+
+}

test-environments/dropwizard/test-dropwizard/pom.xml

@@ -69,7 +69,7 @@
         <dependency>
             <groupId>com.flipkart.pibify</groupId>
             <artifactId>pibify-core</artifactId>
-            <version>1.5</version>
+            <version>1.6</version>
         </dependency>
     </dependencies>
 
@@ -112,7 +112,7 @@
             <plugin>
                 <groupId>com.flipkart.pibify</groupId>
                 <artifactId>pibify-maven-plugin</artifactId>
-                <version>1.3</version>
+                <version>1.6</version>
                 <configuration>
                     <excludes>
                         <!--                            <exclude>com/flipkart/pibify/toskip/**</exclude>-->

test-environments/lombok/pom.xml

@@ -106,7 +106,7 @@
         <dependency>
             <groupId>com.flipkart.pibify</groupId>
             <artifactId>pibify-core</artifactId>
-            <version>1.5</version>
+            <version>1.6</version>
             <scope>compile</scope>
         </dependency>
     </dependencies>

test-environments/pibify-test-vanilla/pom.xml

@@ -46,7 +46,7 @@
         <plugin>
             <groupId>com.flipkart.pibify</groupId>
             <artifactId>pibify-maven-plugin</artifactId>
-            <version>1.5</version>
+            <version>1.6</version>
             <configuration>
                 <excludes>
                     <exclude>com/flipkart/pibify/toskip/**</exclude>
@@ -68,7 +68,7 @@
         <plugin>
             <groupId>com.flipkart.pibify</groupId>
             <artifactId>pibify-maven-plugin</artifactId>
-            <version>1.5</version>
+            <version>1.6</version>
             <configuration>
                 <incremental>true</incremental>
                 <incrementalBuildProvider>com.flipkart.pibify.mvn.GitIncrementalBuildProvider</incrementalBuildProvider>
@@ -137,7 +137,7 @@
         <dependency>
             <groupId>com.flipkart.pibify</groupId>
             <artifactId>pibify-core</artifactId>
-            <version>1.5</version>
+            <version>1.6</version>
             <scope>compile</scope>
         </dependency>
         <dependency>

test-environments/vertx/pom.xml

@@ -122,7 +122,7 @@
         <dependency>
             <groupId>com.flipkart.pibify</groupId>
             <artifactId>pibify-core</artifactId>
-            <version>1.5</version>
+            <version>1.6</version>
             <scope>compile</scope>
         </dependency>
     </dependencies>