J3MLoader: Ensures clean instance state + javadoc

[capdevon]

Next Step:
Needs the Merge of PR #2482 first

To nullify the material and/or materialDef variables after loading within the load(AssetInfo) method in J3MLoader.java, you should set them to null in a finally block. This ensures that the variables are cleared regardless of whether the loading process completes successfully or an exception occurs.

Here's why and how:

Why Nullify?

1. Memory Management (Garbage Collection): Although Java's garbage collector will eventually reclaim memory for objects that are no longer referenced, explicitly nullifying instance variables after they are no longer needed can make the objects they refer to eligible for garbage collection sooner. This is particularly relevant if the J3MLoader instance itself is reused to load multiple assets over its lifetime.
2. Preventing State Leakage: If the J3MLoader instance is reused for subsequent asset loads, nullifying these variables prevents accidental use of data from a previous load operation, helping to maintain a clean state for each new load.
3. Clarity and Defensive Programming: It clearly signifies that the loader has finished processing these specific material-related objects for the current load operation.

How to Implement

Add the nullification logic in a finally block within the load method. This block guarantees execution, ensuring proper cleanup.

J3MLoader.java file:

@Override
public Object load(AssetInfo info) throws IOException {

    InputStream in = info.openStream();

    try {
        key = info.getKey(); // Initialize 'key' specific to this load operation
        this.assetManager = info.getManager();
        ... ...

        loadFromRoot(BlockLanguageParser.parse(in)); // This call populates 'material' or 'materialDef'

        // Determine which asset was loaded and assign it to loadedAsset
        Object loadedAsset = null;
        if (material != null) {
            loadedAsset = material;
        } else if (materialDef != null) {
            loadedAsset = materialDef;
        }

        return loadedAsset;

    } finally {
        // --- Nullify and clear transient instance variables here ---
        material = null;
        materialDef = null;
        key = null;
        assetManager = null;
        nodesLoaderDelegate = null;
        isUseNodes = false;

        // Close the input stream to release resources
        try {
            in.close();
        } catch (IOException ex) {
            logger.log(Level.SEVERE, "Error closing input stream for asset {0}: {1}", new Object[]{info.getKey(), ex.getMessage()});
        }
    }
}

By adding this finally block, you ensure a robust cleanup process for your J3MLoader instance, making it more memory-efficient and preventing potential state-related bugs when the loader is reused.

[capdevon]

This is the last PR I would like to propose, but as mentioned before, it requires the merge of the other PR.

[pspeed42]

80% sure that the loaders are instantiated on demand and then thrown away. Otherwise, multithreaded asset loading would be completely busted because a lot of them use their own fields like this.

...so leaving them set causes no harm because the loader is going to be thrown away anyway.

[pspeed42]

Nope. I'm wrong. Apparently is does use a thread local: https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-core/src/main/java/com/jme3/asset/ImplHandler.java#L191

...so, yeah, we're leaving this around until the next material is loaded.