Fall back to the library class loader for classpath resources (#1265)

In OSGi runtimes the thread context class loader cannot see
this library's bundled meta-schemas, so resolution fails with
FileNotFoundException: classpath:draft/2020-12/schema. The 1.x
ClasspathURLStreamHandler chained class loaders; the chain was not
carried over in the schema retrieval refactor (#931).

The fallback runs only after the TCCL misses, so flat classpath
behavior is unchanged, and it is skipped when a custom class loader
source is supplied.

Author: joaodinissf

src/main/java/com/networknt/schema/resource/ClasspathResourceLoader.java

@@ -35,11 +35,14 @@ public static ClasspathResourceLoader getInstance() {
 
     private final Supplier<ClassLoader> classLoaderSource;
 
+    /** Whether to fall back to this library's own class loader when the default source misses. */
+    private final boolean fallbackToOwnClassLoader;
+
     /**
      * Constructor.
      */
     public ClasspathResourceLoader() {
-        this(ClasspathResourceLoader::getClassLoader);
+        this(ClasspathResourceLoader::getClassLoader, true);
     }
 
     /**
@@ -48,7 +51,12 @@ public ClasspathResourceLoader() {
      * @param classLoaderSource the class loader source
      */
     public ClasspathResourceLoader(Supplier<ClassLoader> classLoaderSource) {
+        this(classLoaderSource, false);
+    }
+
+    private ClasspathResourceLoader(Supplier<ClassLoader> classLoaderSource, boolean fallbackToOwnClassLoader) {
         this.classLoaderSource = classLoaderSource;
+        this.fallbackToOwnClassLoader = fallbackToOwnClassLoader;
     }
 
     @Override
@@ -71,6 +79,17 @@ public InputStreamSource getResource(AbsoluteIri absoluteIri) {
                 if (result == null) {
                     result = classLoader.getResourceAsStream(resource.substring(1));
                 }
+                if (result == null && this.fallbackToOwnClassLoader) {
+                    // In OSGi the thread-context class loader is often non-null but cannot see this
+                    // library's bundled resources; retry with the library's own class loader.
+                    ClassLoader ownClassLoader = ResourceLoader.class.getClassLoader();
+                    if (ownClassLoader != null && ownClassLoader != classLoader) {
+                        result = ownClassLoader.getResourceAsStream(resource);
+                        if (result == null) {
+                            result = ownClassLoader.getResourceAsStream(resource.substring(1));
+                        }
+                    }
+                }
                 if (result == null) {
                     throw new FileNotFoundException(iri);
                 }

src/test/java/com/networknt/schema/resource/ClasspathResourceLoaderTcclTest.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2026 the original author or authors.
+ *
+ * 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.networknt.schema.resource;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.io.ByteArrayInputStream;
+import java.io.FileNotFoundException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.concurrent.Callable;
+
+import org.junit.jupiter.api.Test;
+
+import com.networknt.schema.AbsoluteIri;
+import com.networknt.schema.Schema;
+import com.networknt.schema.SchemaLocation;
+import com.networknt.schema.SchemaRegistry;
+import com.networknt.schema.dialect.DialectId;
+import com.networknt.schema.dialect.Dialects;
+
+/**
+ * Tests that the default {@link ClasspathResourceLoader} falls back to this library's own class
+ * loader when the thread-context class loader (as in OSGi) cannot see the bundled resources.
+ */
+class ClasspathResourceLoaderTcclTest {
+
+    private static final String META_SCHEMA_RESOURCE = "draft/2020-12/schema";
+
+    /** A class loader that, like an OSGi TCCL, cannot see this library's resources. */
+    private static ClassLoader blindClassLoader() {
+        return new ClassLoader(null) {
+            @Override
+            public InputStream getResourceAsStream(String name) {
+                return null;
+            }
+        };
+    }
+
+    private static <T> T withContextClassLoader(ClassLoader cl, Callable<T> body) throws Exception {
+        Thread current = Thread.currentThread();
+        ClassLoader previous = current.getContextClassLoader();
+        current.setContextClassLoader(cl);
+        try {
+            return body.call();
+        } finally {
+            current.setContextClassLoader(previous);
+        }
+    }
+
+    @Test
+    void metaSchemaLoadsWhenContextClassLoaderCannotSeeResources() throws Exception {
+        Schema metaSchema = withContextClassLoader(blindClassLoader(),
+                () -> SchemaRegistry.withDefaultDialect(Dialects.getDraft202012())
+                        .getSchema(SchemaLocation.of(DialectId.DRAFT_2020_12)));
+        assertNotNull(metaSchema);
+    }
+
+    @Test
+    void contextClassLoaderStillWinsWhenItCanSeeTheResource() throws Exception {
+        byte[] sentinel = "SENTINEL".getBytes(StandardCharsets.UTF_8);
+        ClassLoader sentinelLoader = new ClassLoader(null) {
+            @Override
+            public InputStream getResourceAsStream(String name) {
+                return META_SCHEMA_RESOURCE.equals(name) ? new ByteArrayInputStream(sentinel) : null;
+            }
+        };
+        byte[] read = withContextClassLoader(sentinelLoader, () -> {
+            InputStreamSource source = ClasspathResourceLoader.getInstance()
+                    .getResource(AbsoluteIri.of("classpath:" + META_SCHEMA_RESOURCE));
+            try (InputStream in = source.getInputStream()) {
+                byte[] buffer = new byte[sentinel.length];
+                assertEquals(sentinel.length, in.read(buffer));
+                return buffer;
+            }
+        });
+        assertEquals("SENTINEL", new String(read, StandardCharsets.UTF_8));
+    }
+
+    @Test
+    void explicitCustomClassLoaderSourceIsNotOverridden() {
+        ClasspathResourceLoader loader = new ClasspathResourceLoader(
+                ClasspathResourceLoaderTcclTest::blindClassLoader);
+        InputStreamSource source = loader.getResource(AbsoluteIri.of("classpath:" + META_SCHEMA_RESOURCE));
+        assertNotNull(source);
+        assertThrows(FileNotFoundException.class, source::getInputStream);
+    }
+}