Using JUnit5 – Part 4 – Filtering Tests

java, junit5

Published: 2019-07 (July 2019)
Relevant for: JUnit 5.5.0

JUnit5 Blog Series

Part 1 – Introduction
Part 2 – Test Basics
Part 3 – Display Names
Part 4 – Filtering tests

In Part 1 of the blog series, we looked at several annotations used in JUnit5. We covered test methods as well as lifecycle methods.

In Part 2 of the blog series, we covered the basics of testing using JUnit5. We covered test annotations such as marking a test method and asserting. We saw how a test method could be tagged and how assumptions can be used. We finally wrapped up with test execution ordering mechanisms.

In Part 3 of the blog series, we detailed ways in which JUnit test classes and test methods could be customized with readable and meaningful names rather than the standard class and method names.

This post will cover filtering JUnit tests for execution. There are several reasons for running a subset of your comprehensive suite of tests. Some example usages include:

  • You may have unit and integration tests and wish to only run unit tests.
  • You may want a sanity check with the core features alone being tested.
  • You may wish to bypass a few tests to test a specific situation.
  • You may wish to skip a few failing tests, since you know they fail.

Filtration Types

Dynamic filtration

In Part 2 of the blog series, we covered what I term, dynamic filtration. This was done using Assumptions (https://junit.org/junit5/docs/5.5.0/user-guide/#writing-tests-assumptions). Assumptions are conditions that when not met, cause the test to be aborted rather than fail. Assumptions are a great feature to dynamically filter unit tests.

Assumptions are evaluated during execution of the test class, and are embedded within the code block of the test method. Repeating the example we covered in that blog:

class TestWithAssumptions {

    @Test
    void testOnlyOnHost123() {
        assumeTrue("host123".equals(System.getenv("HOSTNAME")));
        // remainder of test
    }

    @Test
    void testOnHost123OrAbortWithMessage() {
        assumeTrue("host123".equals(System.getenv("HOSTNAME")),
            () -> "Aborting test: not on host123");
        // remainder of test
    }

}

Static filtration

In Part 2 of the blog series, we covered the @Tag (https://junit.org/junit5/docs/5.5.0/api/org/junit/jupiter/api/Tag.html) annotation on the unit test method. This annotation can be used to statically label classes and methods. The benefit of such an identification (or label or category) is that a predicate check can be made of such.

Filtering tests based on static labels is what I term static filtration. Since the Tag is an annotation, it is not a part of the code block that executes the unit test. A Tag is a @Repeatable (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/annotation/Repeatable.html) annotation, which implies a class or method can have several tags annotating them.

How Static Filtration works

Code Katas are means to teach a concept, a feature or a functionality. In some Code Katas we deliberately remove logic to make tests fail. The mission for the student is to “fix” these tests. Since this is a learning process, there is a known solution also provided. In order to verify that the solutions are not failing, we can run a build that executes only the solutions (and other tests that are expected to pass). A way of doing that is to leverage Tags.

In this above example, we can thus tag known passing tests as “PASSING” and the kata tests as “TODO”.

See PublicMethodInvocationTest (https://github.com/c-guntur/java-katas/blob/baseline/java-handles/src/test/java/none/cvg/methods/PublicMethodInvocationTest.java).

  • On line 37, the test method is tagged as PASSING. This is a test that is expected to always pass, since it is already solved.
  • On line 63, the other test method is tagged as TODO, since it is what needs to be fixed (and is expected to fail).

We will now look at how we can filter tests both in an IDE (IntelliJ IDEA) as well as during a build process (Apache Maven).

Filtering tests in IDE

When we run all tests in the IDE, screen shot below, ALL tests found are executed, which is not the ideal outcome since several tests marked TODO will fail.

JUNitRunAllTests

Run All Tests (in IntelliJ IDEA)

The Runner configuration can be edited. Select a Test Kind, with value Tags. In this example we used PASSING and TODO as the tags. We are trying to only run the PASSING tests, thus the Tag expression we use is PASSING.

JUNitRunConfiguration

Configure to Run tests with a specific Tag (in IntelliJ IDEA)

When this run configuration is executed, any test tagged as PASSING is included and executed. Tests without this tag (or with the TODO tag, in this example), are filtered out and ignored.

Filtering tests in a build

It is great to setup the IDE on a desktop to work as needed. Repeatability and automation drives using a build tool to do the same. We can also filter tests based on Tags using a build tool such as maven.

JUnit tests are executed in the test phase of the maven lifecycle. A common (and default) plugin to run unit tests is the maven-surefire-plugin. The plugin can be configured to include and exclude groups (generic name corresponding to tags in JUnit5, other unit test frameworks may have other names).

Example: pom.xml (https://github.com/c-guntur/java-katas/blob/baseline/pom.xml#L59-L67)

                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-surefire-plugin</artifactId>
                    <version>2.22.2</version>
                    <configuration>
                        <groups>PASSING</groups>
                        <excludedGroups>TODO</excludedGroups>
                    </configuration>
                </plugin>

In this example, when the maven build is run, any test with a Tag of PASSING is included and any test with a Tag of TODO is excluded.

Summary

In this blog, we saw how we could filter test class and test method names both dynamically using assumptions and more statically using Tags.

Hope this was helpful !

Using JUnit5 – Part 3 – Display Names

java, junit5

Published: 2019-07 (July 2019)
Relevant for: JUnit 5.5.0

JUnit5 Blog Series

Part 1 – Introduction
Part 2 – Test Basics
Part 3 – Display Names
Part 4 – Filtering tests

In Part 1 of the blog series, we looked at several annotations used in JUnit5. We covered test methods as well as lifecycle methods.

In Part 2 of the blog series, we looked at the basics of testing using JUnit5. We covered test annotations such as marking a test method and asserting. We saw how a test method could be tagged and how assumptions can be used. We finally wrapped up with test execution ordering mechanisms.

This post will cover some customization of names for tests. First, a justification of why names should be customized.

Why customize names?

When test class with a few test methods is run with JUnit, the output produced lists the name of the class and a status of execution for each method. The name of the class is used as the top level identifier

JUnitNoDisplayName

As is visible from the image above, a JUnit test was run on a class STestSolution3PeriodsAndDurations. This has four test methods that were tested and they all verify something. All tests passed. However, one really has to peer into the names of all the tests to understand what they executed. For instance, the second test verifies creation of a Period using fluent methods. This was inferred and hopefully most developers name their test methods to convey meaningful intent to anyone who looks at the result.

Let’s compare that to the next image.

JUnitWithDisplayName

Clearly the latter image communicates a lot better about what was tested and what the intent was. The test class is replaced with a meaningful text of what the overall theme for all test methods enclosed was : “Periods (days, months, years) and Durations (hours, minutes, seconds)“. Also individual test methods had proper space-separated words rather than a camel-cased name.

Let’s now look at how we customize the names in JUnit5.

Customizing names in JUnit5

There are primarily two ways in which JUnit5 allows for customizing names.

  1. Using a @DisplayName on a test class or a test method.
  2. Using a @DisplayNameGeneration on the test class which accepts an attribute of a DisplayNameGenerator class.

DisplayName API: https://junit.org/junit5/docs/5.5.0/api/org/junit/jupiter/api/DisplayName.html
DisplayNameGeneration API: https://junit.org/junit5/docs/5.5.0/api/org/junit/jupiter/api/DisplayNameGeneration.html
DisplayNameGenerator API: https://junit.org/junit5/docs/5.5.0/api/org/junit/jupiter/api/DisplayNameGenerator.html

Using a DisplayName annotation

Adding a @DisplayName annotation on a given class or test method can help customize a single class or method name. Let us look at examples.

DisplayName on a test class

Example: @DisplayName (https://github.com/c-guntur/java-katas/blob/baseline/java-datetime/src/solutions/java/none/cvg/datetime/STest3PeriodsAndDurationsTest.java#L35)

/**
* DateTime ranges: Period, Duration tests.
*
* Note: We create a Clock instance in setup() used for some of the tests.
*
* @see Clock
* @see Period
* @see Duration
* @see ChronoUnit
*/
@DisplayNameGeneration(DateTimeKataDisplayNames.class)
@DisplayName("Periods (days, months, years) and Durations (hours, minutes, seconds)")
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
public class STest3PeriodsAndDurationsTest {

DisplayName on a test method

Example: @DisplayName (https://github.com/c-guntur/java-katas/blob/baseline/java-datetime/src/solutions/java/none/cvg/datetime/STest2LocalAndZonedDateTimesTest.java#L304)

    @Test
    @Tag("PASSING")
    @Order(10)
    @DisplayName("verify conversion of UTC date time to Indian Standard Time")
    public void verifyConversionOfUTCDateTimeToIndianStandardTime() {

        ZonedDateTime allDateTimeOhFives =
                ZonedDateTime.of(5, 5, 5, 5, 5, 5, 555, ZoneId.ofOffset("", ZoneOffset.UTC));

        ZoneId gmtPlusOneZoneId = ZoneId.ofOffset("", ZoneOffset.of("+0530"));

        // DONE: Replace the ZonedDateTime.now() below to display the below UTC time in GMT +0530
        //  The ZonedDateTime created in GMT. Fix the calls so a ZonedDateTime
        //  can be created with the offset of GMT +0530. Use an ofInstant from a toInstant.
        //  Check: java.time.ZonedDateTime.ofInstant(java.time.Instant, java.time.ZoneId)
        //  Check: java.time.ZonedDateTime.toInstant()
        ZonedDateTime gmtPlusOneHourTimeForAllFives =
                ZonedDateTime.ofInstant(
                        allDateTimeOhFives.toInstant(),
                        gmtPlusOneZoneId);

        assertEquals(10,
                gmtPlusOneHourTimeForAllFives.getHour(),
                "The hour should be at 10 AM when Zone Offset is GMT +0530");

        assertEquals(35,
                gmtPlusOneHourTimeForAllFives.getMinute(),
                "The minute should be 35 when Zone Offset is GMT +0530");
    }

Using DisplayNameGenerator

Using a generator to modify display names is a two step process.

  1. Create a DisplayNameGenerator class.
  2. Set DisplayNameGeneration annotation on the Test class.

Setting up the DisplayNameGenerator

DisplayNameGenerator is an interface that has three methods with very sensible names that convey theor purpose:

  • generateDisplayNameForClass(Class<?> testClass) – This method can be implemented to provide a meaningful display name to the test class.
  • generateDisplayNameForNestedClass(Class<?> nestedClass) – This method can be implemented to provide a meaningful display name to a nested class in the test class.
  • generateDisplayNameForMethod(Class<?> testClass, Method testMethod) – This method can be implemented to provide a meaningful display name to a test method of a given test class.

Usage

DisplayNameGenerator is an interface, but has two out-of-the-box implementations that can be extended/adapted as needed.

  1. DisplayNameGenerator.Standard – converts camel case to spaced words.
  2. DisplayNameGenerator.ReplaceUnderscores – converts underscores in names as space-separated words.

The example extends the Standard implementation.

Example: DisplayNameGenerator (https://github.com/c-guntur/java-katas/blob/baseline/java-handles/src/main/java/none/cvg/handles/HandlesKataDisplayNames.java)

package none.cvg.handles;

import java.lang.reflect.Method;

import org.junit.jupiter.api.DisplayNameGenerator;

import static java.lang.Character.isDigit;
import static java.lang.Character.isLetterOrDigit;
import static java.lang.Character.isUpperCase;

public class HandlesKataDisplayNames extends DisplayNameGenerator.Standard {
    @Override
    public String generateDisplayNameForClass(Class<?> aClass) {
        return super.generateDisplayNameForClass(aClass);
    }

    @Override
    public String generateDisplayNameForNestedClass(Class<?> aClass) {
        return super.generateDisplayNameForNestedClass(aClass);
    }

    @Override
    public String generateDisplayNameForMethod(Class<?> aClass, Method method) {
        String methodName = method.getName();
        if (methodName.startsWith("reflection")) {
            return "using Reflection";
        }
        if (methodName.startsWith("unsafe")) {
            return "using Unsafe";
        }
        if (methodName.startsWith("methodHandle")) {
            return "using Method Handles";
        }
        if (methodName.startsWith("compareAndSet")) {
            return camelToText(methodName.substring(13));
        }
        if (methodName.startsWith("get")) {
            return camelToText(methodName.substring(3));
        }
        return camelToText(methodName);
    }


    private static String camelToText(String text) {
        StringBuilder builder = new StringBuilder();
        char lastChar = ' ';
        for (char c : text.toCharArray()) {
            char nc = c;

            if (isUpperCase(nc) && !isUpperCase(lastChar)) {
                if (lastChar != ' ' && isLetterOrDigit(lastChar)) {
                    builder.append(" ");
                }
                nc = Character.toLowerCase(c);
            } else if (isDigit(lastChar) && !isDigit(c)) {
                if (lastChar != ' ') {
                    builder.append(" ");
                }
                nc = Character.toLowerCase(c);
            }

            if (lastChar != ' ' || c != ' ') {
                builder.append(nc);
            }
            lastChar = c;
        }
        return builder.toString();
    }
}

Once a DisplayNameGenerator is created, the second step is to associate it with a test class. This requires using the @DisplayNameGeneration annotation on the test class.

Applying a DisplayNameGenerator

An annotation on a test class is required to avail of the generator logic. This is done by adding a @DisplayNameGeneration annotation on the test class.

Example: @DisplayNameGeneration (https://github.com/c-guntur/java-katas/blob/baseline/java-handles/src/solutions/java/none/cvg/constructors/SDefaultConstructorInvocationTest.java#L34)

package none.cvg.constructors;

import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodHandles;
import java.lang.invoke.MethodType;
import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;

import none.cvg.handles.DemoClass;
import none.cvg.handles.HandlesKataDisplayNames;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.DisplayNameGeneration;
import org.junit.jupiter.api.MethodOrderer;
import org.junit.jupiter.api.Order;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestMethodOrder;
import sun.misc.Unsafe;

import static none.cvg.handles.ErrorMessages.REFLECTION_FAILURE;
import static none.cvg.handles.ErrorMessages.TEST_FAILURE;
import static none.cvg.handles.ErrorMessages.UNSAFE_FAILURE;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.fail;

/*
 * DONE:
 *  This test aims at using MethodHandles to invoke a default constructor on a class in order to
 *  create a new instance.
 *  Each solved test shows how this can be achieved with the traditional reflection/unsafe calls.
 *  Each unsolved test provides a few hints that will allow the kata-taker to manually solve
 *  the exercise to achieve the same goal with MethodHandles.
 */
@DisplayNameGeneration(HandlesKataDisplayNames.class)
@DisplayName("Invoke DemoClass()")
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
public class TestSolutionDefaultConstructorInvocation {

Summary

In this blog, we saw how we could customize test class and test method names to produce a more meaningful output. The next blog will cover how we can filter tests based on tags.

Hope this was helpful !

 

Using JUnit5 – Part 2 – Testing Basics

java, junit5

Published: 2019-07 (July 2019)
Relevant for: JUnit 5.5.0

JUnit5 Blog Series

Part 1 – Introduction
Part 2 – Test Basics
Part 3 – Display Names
Part 4 – Filtering tests

In Part 1 of the blog series, we looked at several annotations used in JUnit5. We covered test methods as well as lifecycle methods.

This post will share examples of a JUnit test which has a few of these annotations.

We will use a recently created code kata for the examples.

Testing

Marking a method as a Test

Tests in JUnit5 are annotated with the @Test annotation. Unlike prior versions of JUnit, the JUnit5 @Test annotation does not have any attributes. Prior versions supported extensions via attributes, while JUnit5 fosters a custom annotation based extension (more on this in a future blog).

Example: @Test (https://github.com/c-guntur/java-katas/blob/baseline/java-datetime/src/solutions/java/none/cvg/datetime/STest1InstantAndDateInteropTest.java#L43)

    @Test
    @Tag("PASSING")
    @Order(1)
    public void verifyInstantAndDateHaveSameEpochMilliseconds() {

        // DONE: Replace the Instant.now() with an instant from classicDate.
        //  Use a Date API that converts Date instances into Instant instances.
        //  Check: java.util.Date.toInstant()
        Instant instant = classicDate.toInstant();

        // DONE: Replace the "null" below to get milliseconds from epoch from the Instant
        //  Use an Instant API which converts it into milliseconds
        //  Check: java.time.Instant.toEpochMilli()
        assertEquals(Long.valueOf(classicDate.getTime()),
                instant.toEpochMilli(),
                "Date and Instant milliseconds should be equal");
    }

Assertions

Assertions are how testing is conducted. Several types of assertions exist for testing. Some examples include:

  • assertTrue / assertFalse
  • assertEquals / assertNotEquals / assertSame / assertNotSame
  • assertNull / assertNotNull
  • assertArrayEquals / assertIterableEquals / assertLinesMatch
  • assertThrows / assertNotThrows
  • assertAll
  • assertTimeout / assertTimeoutPreemptively
  • fail

There are several polymorphs for most of the methods listed above. JUnit5 aggregates all such assertions as static methods in a single factory utility aptly named Assertions (https://junit.org/junit5/docs/5.5.0/api/org/junit/jupiter/api/Assertions.html).

Assertions are mostly unary or binary (There are assertions, with other arities, that are less commonly used)

Unary assertions are usually boolean condition evaluators. assertTrue or assertNull are good examples of unary assertions. The expectation in such cases is built into the actual assertion method name. A second optional parameter for unary assertions is a message that is returned in case of an assertion failure and exists to provide more meaningful readable failure details.

Binary assertions typically have an expected value (a known), an actual value (evaluated) and an optional third parameter of message (in case of the expectation not being met). assertEquals and assertSame are good examples of binary assertions.

Typically, unit tests statically import the assertions required for the given tests in a test class. An example of such an assertion is the assertEquals method as shown below.

Example: Assertion (https://github.com/c-guntur/java-katas/blob/baseline/java-datetime/src/solutions/java/none/cvg/datetime/STest1InstantAndDateInteropTest.java#L56)

    @Test
    @Tag("PASSING")
    @Order(1)
    public void verifyInstantAndDateHaveSameEpochMilliseconds() {

        // DONE: Replace the Instant.now() with an instant from classicDate.
        //  Use a Date API that converts Date instances into Instant instances.
        //  Check: java.util.Date.toInstant()
        Instant instant = classicDate.toInstant();

        // DONE: Replace the "null" below to get milliseconds from epoch from the Instant
        //  Use an Instant API which converts it into milliseconds
        //  Check: java.time.Instant.toEpochMilli()
        assertEquals(Long.valueOf(classicDate.getTime()),
                instant.toEpochMilli(),
                "Date and Instant milliseconds should be equal");
    }

See also: Static Import (https://github.com/c-guntur/java-katas/blob/baseline/java-datetime/src/solutions/java/none/cvg/datetime/STest1InstantAndDateInteropTest.java#L18)

import java.text.SimpleDateFormat;
import java.time.Instant;
import java.util.Date;
import java.util.TimeZone;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.DisplayNameGeneration;
import org.junit.jupiter.api.MethodOrderer;
import org.junit.jupiter.api.Order;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestMethodOrder;

import static none.cvg.datetime.LenientAssert.assertAlmostEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

NOTE: Assertion parameter ordering in JUnit 5 is different from the order in prior versions. In my opinion, the current parameter arrangement makes a lot more sense.

Filtering and Categorizing Tests

Tags

Tags are a means to categorize test methods and classes. Tagging also leads to discovery and filtering of tests. Tagging is done by annotating the class or method with an @Tag annotation. More on filtering in another blog of this series.

Example: @Tag (https://github.com/c-guntur/java-katas/blob/baseline/java-datetime/src/solutions/java/none/cvg/datetime/STest1InstantAndDateInteropTest.java#L62)

    @Test
    @Tag("PASSING")
    @Order(1)
    public void verifyInstantAndDateHaveSameEpochMilliseconds() {

        // DONE: Replace the Instant.now() with an instant from classicDate.
        //  Use a Date API that converts Date instances into Instant instances.
        //  Check: java.util.Date.toInstant()
        Instant instant = classicDate.toInstant();

        // DONE: Replace the "null" below to get milliseconds from epoch from the Instant
        //  Use an Instant API which converts it into milliseconds
        //  Check: java.time.Instant.toEpochMilli()
        assertEquals(Long.valueOf(classicDate.getTime()),
                instant.toEpochMilli(),
                "Date and Instant milliseconds should be equal");
    }

Assumptions

Assumptions are conditions that determine if the rest of the test code block should be either evaluated or aborted. Not meeting an assumption will not cause the code block conditioned by it, to fail. It would rather simply abort execution of such a code block. Some assumption methods:

  • assumeTrue / assumeFalse
  • assumeThat

Similar to assertions, assumptions are grouped as static methods, in a factory utility class, Assumptions (https://junit.org/junit5/docs/5.5.0/user-guide/#writing-tests-assumptions).

class TestWithAssumptions {

    @Test
    void testOnlyOnHost123() {
        assumeTrue("host123".equals(System.getenv("HOSTNAME")));
        // remainder of test
    }

    @Test
    void testOnHost123OrAbortWithMessage() {
        assumeTrue("host123".equals(System.getenv("HOSTNAME")),
            () -> "Aborting test: not on host123");
        // remainder of test
    }

}

Typically, unit tests statically import the assumptions required for the given tests in a test class.

There is no current example of an assumption in the code kata.

Ordering Tests

Test execution order

As stated in the previous part of the blog series, I reserve my opinions of ordering the sequence of test executions. It is useful in certain cases, such as code katas. Test ordering requires either one or two steps depending on the type of ordering.

NOTE: If no order is specified for a test class, JUnit 5 looks for instructions from parent class hierarchy and if still none found, will order tests in a deterministic but non-obvious manner.

Instructing JUnit to order tests

An annotation on the test class is needed to instruct JUnit5 to order tests. This annotation is called the @TestMethodOrder. This annotation accepts an attribute of type MethodOrderer. There are three default implementations that exist:

  1. Alphanumeric – uses String::compareTo to order execution of test methods
  2. OrderAnnotation – uses the @Order annotation on each test method to determine order. The Order annotation accepts a int attribute that specifies the ranking.
  3. Random – uses a random order either simply from System.nanoTime() or in combination with a custom seed.

More custom orders can be created by implementing the MethodOrderer interface.

Example: @TestMethodOrder (https://github.com/c-guntur/java-katas/blob/baseline/java-datetime/src/solutions/java/none/cvg/datetime/STest1InstantAndDateInteropTest.java#L31)

/**
 * The tests in this class aim to show interoperability between
 * `java.util.Date` and the newer `java.time.Instant`.
 *
 * @see Instant
 * @see Date
 * @see LenientAssert
 */
@DisplayNameGeneration(DateTimeKataDisplayNames.class)
@DisplayName("Instant And Date Interoperability")
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
public class STest1InstantAndDateInteropTest {

Extra Step (For OrderAnnotation only): Adding an Order via annotations

In addition to the above annotation instructing JUnit to order test methods, an additional annotation is needed if the OrderAnnotation orderer is specified. The @Order annotation accepts an integer that specifies the ascending order of execution.

Example: @Order (https://github.com/c-guntur/java-katas/blob/baseline/java-datetime/src/solutions/java/none/cvg/datetime/STest1InstantAndDateInteropTest.java#L45)

    @Test
    @Tag("PASSING")
    @Order(1)
    public void verifyInstantAndDateHaveSameEpochMilliseconds() {

        // DONE: Replace the Instant.now() with an instant from classicDate.
        //  Use a Date API that converts Date instances into Instant instances.
        //  Check: java.util.Date.toInstant()
        Instant instant = classicDate.toInstant();

        // DONE: Replace the "null" below to get milliseconds from epoch from the Instant
        //  Use an Instant API which converts it into milliseconds
        //  Check: java.time.Instant.toEpochMilli()
        assertEquals(Long.valueOf(classicDate.getTime()),
                instant.toEpochMilli(),
                "Date and Instant milliseconds should be equal");
    }

That’s a wrap of part two of this blog series. The next blog will include customizing tests with DisplayNames and writing a custom DisplayNameGeneration. Happy coding !

Using JUnit5 – Part 1 – An Introduction

java, junit5

Published: 2019-07 (July 2019)
Relevant for: JUnit 5.5.0

JUnit5 Blog Series

Part 1 – Introduction
Part 2 – Test Basics
Part 3 – Display Names
Part 4 – Filtering tests

Code Katas are a great way of teaching programming practices. The effectiveness of a code kata is to “solve” something repeatedly in order to gain a “muscle memory” of sorts on the subject matter.

Nothing stresses repeatability more than unit tests. Code Katas thus, in many cases can be associated with or run via unit tests.

Many of us have been long used to JUnit4 as a formidable unit testing framework. This blog is not going to be a comparison between JUnit4 and JUnit5, but you will notice some differences as italicized text.

Let us explore JUnit5 as it was used for a recent code kata, this is how I learnt using JUnit 5 !

JUnit5 Logo

JUnit5 dependencies

JUnit5 can be added as a single maven dependency:

            <dependency>
                <groupId>org.junit.jupiter</groupId>
                <artifactId>junit-jupiter</artifactId>
                <version>${junit5.version}</version>
            </dependency>

The equivalent gradle dependency can be inferred.

What is JUnit5 and What is Jupiter?

JUnit5 is made of three separate parts:

  1. JUnit5 Platform: Provides a TestEngine and a testing platform for the JVM.
  2. JUnit5 Jupiter: Programming and extension model for JUnit5 tests.
  3. JUnit Legacy: Backward compatibility TestEngine for JUnit 3 and 4.

Read more about this at the JUnit5 User Guide (https://junit.org/junit5/docs/current/user-guide/).

JUnit5 Basics

Base package for JUnit 5 is: org.junit.jupiter. Most unit test annotations are located at: org.junit.jupiter.apipackage (in the junit-jupiter-api module). Methods in JUnit5 Test can be typically grouped into :

  1. Test methods: Methods that are run as unit tests.
  2. Lifecycle methods: Methods that are executed as before or after one or more (or all) test methods.

Basic Annotations

@Test: Identifies a method as a test method. Unlike prior versions, this annotation does not have attributes. #TestMethod

@Disabled: An annotation to ignore running a method marked as @Test. #TestMethod

@BeforeEach: A setup method that is run before execution of each test. #LifecycleMethod

@BeforeAll: A static setup method run once before execution of all tests. #LifecycleMethod

@AfterEach: A teardown method this is run after execution of each test. #LifecycleMethod

@AfterAll: A static teardown method run once after execution of all tests. #LifecycleMethod

Other Annotations

@Tag: A category or grouping annotation. This is very useful specially when filtering which tests should be run via build tools such as maven. Example in another blog in this series.

@DisplayName: A string that can represent the class or method in the JUnit exection results instead of the actual name. Example in another blog in this series.

@DisplayNameGeneration: A class that can generate class and method names based upon conditions. Examples in another blog in this series.

Custom annotations: It is quite simple to create custom annotations and inherit the behavior.

JUnit5 Conditional Control of Test Methods

Operating System Conditions

@EnabledOnOs: Enable a test to run on a specific array of one or more operating systems.

@DisabledOnOs: Disable a test to run on a specific array of one or more operating systems.

Java Runtime Environment Conditions

@EnabledOnJre: Enable a test to run on a specific array of one or more Java Runtime Environments.

@DisabledOnJre: Disable a test to run on a specific array of one or more Java Runtime Environments.

System Property Conditions

@EnabledIfSystemProperty: Enable a test to run if a System Property matches the condition attributes.

@DisabledIfSystemProperty: Disable a test to run if a System Property matches the condition attributes.

Ordering Test method execution

JUnit5 allows for ordering test method execution. This causes mixed feelings for me.

My feelings: Ordering methods may lead to some developers building out dependent tests where the result of one test is needed for the next to run or pass. Tests should be independent. That said, it is an incredibly useful a feature when used in code katas where the run of tests may have to follow a certain sequence. In the past, I used to solve this by naming my test methods with some numeral-inclusive prefix and sort the results alphabetically. With great power, comes great responsibility.

@TestMethodOrder: Test methods can be ordered when the Test class is marked with this annotation.

@Order: Each test method can then include an Order annotation that includes a numeric attribute.

These were some of the basic that we covered. The next blog in this series will show examples of how we use these features.

Devnexus 2019: Reflection and Unsafe alternates

java, java 11

As has been the norm for the past few years, I am very excited about attending Devnexus once again, in 2019. In my humble opinion, Devnexus is one of the best tech. conferences to attend. Devnexus is held in Atlanta, Georgia from March 6th – 8th 2019.

My presentation

I will be presenting on Friday, March 8th 2019, on the topic of Alternates to Reflection and Unsafe usage. This talk is a part presentation (small), part live coding kata session. Bring your laptop to participate in coding along – or – use a QR code scanner/scribbling device of your choice to capture the URL where you can check out the code to try out the coding portion later.

DaVinci

Details

Many Java libraries and frameworks currently use Reflection and Unsafe APIs. With the newer modular Java some of these important tools of our trade may become incompatible and/or may not work as desired. In addition several enterprise applications also rely on Core Reflection, (if not the use of Unsafe APIs).

Session

The essence of the session is to demonstrate the alternates for the current usage patterns for some of the simpler and more common usages of Java Reflection API and the sun.misc.Unsafe among applications, libraries and frameworks. An explanation of the newer Handles API will be followed with code that allows for a comparison between using both styles.

Oh, and spoiler alert: there may be an abridged fairy tale or two introduced during this talk.

Presentation

This presentation is intended for the application developers and is aimed at helping them both understand reflection and the newer alternates. This may further evolve into developers contributing to applications, libraries and frameworks in converting to the newer APIs.

The coding portion of this session is a code kata, that has two different kinds of unit tests. The code contains passing JUnit tests which show how Core Reflection and Usafe APIs were used, and failing tests using new light-weight Method and Var Handle APIs that the attendees can solve-along (or take as homework to work on).

Kata

A coding kata is best described THE Dave Thomas (Author of the The Pragmatic Programmer). Please do read his blog at http://codekata.com/. From Wikipedia:

 

A code kata is an exercise in programming which helps programmers hone their skills through practice and repetition.

How does one go about with this kata?

Steps:

  1. Run the test class(es).
  2. One or more tests will fail with the test failure message.
  3. Fix the failing tests by taking hints from the TODOs.
  4. Repeat above steps until all tests pass.
  5. Rinse and repeat (delete and checkout again, then back to Step 1) to build muscle memory.

Each test class has two types of test methods:

  • Solved test methods show how an invocation/access can be achieved with the traditional calls.
  • Unsolved/failing test methods which provide TODO hints that will allow the kata-taker to manually solve the exercise to achieve the same with MethodHandles/VarHandles.

How to prepare for coding along

This kata is developed as a Java maven project. Ensure that you have:

    1. Apache Maven 3.3.x or above. Tested with Apache Maven 3.5.0.
      Link: https://maven.apache.org/download.cgi

 

    1. JDK 11. Tested with OpenJDK 11
      Link: http://jdk.java.net/11/

 

    1. Your favorite Java IDE. IntelliJ IDEA Ultimate was used to develop this kata.

 

  1. Checkout the code from Github (link will be provided during the session).

Topics Covered

Reflection

Reflection is heavy weight. Reflection has been around in the Java space since almost 1997 (Java 1.1). Thanks to some futuristic changes in Java back in early 2000s, newer, more safe and more lightweight alternates are now available for almost all of the usages of reflection. Alternates to reflection using MethodHandles introduced in Java 7 are described.

The code kata covers constructor invocation and method calls to public, private, package-protected and protected methods. The solved examples show how invocations are performed using the Core Reflection API. The unsolved or failing tests that need to be fixed carry TODOs with hints explaining how to solve them and thus learn the newer MethodHandle API.

sun.misc.Unsafe

Unsafe is, well, unsafe. The sun.misc.Unsafe is a goto for developers (specially library and framework developers). Unsafe API allows for lower level memory modifications of fields and was the “solution” to atomic operations prior to the introduction of Atomic* classes. The Unsafe API also exposed some “dangerous” functionality, which will be covered.

The code kata covers getters, compareAndSet operations using Unsafe. The Kata also makes a distinction of what was supported in sun.misc.Unsafe, but is no longer allowed with the new VarHandle API.

Appendix

Some questions that usually popup during such a session including how the invocation happens, what the limitations are and how it all works. These are included in a more verbose appendix. A PDF copy of the presentation is included with the code. In addition, some of the features of Unsafe that cannot possibly be covered, given both the time limits of the presentation and the arrangement of the kata, are listed out in the appendix.


Take Away

The key take-away for an attendee of this presentation and kata is a solid understanding of the simpler and more common usages of Core Reflection API and Unsafe API alongside the newer Handles API both in similarity and in certain cases, how they differ.

Who knows if your next open source/enterprise contribution is with helping out a library, framework or an enterprise application in converting to the newer APIs ?

Switching between multiple JDKs on a Mac

java, java 10, java 11, java 8, java 9, technology

Blog post date: 2018-May-18
Relevant versions of Java: Java 1.7, 8, 9, 10, 11

We often work with different versions of Java. There are times when we would like to test our application/program against different JDKs. Or … we just love to collect all versions of Java released just to show off.

Either of these would mean some kind of control of the JAVA_HOME and the PATH environment variables.

MultiDuke

Many developers have successfully overcome this with innovative scripts to quickly switch Java versions. I am one such developer and below is an explanation of my setup.

Current installations of JDK on my Mac:

  • JDK 1.7.0_80
  • JDK 1.8.0_172
  • JDK 9.0.4
  • JDK 10.0.1
  • JDK 11-ea+14

How does one determine the current installations of JDK?

On your Mac terminal run the command:

/usr/libexec/java_home -verbose

Sample output:

Matching Java Virtual Machines (5):
11, x86_64: "OpenJDK 11-ea" /Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home
10.0.1, x86_64: "OpenJDK 10.0.1" /Library/Java/JavaVirtualMachines/jdk-10.0.1.jdk/Contents/Home
9.0.4, x86_64: "OpenJDK 9.0.4" /Library/Java/JavaVirtualMachines/jdk-9.0.4.jdk/Contents/Home
1.8.0_172, x86_64: "Java SE 8" /Library/Java/JavaVirtualMachines/jdk1.8.0_172.jdk/Contents/Home
1.7.0_80, x86_64: "Java SE 7" /Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home

Simple ! Quite easy to determine the current JDKs available.

How can I switch Java versions easily?

Aliases. That’s it. If you know this, you can skip the remaining part of this blog. What is really cool is how a single JVM exec command can be used to switch JDK versions.

Sharing an excerpt from a .bash_profile:


alias jdk11="export JAVA_HOME=`/usr/libexec/java_home -v 11` && export PATH=$JAVA_HOME/bin:$PATH; java -version"
alias jdk10="export JAVA_HOME=`/usr/libexec/java_home -v 10` && export PATH=$JAVA_HOME/bin:$PATH; java -version"
alias jdk9="export JAVA_HOME=`/usr/libexec/java_home -v 9` && export PATH=$JAVA_HOME/bin:$PATH; java -version"
alias jdk8="export JAVA_HOME=`/usr/libexec/java_home -v 1.8` && export PATH=$JAVA_HOME/bin:$PATH; java -version"
alias jdk7="export JAVA_HOME=`/usr/libexec/java_home -v 1.7` && export PATH=$JAVA_HOME/bin:$PATH; java -version"

Note how the Java versioning from 9 onwards is a full digit? The same applies with the default directory names of the installed JDKs. This was a deliberate change toshake off the 1.x naming style of prior versions of Java.

JDK switching output

A picture would do this more justice.
Switching JDKs at Terminal

Maintenance of JDKs

Needs Admin rights on the Mac !

Keeping the JDK versions up-to-date is in everyone’s best interest, both for the new features as well as any security patches. A few steps that can help with maintaining:

    1. Extract the latest build/patch of the JDK into the directory: /Library/Java/JavaVirtualMachines.
      • If an installer was used, most likely the directories are created.
      • If a tarball was extracted from, make sure to move the extracted directory under the parent mentioned above.

 

    1. Post-installation, open a new terminal shell (current shell will not pick up the latest patch of an existing version of the JDK).
      • Add the appropriate alias, if this is a new version of Java
      • If existing version being patched, then no further action is needed.

 

    1. Type in the appropriate alias and verify that the build/patch is what shows.

 

  1. Once verified, the options for removing the prior patch present themselves:
    • delete older build/patch since it is no longer useful to reclaim space.
    • retain older build/patch, for other usage. It is possible to manually switch to this build/patch:
      • export JAVA_HOME=/Library/Java/JavaVirtualMachines/
      • export PATH=$JAVA_HOME/bin:$PATH

That’s a wrap on Switching JDKs on a Mac. Hope this post was helpful.

Java 9 Features – Changes to Optional

java, java 9, technology

Duke-Java9

In Java 8, a new class named Optional was introduced. Or rather in the word-style of Douglas Adams, “in the beginning null was created. This made a lot of people angry and was widely regarded as a bad move“. Optional was introduced to alleviate some of that anger.

Optional relieved developers of the grief of null checks and the “fun” of a NullPointerException popping up when failing to null check.

In Java 8, the Optional already had very useful methods:

  • of – Wrap the non-null value into an Optional.
  • ofNullable – Wrap and return an Optional of the current value, if current value is null, return Optional.empty()
  • isPresent – Checks and returns a boolean indicating the presence of a non-null value in the Optional.
  • ifPresent – Checks and invokes the specified Consumer instance upon the presence of a non-null value in the Optional.
  • get – Fetch the value in the Optional if it is not null, else throw a NoSuchElementException
  • orElse – Fetch the value in the Optional if it is not null, else return the other element passed in.
  • orElseGet – Fetch the value in the Optional if it is not null, else return invoke the other Supplier to fetch an element instead.
  • orElseThrow – Fetch the value in the Optional if it is not null, else throw the passed in Exception.
  • filter – If the value exists, test the filtering Predicate on it and if true return result wrapped in an Optional, else return Optional.empty().
  • map – If the value exists, apply the mapping Function to it and return any non-null result wrapped in an Optional, else return Optional.empty().
  • flatMap – If the value exists, apply the Optional-bearing mapping Function to it and return any non-null result wrapped in an Optional, else return Optional.empty().

Java 9 changes

  • ifPresentOrElse – Checks and returns a boolean indicating the presence of a non-null value in the Optional, or else, invokes the Runnable action.
  • or – Wrap and return an Optional of the current value if not null; if current value is null, return Optional by invoking the specified Supplier
  • stream – Returns a sequential stream containing only the value, if the value is non-null.

Optional::ifPresentOrElse

Consider a situation where the code is to either run a Consumer if the value exists or else run a different action. This is not possible in the Java 8 Optional behavior. Optional in Java 8 provides an orElse or an orElseGet method, both of which actually return an unwrapped value, rather than act as an execution block.

Source at: https://github.com/c-guntur/java9-examples/blob/master/src/test/java/samples/java9/optional/OptionalIfPresentOrElse.java

Pre-Java 8 :


if(preference != null) { 
    callPresenceAction();
} else {
    callAbsenceAction();
}

In Java 8 :


if(optionalPreference.isPresent()) { 
    callPresenceAction();
} else {
    callAbsenceAction();
}

or


optionalPreference.ifPresent(callPresenceConsumer());
// orElseGet returns a non-optional value
// it cannot be used to simply execute an action.
Preference p = optionalPreference.orElseGet(callAbsenceSupplier());

In Java 9 :


optionalPreference
        .ifPresentOrElse(presenceAction,absenceAction);

Optional::or

Per the Java 8 API, both the orElse and the orElseGet do not return an Optional, rather return the unwrapped value. It is possible that such a value is null. The or method is introduced as a means to execute a supplier on absence of an unwrapped value in the container, and returns an Optional, rather than the unwrapped value.

Source at: https://github.com/c-guntur/java9-examples/blob/master/src/test/java/samples/java9/optional/OptionalOr.java

Pre-Java 8 :


Preference preference = findPreference(name); 
if(preference == null) {
    preference = createPreference(name, description);
}
// preference can still be null !!!

In Java 8 :


Preference preference = 
        findOptionalPreference(name)
            .orElseGet(getPreferenceSupplier(name, description));
// preference can still be null !!!

In Java 9 :


Optional optionalPreference = 
        findOptionalPreference(name)
            .or(getOptionalPreferenceSupplier(name, description));
// optional preference, so, protected from being null !!!

Optional::stream

Given a situation where a stream or collection of Optionals exist, and we need to extract values from each, if they contain non-null values. Optional::stream returns a stream with a single non-null value if the Optional has a non-null value, or returns an empty stream otherwise.

Source at: https://github.com/c-guntur/java9-examples/blob/master/src/test/java/samples/java9/optional/OptionalStream.java

Pre-Java 8 :


List preferences = new ArrayList();
for (String preferenceName : PREFERENCE_NAMES) {
    Preference aPreference = findPreference(preferenceName);
    if (aPreference != null) {
        preferences.add(aPreference);
    }
}

In Java 8 :


List preferences =
        PREFERENCE_NAMES.stream()
                .map(preferenceName -> findOptionalPreference(preferenceName))
                .filter(Optional::isPresent)
                .map(Optional::get)
                .collect(toList());

In Java 9 :


List preferences =
        PREFERENCE_NAMES.stream()
                .map(preferenceName -> findOptionalPreference(preferenceName))
                .flatMap(Optional::stream)
                .collect(toList());

That’s a wrap on the Optional changes in Java 9. Hope this post was helpful.

Java 9 Features – Private Interface Methods

java, java 9, technology

Duke-Java9

A blog on Java 9 changes for interfaces.

Evolution of interfaces in Java:

Until Java 7, all versions of Java maintained the same set of features for interfaces. Interfaces can

Interfaces contained method signatures and were useful for storing public constants. Since then, constants have remained a staple of the interface. Recent changes have been more focused on methods.

Java 7

  • abstract methods – Method signatures as contracts that had to be implemented by the class that implemented the interface.

Java 8

  • default methods – Methods with an implementation in the interface, providing an option to the implementing class to override.

    This change allowed for extension and growth of existing APIs without major refactoring and without harming backward-compatibility. Best example of this is the Java 8 collection framework that introduced new features on the root interfaces without having to make significant changes to any of the implementations.

    See http://docs.oracle.com/javase/8/docs/api/java/util/List.html for sort(...) or spliterator() or replaceAll(...).

  • static methods – Methods with the static modifier with an implementation, which thus belong to the interface.

    These methods cannot be overwritten in implementing classes. Adding static methods allows the interface to control some behavior without allowing for an implementation to alter such behavior.

    See http://docs.oracle.com/javase/8/docs/api/java/util/Map.Entry.html for comparingByKey() or comparingByValue().

Java 9

  • private methods – Methods with implementation in the interface that remain private to the interface alone.

    These methods are useful from an encapsulation perspective to hold some logic that the implementations should not override.

    While there is no concrete example in the JDK API that I could immediately find, there are several existing interfaces which have workarounds for encapsulating private methods via private inner classes. Such workarounds can be circumvented with private methods.

Java support in interfaces

  Java 7 Java 8 Java 9
constants
abstract methods
default methods
public static methods
private methods
private static methods

Modifier combinations in Java 9

Combination Comment
[public] (naturally abstract) supported
[public] default supported
[public] static supported
private supported
private static supported
private abstract compile-time error
private default compile-time error

Java 8 Date Time API – A Kata

java, java 8, technology

Duke-Calendar

This post is an extract of a Code Kata presentation I had hosted back in November 2015. Java 8 Date Time API was relatively new to many of the attendees.

This Kata-based style of teaching includes sharing a set of failing / non-functional JUnit tests with TODO comments indicating actions that need to be taken to resolve/pass the JUnit tests. Solving the JUnit tests repeatedly helps developers gain muscle-memory into using the feature (similar to the karate kata).

Link to the code kata is on Github, located at the bottom of the post.

Background: Why a new API

First, some background on why there was a need to create a new API.

Issues with java.util.Date

java.util.Date:

  • is mutable-only – Date instances are not immutable.
  • has concurrency problems – Date instances are not thread-safe.
  • has incorrect naming – Date is not a “date” but a “timestamp”.
  • lacks convention – Days start with 1, months with 0 and years with 1900.
  • lacks fluency – Cannot create durations (a quarter, 5 minutes) OR combos(year+month, date without seconds) etc.

Additional observations about the pre-Java 8 Date API

  • System.currentTimeInMillis() is not accurate and can return same value for multiple sequential calls.
  • java.util.Date vs. java.sql.Date – SQL flavor is only a DATE with no time.
  • java.sql.Timestamp – SQL flavor replicating java.util.Date but additionally storing nanoseconds.

Issues with java.util.Calendar

java.util.Calendar:

  • lacks clarity – Mix of dates and times.
  • has confusing timezone support – Not very easy to switch timezones, offsets etc.
  • has severe formatting hurdlesSimpleDateFormat and Calendar do not interoperate well.
  • presents extension hardships – New calendar systems are created by extending Calendar (therefore all it’s problems).

“Calendar is the Ravenous Bugblatter Beast of Traal for Date APIs” – Chandra Guntur (circa 2000).

What was proposed to fix this?

JSR-310: Date and Time API
Excerpts from JSR-310 (https://jcp.org/en/jsr/detail?id=310)

  • “The main goal is to build upon the lessons learned from the first two APIs (Date and Calendar) in Java SE, providing a more advanced and comprehensive model for date and time manipulation.”
  • “The new API will be targeted at all applications needing a data model for dates and times. This model will go beyond classes to replace Date and Calendar, to include representations of date without time, time without date, durations and intervals.
  • “The new API will also tackle related date and time issues. These include formatting and parsing, taking into account the ISO8601 standard and its implementations, such as XML.”
  • “The final goal of the new API is to be simple to use. The API will need to contain some powerful features, but these must not be allowed to obscure the standard use cases. Part of being easy to use includes interaction with the existing Date and Calendar classes …”

Origins of the JSR-310

Java 8 Date Time API

The Java classes in lavender below are all linked to the JDK 8 API. Please feel free to click.

Date Time Classes

Dates and Times: Simple Date and Time ‘containers’

  • Instant stores a numeric timestamp from Java epoch, + nanoseconds.
  • LocalDate stores a date without a time portion (calendar date).
  • LocalTime stores a time without a date portion (wall clock).
  • LocalDateTime stores a date and time (LocalDate + Local Time).
  • ZonedDateTime stores a date and time with a time-zone.
  • OffsetTime stores a time and offset from UTC without a date.
  • OffsetDateTime stores a date with time and offset from UTC.

Ranges and Partials: Spans and ranges of temporality

  • Duration models time in nanoseconds for time intervals. (e.g. 5 mins)
  • Period models amount of time in years, months and/or days. (e.g. 2 Days)
  • Month stores a month on its own. (e.g. MARCH)
  • MonthDay stores a month and day without a year or time (e.g. date of birth)
  • Year stores a year on its own. (e.g. 2015)
  • YearMonth stores a year and month without a day or time. (e.g. credit card expiry)
  • DayOfWeek stores a day-of-week on its own. (e.g. WEDNESDAY)

Chronology: A calendar system to organize and identify dates

  • Chronology is a factory to create or fetch pre-built calendar systems.
    Default is IsoChronology (e.g. ThaiBuddhistChronology).
  • ChronoLocalDate stores a date without a time in an arbitrary chronology.
  • ChronoLocalDateTime stores a date and time in an arbitrary chronology.
  • ChronoZonedDateTime stores a date, time and timezone in an arbitrary chronology.
  • ChronoPeriod models a span on days/time for use in an arbitrary chronology.
  • Era stores a timeline [typically two per Chronology, but some have more eras].

Date Time Common API – Reference Table

Date and Time

Type Y M D H m S(n) Z ZId toString
Instant 1999-01-12T12:00:00.747Z
LocalDate 1999-01-12
LocalTime 12:00:00.747
LocalDateTime 1999-01-12T12:00:00.747
ZonedDateTime 1999-01-12T12:00:00.747-05:00 [America/New_York]
OffsetTime 12:00:00.747-05:00
OffsetDateTime 1999-01-12T12:00:00.747-05:00

Ranges

Type Y M D H m S(n) Z ZId toString
Duration P22H
Period P15D

Partials

Type Y M D H m S(n) Z ZId toString
Month * JANUARY
MonthDay -01-12
Year 1999
YearMonth 1999-01
DayOfWeek * TUESDAY

Fluency and Symmetry in the new Date Time API

The Java 8 Date Time API introduces a certain symmetry in operations that make for a pleasant developer experience. Below is a list of prefixes for methods across the API that perform in a similar pattern where encountered.

  • of {static factory method prefix} – Factory method to obtain an instance with provided parameters – validates and builds with no conversion.example usage: LocalDate.of(...) or Instant.ofEpochSecond(...)
  • from {static factory method prefix} – Factory method to obtain an instance with provided parameters – validates, converts and builds.example usage: LocalDateTime.from(...) or OffsetTime.from(...)
  • parse {static factory method prefix} – Factory method to obtain an instance with provided CharSequence parameters, by parsing the content.example usage: LocalDate.parse(...) or OffsetDateTime.parse(...)
  • format {instance method prefix} – Formats the instance with provided formatter.example usage: localDate.format(formatter)
  • get {instance method prefix} – Return part of the state of the target temporal object.example usage: localDate.getDayOfWeek()
  • is {instance method prefix} – Queries a part of the state of the target temporal objectexample usage: localTime.isAfter(...)
  • with {instance method prefix} – Returns a copy of the immutable temporal object with a portion altered. Alternate for a set operation.example usage: offsetTime.withHour(...)
  • plus {instance method prefix} – Return a copy of the temporal object with an added time.example usage: localDate.plusWeeks(...)
  • minus {instance method prefix} – Return a copy of the temporal object with subtracted time.example usage: localTime.minusSeconds(...)
  • to {instance method prefix} – Convert the temporal object into a new temporal object of another type.example usage: localDateTime.toLocalDate(...)
  • at {instance method prefix} – Combine the temporal object into a new temporal object with supplied parameters.example usage: localDate.atTime(...)

KATA TIME !!!

The Code for the Kata is located at: https://github.com/c-guntur/javasig-datetime

Your mission, should you choose to accept it, is to:

  1. setup the kata using your favorite IDE
  2. launch each JUnit test (Exercise1Test through Exercise5Test) and fix the tests, so all execute as instructed in the TODO above any commented lines.
  3. repeat as often as necessary to build muscle memory of using the awesome Date Time API

There are solutions, but looking at solutions may limit your learning different ways of solving the same problem.

Link to solutions: https://github.com/c-guntur/javasig-datetime-solutions

I hope you found this post fun!

Happy coding!