Restructure example_resources m4 src layout

Reorganize m4/src directory to follow proper Maven directory
structure with separate java/ and resources/ subdirectories for
each module. This change addresses Java compiler limitations with
symlinked source files.

Changes:
- Restructure m4/src with Maven-standard layout:
  - src/{module}/main/java/ for Java source files
  - src/{module}/main/resources/ for resource files
- Copy all source files (symlinks don't work with javac)
- Update pom.xml to read resources from new structure
- Add verify-sources.sh to ensure consistency with ../src
- Update verify.sh to call verify-sources.sh as Step 0
- Document structure and symlink limitation in README.adoc

Technical limitation: The Java compiler cannot resolve module
structure when source files are symlinked from outside the module
source path (--module-source-path). When javac encounters such
symlinks, it fails with "module not found on module source path"
errors. Therefore, m4/src/ contains full copies of all files from
../src/, reorganized into Maven's standard directory layout.

The verify-sources.sh script validates that all files remain
identical between ../src and m4/src despite different layouts,
running automatically as part of the verification workflow.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Introduced in the course of support-and-care/maven-support-and-care#137

Author: ascheman

jigsaw-examples/example_resources/README.adoc

@@ -67,7 +67,52 @@ include::m4/run-result/run.txt[]
 [[sec:maven-4-migration]]
 == Maven 4 Migration
 
-This example was migrated to Maven 4 using the standard approach documented in the xref:../../README.adoc#maven-4-migration[central Maven 4 Migration guide].
+This example was migrated to Maven 4 with a special source tree structure to properly separate Java source files from resources, following Maven conventions.
 
-The source files follow the standard Module Source Hierarchy setup.
-Resource handling required explicit configuration of `maven-resources-plugin` to copy `.properties` files from the modular source directories to the target classes directories, as the hybrid compilation approach only packages compiled `.class` files by default.
+The `m4/src` directory follows proper Maven directory conventions with separate `java/` and `resources/` subdirectories:
+
+[source]
+----
+m4/src/
+├── modb/main/
+│   ├── java/              # Java source files only
+│   │   ├── module-info.java
+│   │   ├── pkgb/B.java
+│   │   └── pkgbinternal/BInternal.java
+│   └── resources/         # Resource files only
+│       ├── pkgb/b.properties
+│       ├── pkgbinternal/binternal.properties
+│       └── resources.modb/resources.properties
+├── modc/main/
+│   ├── java/              # Java source files only
+│   │   ├── module-info.java
+│   │   ├── pkgc/C.java
+│   │   └── pkgcinternal/CInternal.java
+│   └── resources/         # Resource files only
+│       ├── cnopackage.properties
+│       ├── pkgc/c.properties
+│       ├── pkgcinternal/cinternal.properties
+│       └── resources.modc/resources.properties
+└── modmain/main/
+    └── java/              # Java source files only (no resources)
+        ├── module-info.java
+        ├── pkgmain/Main.java
+        └── pkgmaininternal/IdGen.java
+----
+
+This structure differs from the original `src/` directory where Java and resource files coexist in the same package directories.
+The Maven build properly handles resources through explicit `maven-resources-plugin` configuration that copies resource files from `src/<module>/main/resources` to `target/classes/<module>`.
+
+[CAUTION]
+.Why Source Files Are Copied, Not Symlinked
+====
+Unlike other examples where we use symbolic links to reference the original `src/` directory, this example requires _full copies_ of all source files in `m4/src/`.
+
+The Java compiler cannot properly resolve module structure when individual source files are symlinked from locations outside the module source path.
+When using `--module-source-path`, `javac` expects all files of a module to reside within a single directory tree and fails with "module not found on module source path" errors when encountering symlinks pointing outside that tree.
+
+Therefore, `m4/src/` contains actual file copies of all Java sources and resources from the original `src/` directory, reorganized into Maven's standard directory structure.
+
+To ensure consistency between the original sources and the Maven 4 copies, the `m4/verify-sources.sh` script validates that all files are identical despite the different directory layouts.
+This script runs automatically as part of `m4/verify.sh`.
+====

jigsaw-examples/example_resources/m4/pom.xml

@@ -52,14 +52,7 @@
               <outputDirectory>${project.build.directory}/classes/modb</outputDirectory>
               <resources>
                 <resource>
-                  <directory>src/modb/main/java</directory>
-                  <includes>
-                    <include>**/*.properties</include>
-                    <include>**/*.txt</include>
-                  </includes>
-                  <excludes>
-                    <exclude>**/*.java</exclude>
-                  </excludes>
+                  <directory>src/modb/main/resources</directory>
                 </resource>
               </resources>
             </configuration>
@@ -74,36 +67,7 @@
               <outputDirectory>${project.build.directory}/classes/modc</outputDirectory>
               <resources>
                 <resource>
-                  <directory>src/modc/main/java</directory>
-                  <includes>
-                    <include>**/*.properties</include>
-                    <include>**/*.txt</include>
-                  </includes>
-                  <excludes>
-                    <exclude>**/*.java</exclude>
-                  </excludes>
-                </resource>
-              </resources>
-            </configuration>
-          </execution>
-          <execution>
-            <id>copy-modmain-resources</id>
-            <phase>process-resources</phase>
-            <goals>
-              <goal>copy-resources</goal>
-            </goals>
-            <configuration>
-              <outputDirectory>${project.build.directory}/classes/modmain</outputDirectory>
-              <resources>
-                <resource>
-                  <directory>src/modmain/main/java</directory>
-                  <includes>
-                    <include>**/*.properties</include>
-                    <include>**/*.txt</include>
-                  </includes>
-                  <excludes>
-                    <exclude>**/*.java</exclude>
-                  </excludes>
+                  <directory>src/modc/main/resources</directory>
                 </resource>
               </resources>
             </configuration>

jigsaw-examples/example_resources/m4/src/modb/main/java

@@ -0,0 +1,6 @@
+module modb {
+    requires transitive modc;
+
+    exports pkgb;
+    opens   pkgb;
+}

jigsaw-examples/example_resources/m4/src/modb/main/java/module-info.java

@@ -0,0 +1,46 @@
+package pkgb;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Properties;
+
+import pkgc.*;
+
+public class B {
+    public String doIt() {
+        return "from B";
+    }
+
+    public C getMyC() {
+        return new C();
+    }
+
+    // access resources in modb
+    public String getTextFromProperties() throws IOException {
+    	String resourceFileName = "/resources.modb/resources.properties";		// now we get modb's resources.properties
+    	
+		final Properties properties = new Properties();
+		try (final InputStream stream = B.class.getModule().getResourceAsStream(resourceFileName)) {
+		    properties.load(stream);
+		}
+		return properties.getProperty("text", "modb's resources properties not found in modb");
+    }
+
+    // access resources in modc (from modb)
+    public String getTextFromMODCsProperties() throws IOException {
+    	String resourceFileName = "/pkgc/c.properties";		// The resource path must be resolveable as a package name *and* this package has to be open (see modc's module-info.java)
+    														// Note that just an export on this package name is not sufficient for access!
+
+    	final Properties properties = new Properties();
+		try (final InputStream stream = C.class.getModule().getResourceAsStream(resourceFileName)) {
+		    properties.load(stream);
+		}
+		String propertyFromMODC = properties.getProperty("text");
+		if (propertyFromMODC == null) {
+		    return "modc's resources properties not found via modb";
+		}
+		else {
+		    return propertyFromMODC + " - but retrieved via modb!";
+		}
+    }
+}

jigsaw-examples/example_resources/m4/src/modb/main/java/pkgb/B.java

@@ -0,0 +1,5 @@
+package pkgbinternal;
+
+public class BInternal {
+// does not do anything - just there to ensure that there is an package pkgbinternal
+}

jigsaw-examples/example_resources/m4/src/modb/main/java/pkgbinternal/BInternal.java

@@ -0,0 +1,2 @@
+# Can only be accessed from outside modb, if package pkgb is open'ed in modb's module-info
+text=Hello World, from modb's b.properties (whose package is opened)

jigsaw-examples/example_resources/m4/src/modb/main/resources/pkgb/b.properties

@@ -0,0 +1,2 @@
+# Can only be accessed from outside modb, if package pkgbinternal would be open'ed in modb's module-info
+text=Hello World, from modb's binternal.properties (whose package is not opened)

jigsaw-examples/example_resources/m4/src/modb/main/resources/pkgbinternal/binternal.properties

@@ -0,0 +1,2 @@
+# Can only be accessed from outside modb, if package resources.modb would be open'ed in modb's module-info
+text=Hello World, from modb's resources.properties