Create the Elements of an Area on demand instead of holding one of each

Every Area held a live instance of each of its types, only so that
createElement() could be called on it to make a copy. That meant the
class of every type was loaded as soon as the Area was, whether or not
a deployment ever exchanged that type.

The generator now writes an ElementFactory for each Area, which switches
on the service number and then on the type number, so a class is loaded
only once a message carries that type. The element arrays of the Areas
and Services are left empty.

The type numbers of an Area are handed out from 1 upwards, so the switch
takes the widest band that starts at 1 and still compiles to a jump
table. What lies past that band goes to a second method. Where those
numbers lie far from zero, each side of zero is switched on its own:
together they would have to span the whole way across zero and would
fall back to a binary search.

On a Raspberry Pi the Areas now load in 411 ms rather than 1199 ms.

MALElementsRegistry no longer keeps a map of live Elements, so
addElement(), removeCallableElement() and howMany() are gone with it.
More than one factory can be registered for the same Area, which is how
the MAL/SPP testbed reaches its two hand written enumerations: their
type numbers are past what the XML schema allows, so no generated
factory can know about them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: CesarCoelho

api-generator/generator-java/pom.xml

@@ -80,6 +80,11 @@
             <groupId>com.sun.xml.bind</groupId>
             <artifactId>jaxb-impl</artifactId>
         </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

api-generator/generator-java/src/main/java/esa/mo/tools/stubgen/GeneratorLangs.java

@@ -21,6 +21,7 @@
 package esa.mo.tools.stubgen;
 
 import esa.mo.tools.stubgen.java.JavaCompositeClass;
+import esa.mo.tools.stubgen.java.JavaElementFactory;
 import esa.mo.tools.stubgen.java.JavaServiceInfo;
 import esa.mo.tools.stubgen.java.JavaExceptions;
 import esa.mo.tools.stubgen.java.JavaConsumer;
@@ -354,6 +355,10 @@ public void run() {
             logger.info(" > Creating Area Helper class: " + area.getName());
             helper.createAreaHelperClass(areaFolder, area);
 
+            logger.info(" > Creating Area Element Factory class: " + area.getName());
+            JavaElementFactory elementFactory = new JavaElementFactory(this, typeInformation);
+            elementFactory.createAreaElementFactoryClass(areaFolder, area);
+
             // Create Area Exceptions
             JavaExceptions exceptions = new JavaExceptions(this);
             logger.info(" > Creating Area Exceptions for area: " + area.getName());

api-generator/generator-java/src/main/java/esa/mo/tools/stubgen/java/JavaElementFactory.java

@@ -172,10 +172,10 @@ public void createAreaHelperClass(File areaFolder, AreaType area) throws IOExcep
             }
         }
 
+        // Left empty on purpose: the Area factory creates these on demand, so
+        // that the class of a type is only loaded once a message carries it.
         StringBuilder buf = new StringBuilder();
-        for (String objectCall : elementList) {
-            buf.append("\n        ").append(objectCall).append(",");
-        }
+        elementList.clear();
         CompositeField objectInstVar = generator.createCompositeElementsDetails(file, false, areaNameCAPS + "_AREA_ELEMENTS",
                 TypeUtils.createTypeReference(null, null, "org.ccsds.moims.mo.mal.structures.Element", false),
                 false, true, "Area Elements.");
@@ -196,6 +196,8 @@ public void createAreaHelperClass(File areaFolder, AreaType area) throws IOExcep
                 false, true, buf_2.toString(), false);
 
         String areaObjectInitialValue = createAreaHelperClassInitialValue(areaNameCAPS, area.getVersion());
+        areaObjectInitialValue = areaObjectInitialValue.substring(0, areaObjectInitialValue.length() - 1)
+                + ", new " + areaName + "ElementFactory())";
         file.addClassVariable(true, true, StdStrings.PUBLIC, areaVar, true, areaObjectInitialValue);
 
         // create error numbers
@@ -221,6 +223,7 @@ public void createAreaHelperClass(File areaFolder, AreaType area) throws IOExcep
         file.flush();
     }
 
+
     public String createAreaHelperClassInitialValue(String areaVar, short areaVersion) {
         return "(" + areaVar + "_AREA_NUMBER, " + areaVar + "_AREA_NAME, "
                 + areaVar + "_AREA_VERSION, " + areaVar + "_AREA_ELEMENTS, " + areaVar + "_AREA_SERVICES)";

api-generator/generator-java/src/main/java/esa/mo/tools/stubgen/java/JavaHelpers.java

@@ -184,10 +184,10 @@ public void createServiceInfoClass(File serviceFolder, AreaType area,
             }
         }
 
+        // Left empty on purpose: the Area factory creates these on demand, so
+        // that the class of a type is only loaded once a message carries it.
         StringBuilder buf = new StringBuilder();
-        for (String objectCall : elementInstantiations) {
-            buf.append("\n        ").append(objectCall).append(",");
-        }
+        elementInstantiations.clear();
         CompositeField objectInstVar = generator.createCompositeElementsDetails(file, false, serviceCAPS + "_SERVICE_ELEMENTS",
                 TypeUtils.createTypeReference(null, null, "org.ccsds.moims.mo.mal.structures.Element", false),
                 false, true, "Area elements.");

api-generator/generator-java/src/main/java/esa/mo/tools/stubgen/java/JavaServiceInfo.java

@@ -0,0 +1,241 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2024      European Space Agency
+ *                         European Space Operations Centre
+ *                         Darmstadt
+ *                         Germany
+ * ----------------------------------------------------------------------------
+ * System                : CCSDS MO Service Stub Generator
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package esa.mo.tools.stubgen.java;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import org.junit.Test;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * Tests the rule that decides how far the switch of an area factory reaches
+ * before the rest of the type numbers are moved out to a second method.
+ */
+public class TestJavaElementFactory {
+
+    /**
+     * Builds the type numbers of an area the way the generator sees them: a
+     * type and the list that holds it, which takes the same number negated.
+     *
+     * @param magnitudes The declared type numbers.
+     * @return The type numbers with the numbers of their lists.
+     */
+    private static Collection<Integer> withLists(int... magnitudes) {
+        List<Integer> numbers = new ArrayList<>();
+
+        for (int magnitude : magnitudes) {
+            numbers.add(magnitude);
+            numbers.add(-magnitude);
+        }
+
+        return numbers;
+    }
+
+    private static int[] range(int first, int last) {
+        int[] numbers = new int[last - first + 1];
+
+        for (int i = 0; i < numbers.length; i++) {
+            numbers[i] = first + i;
+        }
+
+        return numbers;
+    }
+
+    /**
+     * An area whose numbers run without a gap is answered by one switch, so the
+     * band has to reach the last of them.
+     */
+    @Test
+    public void bandCoversAnAreaThatHasNoGaps() {
+        assertEquals(12, JavaElementFactory.widestJumpTableBand(withLists(range(1, 12))));
+        assertEquals(45, JavaElementFactory.widestJumpTableBand(withLists(range(1, 45))));
+    }
+
+    /**
+     * The numbers of the MAL run 1 to 19, then 101 to 105, then 1001 to 1010.
+     * The first two groups are close enough to be held together, the last one
+     * is not, so it is left for the second method.
+     */
+    @Test
+    public void bandStopsBeforeAGapThatIsTooWideToPayFor() {
+        List<Integer> mal = new ArrayList<>();
+        mal.addAll(withLists(range(1, 19)));
+        mal.addAll(withLists(range(101, 105)));
+        mal.addAll(withLists(range(1001, 1010)));
+
+        assertEquals(105, JavaElementFactory.widestJumpTableBand(mal));
+    }
+
+    /**
+     * A group of numbers that lies past a gap is still taken in when it is
+     * dense enough to pay for the gap in front of it. Stopping at the first
+     * candidate that fails would leave it out.
+     */
+    @Test
+    public void bandReachesPastAGapThatTheNumbersBehindItPayFor() {
+        List<Integer> numbers = new ArrayList<>();
+        numbers.addAll(withLists(1, 2, 3));
+        numbers.addAll(withLists(range(20, 60)));
+
+        assertEquals(60, JavaElementFactory.widestJumpTableBand(numbers));
+    }
+
+    /**
+     * The band is counted out from 1, not placed on the longest run of numbers
+     * that follow one another. An area that starts with a gap would otherwise
+     * leave its first types out of the jump table.
+     */
+    @Test
+    public void bandIsAnchoredAtOneAndNotOnTheLongestRun() {
+        // The run 10 to 15 is the longest, but 1 and 6 come first
+        List<Integer> numbers = new ArrayList<>();
+        numbers.addAll(withLists(1, 6));
+        numbers.addAll(withLists(range(10, 15)));
+
+        int band = JavaElementFactory.widestJumpTableBand(numbers);
+        assertEquals(15, band);
+        assertTrue("Type number 1 has to be inside the band", band >= 1);
+    }
+
+    /**
+     * A single type is answered by a lookup rather than by a jump table, so
+     * there is no band and the types are left in one switch.
+     */
+    @Test
+    public void aSingleTypeHasNoBand() {
+        assertEquals(0, JavaElementFactory.widestJumpTableBand(withLists(1)));
+    }
+
+    /**
+     * A number that lies on its own far from the rest cannot widen the band,
+     * whatever else the area declares.
+     */
+    @Test
+    public void aLoneNumberFarOutIsLeftOutOfTheBand() {
+        List<Integer> numbers = new ArrayList<>();
+        numbers.addAll(withLists(range(1, 20)));
+        numbers.addAll(withLists(5000));
+
+        assertEquals(20, JavaElementFactory.widestJumpTableBand(numbers));
+    }
+
+    /**
+     * The band that is chosen has to be one the Java compiler really answers
+     * with a jump table, and the one past it must not be.
+     */
+    @Test
+    public void chosenBandIsTheWidestThatStillCompilesToAJumpTable() {
+        List<Integer> numbers = new ArrayList<>();
+        numbers.addAll(withLists(range(1, 19)));
+        numbers.addAll(withLists(range(101, 105)));
+        numbers.addAll(withLists(range(1001, 1010)));
+
+        int band = JavaElementFactory.widestJumpTableBand(numbers);
+        int inside = 0;
+
+        for (Integer number : numbers) {
+            if (Math.abs(number) <= band) {
+                inside++;
+            }
+        }
+
+        assertTrue("The chosen band is not a jump table",
+                JavaElementFactory.compilesToJumpTable(inside, 2L * band + 1L));
+        assertTrue("The whole area would still be a jump table",
+                !JavaElementFactory.compilesToJumpTable(numbers.size(), 2L * 1010 + 1L));
+    }
+
+    /**
+     * Nothing to switch over is answered with no band, rather than with an
+     * empty one that the generator would then try to split.
+     */
+    @Test
+    public void noTypesGiveNoBand() {
+        assertEquals(0, JavaElementFactory.widestJumpTableBand(new ArrayList<>()));
+    }
+
+    /**
+     * Numbers that lie far from zero leave the whole way across zero empty
+     * between the types and their lists, so each side is switched on its own.
+     */
+    @Test
+    public void numbersFarFromZeroAreSwitchedOneSideAtATime() {
+        assertTrue(JavaElementFactory.shouldSplitOnSign(withLists(range(1001, 1010))));
+    }
+
+    /**
+     * Numbers that already answer with a jump table gain nothing from being
+     * taken apart, and would only pay for the test that reaches each side.
+     */
+    @Test
+    public void numbersThatAreAlreadyAJumpTableAreLeftWhole() {
+        assertFalse(JavaElementFactory.shouldSplitOnSign(withLists(range(1, 19))));
+        assertFalse(JavaElementFactory.shouldSplitOnSign(withLists(range(1, 105))));
+    }
+
+    /**
+     * A single type far from zero is reached faster by one lookup over both of
+     * its numbers than by a test and a jump table holding one entry each.
+     */
+    @Test
+    public void aSingleTypeFarFromZeroIsLeftWhole() {
+        assertFalse(JavaElementFactory.shouldSplitOnSign(withLists(90)));
+    }
+
+    /**
+     * There is nothing to take apart when the numbers all fall on one side of
+     * zero.
+     */
+    @Test
+    public void numbersOnOneSideOfZeroAreLeftWhole() {
+        List<Integer> positives = new ArrayList<>();
+
+        for (int number = 1001; number <= 1010; number++) {
+            positives.add(number);
+        }
+
+        assertFalse(JavaElementFactory.shouldSplitOnSign(positives));
+        assertFalse(JavaElementFactory.shouldSplitOnSign(new ArrayList<>()));
+    }
+
+    /**
+     * Both sides have to be worth a jump table on their own. One side that
+     * stays a binary search is not worth the test that reaches it.
+     */
+    @Test
+    public void bothSidesHaveToBeWorthAJumpTable() {
+        // The lists follow one another, the types themselves do not
+        List<Integer> lopsided = new ArrayList<>();
+
+        for (int number = 1001; number <= 1010; number++) {
+            lopsided.add(-number);
+        }
+
+        lopsided.add(1001);
+        lopsided.add(3000);
+        lopsided.add(9000);
+
+        assertFalse(JavaElementFactory.shouldSplitOnSign(lopsided));
+    }
+}

api-generator/generator-java/src/test/java/esa/mo/tools/stubgen/java/TestJavaElementFactory.java

@@ -0,0 +1,61 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) 2024      European Space Agency
+ *                         European Space Operations Centre
+ *                         Darmstadt
+ *                         Germany
+ * ----------------------------------------------------------------------------
+ * System                : CCSDS MO MAL Java API
+ * ----------------------------------------------------------------------------
+ * Licensed under the European Space Agency Public License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ *
+ * Except as expressly set forth in this License, the Software is provided to
+ * You on an "as is" basis and without warranties of any kind, including without
+ * limitation merchantability, fitness for a particular purpose, absence of
+ * defects or errors, accuracy or non-infringement of intellectual property rights.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ----------------------------------------------------------------------------
+ */
+package org.ccsds.moims.mo.mal;
+
+import org.ccsds.moims.mo.mal.structures.Element;
+
+/**
+ * Creates the Elements of one Area.
+ *
+ * One of these is generated for each Area, and answers with a new Element for a
+ * service number and a type number of that Area. The generated implementation
+ * is a switch on the service number, and then a switch on the type number, so
+ * that the class of a type is only ever loaded when a message actually carries
+ * that type. Holding an instance of every type instead, only to be able to ask
+ * it for a copy of itself, made every one of them load at start up.
+ */
+public interface AreaElementFactory {
+
+    /**
+     * Returns a new Element of the given type, or null if this Area does not
+     * define it.
+     *
+     * @param serviceNumber The service the type belongs to, or 0 for the types
+     * defined by the Area itself.
+     * @param typeNumber The type number, negative for the list of a type.
+     * @return A new Element, or null if this Area does not define that type.
+     */
+    Element createElement(int serviceNumber, int typeNumber);
+
+    /**
+     * Returns the number of the Area this factory creates the Elements of.
+     *
+     * @return The Area number.
+     */
+    int getAreaNumber();
+
+    /**
+     * Returns the version of the Area this factory creates the Elements of.
+     *
+     * @return The Area version.
+     */
+    int getAreaVersion();
+}