The standard directory layout

Maven does not ask where the sources are: it has a layout, and a project that follows it needs no folder in its pom. The layout is the same for every Maven project in the world, which is what lets a person who has never seen a repository find the code, the tests, the resources and the output in it. This article builds a small project that uses all four folders and shows what each one contributes.

The layout

A Maven project follows one layout, and a project that follows it needs no folder in its pom: the code in src/main/java, the resources the code reads in src/main/resources, the tests in src/test/java, the resources the tests read in src/test/resources, and everything the build writes in target. A folder a project does not need is simply absent, and Maven says so in its log instead of failing: skip non existing resourceDirectory. This project has a src/main/resources and no src/test/resources, so both messages appear in the build below.

The pom is the short one of the first article plus one test dependency. Its only property is the release of the compiler:

pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>layout</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> <dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.14.3</version> <scope>test</scope> </dependency> </dependencies> </project>

src/main/java

Everything under src/main/java is compiled into target/classes. The folder holds the package tree, not the package name: the class below declares package com.example.layout and lives in src/main/java/com/example/layout/. A file whose folder and package disagree still compiles with plain javac, and Maven does the same, but every tool that reads the tree by its folders, from an IDE to a jar task, expects the two to match.

src/main/java/com/example/layout/Main.java

package com.example.layout; import java.io.IOException; import java.io.InputStream; import java.util.Properties; public class Main { static String greeting() throws IOException { Properties props = new Properties(); try (InputStream in = Main.class.getResourceAsStream("/messages.properties")) { props.load(in); } return props.getProperty("greeting"); } public static void main(String[] args) throws IOException { System.out.println(greeting()); } }

src/main/resources

A resource is a file the program reads at run time: a properties file, a message bundle, a template, an image. It is not compiled, it is copied, and the copy lands in target/classes, which is the root of the class path. That is why the program asks for /messages.properties with a slash at the start: the resource is at the root of the class path, not in a package.

src/main/resources/messages.properties

greeting=Hello from a resource

A properties file is ISO-8859-1 by the Java specification, and the resources plugin warns about the encoding when filtering is on; the resources article comes back to that. Without filtering the file is copied byte for byte, so this one keeps its ASCII and needs no setting.

src/test/java

Test sources live in src/test/java, in the same package as the code they test, and they are compiled into target/test-classes. The two output folders explain the scopes of the dependency article: a test dependency is on the class path of the test compile and of the test run, and not on the class path of the code.

src/test/java/com/example/layout/MainTest.java

package com.example.layout; import static org.junit.jupiter.api.Assertions.assertEquals; import java.io.IOException; import org.junit.jupiter.api.Test; class MainTest { @Test void greetingComesFromTheResource() throws IOException { assertEquals("Hello from a resource", Main.greeting()); } }

The test class is package-private, and that is enough: surefire finds a test class that is not public, and the test calls the package-private method of the class under test without reflection.

The same three files on disk

The folders of the layout, as find lists them, and the three files inside them:

find src -type d | sort
find src -type f | sort

src
src/main
src/main/java
src/main/java/com
src/main/java/com/example
src/main/java/com/example/layout
src/main/resources
src/test
src/test/java
src/test/java/com
src/test/java/com/example
src/test/java/com/example/layout
src/main/java/com/example/layout/Main.java
src/main/resources/messages.properties
src/test/java/com/example/layout/MainTest.java

The two trees share the package path com/example/layout and nothing else. There is no src/test/resources folder, and the build below says so instead of treating it as an error.

What the build writes

mvn package runs resources, compile, testResources, testCompile, surefire and jar in that order, and every one of them writes into target/:

mvn -B package > build.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" build.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:layout >-------------------------
[INFO] Building layout 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ layout ---
[INFO] Copying 1 resource from src/main/resources to target/classes
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ layout ---
[INFO] Recompiling the module because of changed source code.
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO]
[INFO] --- resources:3.4.0:testResources (default-testResources) @ layout ---
[INFO] skip non existing resourceDirectory <project>/src/test/resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ layout ---
[INFO] Recompiling the module because of changed dependency.
[INFO] Compiling 1 source file with javac [debug release 21] to target/test-classes
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ layout ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.layout.MainTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.082 s -- in com.example.layout.MainTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ layout ---
[INFO] Building jar: <project>/target/layout-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5.110 s
[INFO] Finished at: 2026-11-22T08:27:53Z
[INFO] ------------------------------------------------------------------------

Eleven files came out of the build, and each of them has an owner:

find target -type f | sort

target/classes/com/example/layout/Main.class
target/classes/messages.properties
target/layout-1.0.0.jar
target/maven-archiver/pom.properties
target/maven-status/maven-compiler-plugin/compile/default-compile/createdFiles.lst
target/maven-status/maven-compiler-plugin/compile/default-compile/inputFiles.lst
target/maven-status/maven-compiler-plugin/testCompile/default-testCompile/createdFiles.lst
target/maven-status/maven-compiler-plugin/testCompile/default-testCompile/inputFiles.lst
target/surefire-reports/TEST-com.example.layout.MainTest.xml
target/surefire-reports/com.example.layout.MainTest.txt
target/test-classes/com/example/layout/MainTest.class

target is disposable: mvn clean deletes the whole folder, and no file in it is versioned. A project that puts something into target by hand loses it on the next clean, which is the point.

The program runs from the classes folder, and the resource is found because the copy sits next to it:

java -cp target/classes com.example.layout.Main

Hello from a resource

What the jar holds

The jar is the classes folder plus the resource, zipped, with the Maven entries:

jar tf target/layout-1.0.0.jar | sort

META-INF/
META-INF/MANIFEST.MF
META-INF/maven/
META-INF/maven/com.example/
META-INF/maven/com.example/layout/
META-INF/maven/com.example/layout/pom.properties
META-INF/maven/com.example/layout/pom.xml
com/
com/example/
com/example/layout/
com/example/layout/Main.class
messages.properties

The test class is not in the jar: surefire compiled it into target/test-classes, and the jar plugin packs target/classes only. The resource is at the root of the jar, which is why the program finds it with the same name from the classes folder and from the jar. The pom inside META-INF/maven is a copy, not a source: nothing in the build reads it back.

Where to go next

The pom article reads the file this project keeps at its root, and the lifecycle article explains the order of the six steps the log above shows.

Article author: Arthur Isaev