This document describes how to implement a Concept Exercise for the Java track.

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read the following documents:

• The features of v3.
• Rationale for v3.
• What are concept exercise and how they are structured?

Please also watch the following video:

• The Anatomy of a Concept Exercise.

As this document is generic, the following placeholders are used:

• <slug>: the name of the exercise in snake_case (e.g. calculator-conundrum).
• <concepts>: the Concepts the exercise is about (e.g. loops),
• <concept-1>: a single Concept slug,
• <prerequisite-n>: a single Concept slug,
• <uuid>: a new v4 UUID (random!)
• <first-and-last-name>: your first and last name (e.g. John Doe)
• <git-email>: the email address you use for git (e.g. johndoe@email.com)

Before implementing the exercise, please make sure you have a good understanding of what the exercise should be teaching (and what not). This information can be found in the exercise's GitHub issue. Having done this, please read the Java Concept exercises introduction. If you have come up with something completely new, create a new issue first so we can discuss the Concept Exercise.

To implement a Concept Exercise, the following files must be added:

languages
└── java
    ├── concepts
    |   └── <concept-1>
    |       ├── about.md
    |       └── links.json
    └── exercises
        └── concept
            └── <slug>
                |── .docs
                |   |── instructions.md
                |   |── introduction.md
                |   |── hints.md
                |   └── source.md (required if there are third-party sources)
                |── .gitignore
                |── .meta
                |   |── design.md
                |   |── config.json
                |   └── src
                |       └── reference
                |           └── java
                |               └── <slug>.java
                |── build.gradle
                └── src
                    |── main
                    |   └── java
                    |       └── <slug>.java
                    └── test
                        └── java
                            └── <slug>Test.java

The configuration files may be copied from another exercise. We aim to keep these in sync. We suggest to use:

• languages/java/exercises/concept/basics/build.gradle

Now create the following three files:

• src/main/java/<slug>.java. the stub implementation file, which is the starting point for students to work on the exercise.
• src/test/java/<slug>Test.java: the test suite, please use assertj to describe assertions instead of those offered by JUnit.
• .meta/src/reference/java/<slug>.java: an exemplar implementation that passes all the tests.

Append to languages/java/exercises/settings.gradle the following line: concept:<slug>

Before submitting your solution, be sure it works following these two steps from the folder of your exercise:

1. Test the solution running gradle test
2. Validate the coding style running gradle check

How to create the files common to all tracks is described in the how to implement a concept exercise document.

• Add the exercise to the list of implemented exercises.

Some exercises could benefit from having an exercise-specific analyzer. If so, specify what analysis rules should be applied to this exercise and why.

Skip this step if you're not sure what to do.

Some exercises could benefit from having an custom representation as generated by the Java representer. If so, specify what changes to the representation should be applied and why.

Skip this step if you're not sure what to do.

When implementing an exercise, it can be very useful to look at already implemented Java exercises like the strings or numbers exercises. You can also check the exercise's general concepts documents to see if other languages have already implemented an exercise for that Concept.

If you have any questions regarding implementing the exercise, please post them as comments in the exercise's GitHub issue.