Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 41 ยท Getting Started

The Standard Directory Layout

Learn every folder in a Maven project: src/main/java, src/main/resources, src/test, and target. See why the convention matters and how resource filtering works.

Maven's biggest convention is where files live. Production code goes in one place, tests in another, and everything Maven produces goes in a third. Because every Maven project uses the same standard directory layout, you can open a project you have never seen and know where to look in seconds, and Maven needs no configuration to find your files.

This lesson walks through each folder, explains what happens to its contents during a build, and introduces resource filtering, which lets you put values from the POM into your resource files. The runnable examples are stand-ins: a layout validator and a filtering model, both written in Java.

Three zones

src/main Code and files that ship.
src/test Code and files for tests only.
target Everything Maven generates.

Sources in, build output out.

1 / 2

The full picture

Here is a typical project, with the folders you will meet most often:

TEXT
my-app/
โ”œโ”€โ”€ pom.xml
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ main/
โ”‚   โ”‚   โ”œโ”€โ”€ java/           production Java code
โ”‚   โ”‚   โ”œโ”€โ”€ resources/      production non-Java files
โ”‚   โ”‚   โ””โ”€โ”€ webapp/         web content (WAR projects only)
โ”‚   โ””โ”€โ”€ test/
โ”‚       โ”œโ”€โ”€ java/           test code
โ”‚       โ””โ”€โ”€ resources/      files used only by tests
โ””โ”€โ”€ target/                 build output (created by Maven)
    โ”œโ”€โ”€ classes/
    โ”œโ”€โ”€ test-classes/
    โ”œโ”€โ”€ surefire-reports/
    โ””โ”€โ”€ my-app-1.0.0.jar

Other folders appear in larger projects, such as src/site for documentation, src/it for integration test projects and src/assembly for packaging descriptors. You can ignore them for now.

src/main/java

This is where production Java sources live, in folders that mirror the package names. A class com.acme.shop.Cart is the file src/main/java/com/acme/shop/Cart.java. The compiler plugin compiles everything under this folder into target/classes.

Java itself does not force the folder to match the package for the compiler, but tools and conventions do, and Maven expects it. Keep them in step.

src/main/resources

Everything that is not Java code but must ship with your application goes here: .properties files, XML or YAML configuration, SQL scripts, templates, images. At build time Maven copies these files into target/classes, next to the compiled classes, so they end up in the JAR with the same relative path.

Your code reads them from the classpath, not from the file system. For example, a file src/main/resources/app.properties is read with getResourceAsStream("/app.properties"). This works the same whether you run from an IDE or from the packaged JAR, which is why resources belong here and not in some random folder.

src/test/java and src/test/resources

Test code and test-only files mirror the main layout. They are compiled into target/test-classes and are not packaged into the production JAR. During the test phase, the classpath contains both folders (and the test dependencies), so a test can see your production classes, but production code cannot see test classes. A test resource with the same name as a main resource wins during tests, which is handy for swapping configuration.

Test classes conventionally end in Test (CartTest), which is how the Surefire plugin finds them; see Running Tests with Surefire.

target

target/ is the build output directory. Maven creates it and fills it. Never edit files here, never commit them to version control, and add target/ to your .gitignore. Anything in target can be recreated by running the build, so deleting it is always safe: mvn clean does exactly that.

Folder in target Contents
classes compiled production classes plus copied resources
test-classes compiled tests plus copied test resources
surefire-reports test result files (text and XML)
generated-sources code produced by annotation processors or generators
maven-status bookkeeping for incremental compilation
<name>-<version>.jar the final package

Do not put source code or hand-written files into target. The next mvn clean deletes everything there, including your work.

Why the convention matters

You might wonder why the folder names are so rigid. There are four practical reasons.

  1. No configuration. Maven's plugins have these folders built in, so a project needs no build script at all to compile and test.
  2. Readability. Any Java developer can navigate any Maven project.
  3. Tooling. IDEs, CI servers, code-coverage tools and static analyzers all assume this layout.
  4. Separation. Production, test and generated files cannot get mixed up, because each lives in its own tree.

Maven does let you change the folders with <sourceDirectory> and related elements in the <build> section of the POM. Resist the urge. A custom layout makes every plugin and every teammate harder to work with, and you gain nothing.

Resource filtering

Sometimes a resource file needs a value that Maven already knows, such as the project version. Filtering replaces ${...} placeholders in your resource files with values from the POM at build time. Suppose src/main/resources/app.properties contains:

TEXT
app.name=${project.name}
app.version=${project.version}

You turn filtering on in the POM, for that folder:

XML
<build>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
</build>

After mvn process-resources, the copy in target/classes/app.properties has real values, such as app.version=1.0.0. The original in src is never changed.

Filtering is powerful but needs care. It processes the whole file, so any ${...} that you did not mean for Maven (a shell script, a template using the same syntax) may be replaced or left broken. Binary files, such as images, are corrupted by filtering. The usual rule is to filter only a dedicated folder of text files, and keep binaries in a folder that is not filtered. Properties and profile-based filtering come back in Properties and Build Settings and Profiles and Environments.

Stand-in: a layout validator

A real Maven build does not check your layout; it simply ignores files in the wrong place, which can lead to confusing failures such as "class not found" at run time. The model below plays inspector. Given a list of paths, it reports what Maven would do with each one and warns about common mistakes. It does not touch your disk; the file list is a fixed example.

Java Layout validator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Real Maven would not print any of this; the validator is a teaching device. In practice your IDE highlights these mistakes (red source roots, icons) and the symptoms show up as missing classes or missing resources at run time. Add your own paths to the list to see how the rules treat them.

Stand-in: a filtering model

The second model replaces ${...} placeholders using a map of known values, as Maven's resources plugin does. It also shows the pitfall: a placeholder that has no value is left as it is.

Java Resource filtering model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The real plugin knows far more names (project.*, settings.*, system properties, environment variables as env.*, your own properties), and its delimiters are configurable. The model knows two names and one rule, but it shows why unknown placeholders survive: ${env.USER} stays unchanged here because the model was not given a value for it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to files in src/main/resources during the build?

    The resources plugin copies them into target/classes, keeping their relative paths, so the JAR contains them next to the compiled classes.
  2. 2. Which statement about target/ is correct?

    target/ is generated. mvn clean deletes it, and it should be ignored by version control.
  3. 3. Why are test classes not included in the production JAR?

    src/test compiles into target/test-classes, a separate folder. Only target/classes goes into the JAR.
  4. 4. What is a risk of enabling resource filtering on a folder?

    Filtering rewrites file contents. Keep filtered text resources apart from binaries, and watch for ${...} text that Maven should not touch.

Summary

  • Production code is in src/main/java, production files in src/main/resources, tests in src/test/java and src/test/resources.
  • Maven compiles and copies these into target/classes and target/test-classes; only the first goes into the JAR.
  • target/ is generated output: never edit it, never commit it, and delete it freely with mvn clean.
  • The fixed layout means zero configuration, readable projects and predictable tooling; avoid custom directories.
  • Resource filtering replaces ${...} placeholders when copying; use it on text files only.

Now meet the file that describes it all: The POM File.