Introduce `Converter` in `junit-platform-commons` #4219

scordio · 2024-12-23T01:33:01Z

Overview

Resolves Introduce generic ConversionService SPI #853
Relates to Implicit conversion from integral numbers to byte array #2702
Relates to Support binary literal format for String to Number conversion #3605
Relates to Make ConvertWith applicable to a larger scope #4514

I hereby agree to the terms of the JUnit Contributor License Agreement.

Definition of Done

There are no TODOs left in the code
Method preconditions are checked and documented in the method's Javadoc
Coding conventions (e.g. for logging) have been followed
Change is covered by automated tests including corner cases, errors, and exception handling
Public API has Javadoc and @API annotations
Change is documented in the User Guide and Release Notes

scordio · 2024-12-23T01:44:39Z

There is plenty of work to do 🙃

The current highlights:

New ConversionService interface, with ClassLoader param instead of ConversionContext (I will come back to it)
New TypedConversionService base class
The implementation of the existing ConversionSupport.convert(String, Class, ClassLoader) is now part of the new DefaultConversionService
A test setup to demonstrate how to solve Locale argument conversion not setting language and country properly #3141 (I'll shape it better as an integration test)

Any feedback would be highly appreciated!

junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/ArgumentConverter.java

marcphilipp · 2025-01-02T10:11:46Z

Thanks for the draft! 👍

The tests are failing due to:

org.junit.platform.commons.support.conversion.ConversionService: module org.junit.platform.commons does not declare uses

That's because junit-platform-commons/src/module/org.junit.platform.commons/module-info.java is missing

uses org.junit.platform.commons.support.conversion.ConversionService;

marcphilipp

Looks very promising! 👍

...m-commons/src/main/java/org/junit/platform/commons/support/conversion/ConversionSupport.java

...ns/src/main/java/org/junit/platform/commons/support/conversion/DefaultConversionService.java

marcphilipp · 2025-01-02T10:23:55Z

jupiter-tests/src/test/java/org/junit/jupiter/params/converter/LocaleConversionService.java

+
+import org.junit.platform.commons.support.conversion.TypedConversionService;
+
+// FIXME delete


This would make a good test case, though. We have existing tests that register services for tests using an extra class loader:

junit5/platform-tests/src/test/java/org/junit/platform/launcher/core/LauncherFactoryTests.java

Lines 353 to 366 in 16c6f72

private static void withTestServices(Runnable runnable) {

var current = Thread.currentThread().getContextClassLoader();

var url = LauncherFactoryTests.class.getClassLoader().getResource("testservices/");

try (var classLoader = new URLClassLoader(new URL[] { url }, current)) {

Thread.currentThread().setContextClassLoader(classLoader);

runnable.run();

}

catch (IOException e) {

throw new UncheckedIOException(e);

}

finally {

Thread.currentThread().setContextClassLoader(current);

}

}

We could generalize and move that method to a test utility class (e.g. in junit-jupiter-api/src/testFixtures) so it can be reused here.

Another possible integration test could be inspired by #3605.

We could generalize and move that method to a test utility class (e.g. in junit-jupiter-api/src/testFixtures) so it can be reused here.

@marcphilipp fine if I do it in a separate PR? Mostly to keep the size of this one under control 🙃

Raised #4544.

marcphilipp · 2025-01-02T10:25:22Z

That's because junit-platform-commons/src/module/org.junit.platform.commons/module-info.java is missing
uses org.junit.platform.commons.support.conversion.ConversionService;

When you add that, you'll also have to add it to platform-tooling-support-tests/projects/jar-describe-module/junit-platform-commons.expected.txt to adjust the integration test.

scordio · 2025-01-15T08:53:35Z

I've been lagging behind with this one but I should be able to spend time on it in the upcoming weekend.

...m-commons/src/main/java/org/junit/platform/commons/support/conversion/ConversionSupport.java

...-jupiter-params/src/main/java/org/junit/jupiter/params/converter/TypedArgumentConverter.java

scordio · 2025-04-21T10:29:40Z

Would you like to include this in 5.13 too? I should have enough time in the upcoming days to finalize it.

scordio · 2025-05-05T13:56:16Z

I've hidden my last comment as it's mostly outdated after @sbrannen's one, and

supporting generics and something like a TypeDescriptor parameter object would be a good step in that direction.

If you'd like to go this way, I'm happy to adjust my work in this direction!

marcphilipp · 2025-05-05T15:13:33Z

I agree with @sbrannen. Let's go with the generic version and the parameter object.

scordio · 2025-05-10T08:40:01Z

I think TypeDescriptor shouldn't be specific to the conversion feature, so I plan to define it in org.junit.platform.commons.

Any better ideas?

EDIT: or maybe it is? 🤔 looking at how the Spring Framework does it.

sbrannen · 2025-05-10T08:58:28Z

I think TypeDescriptor shouldn't be specific to the conversion feature, so I plan to define it in org.junit.platform.commons.

I think it's OK for TypeDescriptor to reside in org.junit.platform.commons.support.conversion.

scordio · 2025-05-10T09:25:52Z

@sbrannen I'm still trying to get a proper background before jumping on the actual changes, so here's a dumb question 🙂

Specifically about parameterized types, is the ResolvableType abstraction closer to what we would need, from your perspective? Or maybe you imagine that together with TypeDescriptor?

marcphilipp · 2025-05-10T12:47:36Z

To start with, I had thought a relatively simple interface should suffice for TypeDescriptor.

interface TypeDescriptor {
	Class<?> getType();
}

@sbrannen WDYT?

scordio · 2025-05-10T13:17:47Z

My suggestion is not to close the door for Type getType() so maybe Class<?> getRawClass() or similar?

Mostly to be ready for cases where TypeDescriptor might wrap a ParameterizedType.

marcphilipp · 2025-05-10T13:24:37Z

We could do what Java did (e.g. for Method.getReturnType()) and have Class<?> getType() now and potentially Type getGenericType() later.

scordio · 2025-05-11T12:41:35Z

To start with, I had thought a relatively simple interface should suffice for TypeDescriptor.
interface TypeDescriptor {
	Class<?> getType();
}

So far, I understood TypeDescriptor should replace the Class parameter in ConversionSupport.convert (and, consequently, in the Converter methods), so:

public static <T> T convert(Object source, Class<T> targetType, ClassLoader classLoader)

should become:

public static <T> T convert(Object source, TypeDescriptor targetType, ClassLoader classLoader)

Therefore, I planned to define TypeDescriptor as a public class, with a private constructor and factory methods like forField(Field) and forParameter(Parameter) that ConversionSupport users could rely on (including DefaultArgumentConverter).

@marcphilipp did you have something else in mind?

scordio · 2025-05-11T13:06:54Z

After renaming to Converter, I realized StringToObjectConverter is pretty much a similar abstraction.

I propose to refactor the StringToObjectConverter hierarchy and rewrite all classes as Converter implementations (still with package-private visibility and used by DefaultConverter only).

WDYT?

sbrannen · 2025-05-11T15:13:33Z

I propose to refactor the StringToObjectConverter hierarchy and rewrite all classes as Converter implementations (still with package-private visibility and used by DefaultConverter only).

WDYT?

That's pretty much the vision I had all along: to have single abstraction/API.

So, yes, that sounds good to me. 👍

Though... the devil is in details. 😉

scordio · 2025-05-11T17:08:52Z

...form-commons/src/main/java/org/junit/platform/commons/support/conversion/TypeDescriptor.java

+	public Class<?> getType() {
+		return type;
+	}


For now, most of the code relies on getType(), but I plan to check if dedicated APIs could better encapsulate some use cases (similar to getWrapperType or isPrimitive).

scordio · 2025-05-11T17:13:28Z

...m-commons/src/main/java/org/junit/platform/commons/support/conversion/ConversionSupport.java

-			}
-			return null;
-		}
+		return convert(source, TypeDescriptor.forType(targetType), getClassLoader(classLoader));


I wonder if the deprecated convert should delegate to the other convert method or should invoke DefaultConverter directly, skipping the new service loader logic. For now, I went with the former.

...-platform-commons/src/main/java/org/junit/platform/commons/support/conversion/Converter.java

scordio · 2025-05-11T17:22:00Z

...form-commons/src/main/java/org/junit/platform/commons/support/conversion/TypedConverter.java

+	 * type is a reference type
+	 * @throws ConversionException if an error occurs during the conversion
+	 */
+	protected abstract T convert(S source) throws ConversionException;


Should this carry the target TypeDescriptor too?

Suggested change

protected abstract T convert(S source) throws ConversionException;

protected abstract T convert(S source, TypeDescriptor targetType) throws ConversionException;

Yes, I think so as well as sourceType and classLoader.

scordio · 2025-05-11T17:23:29Z

...ons/src/main/java/org/junit/platform/commons/support/conversion/StringToObjectConverter.java

-	 * <p>This method will only be invoked in {@link #canConvertTo(Class)}
-	 * returned {@code true} for the same target type.
-	 */
-	Object convert(String source, Class<?> targetType) throws Exception;


Being an internal API, I deleted this convert(String, Class<?>) variant to reduce complexity. The downside is that the ClassLoader parameter is mostly unused in the subclasses.

marcphilipp · 2025-05-12T07:04:33Z

...-platform-commons/src/main/java/org/junit/platform/commons/support/conversion/Converter.java

+ * @see TypedConverter
+ */
+@API(status = EXPERIMENTAL, since = "1.13")
+public interface Converter {


Didn't we decide to make this generic as in Converter<S, T>?

I guess for that to make sense, we'd have to parameterize TypeDescriptor as well.

@scordio @sbrannen WDYT?

I had the same in mind but wasn't entirely confident about this direction yesterday, especially before refactoring StringToObjectConversion.

But now the refactoring is done so I can sketch it and see what happens 🙂

scordio · 2025-05-16T06:21:53Z

...form-commons/src/main/java/org/junit/platform/commons/support/conversion/TypeDescriptor.java

+	public static TypeDescriptor forClass(Class<?> clazz) {
+		return new TypeDescriptor(clazz);
+	}
+
+	public static TypeDescriptor forInstance(Object instance) {
+		return new TypeDescriptor(instance.getClass());
+	}
+
+	public static TypeDescriptor forField(Field field) {
+		return new TypeDescriptor(field.getType());
+	}
+
+	public static TypeDescriptor forParameter(Parameter parameter) {
+		return new TypeDescriptor(parameter.getType());
+	}


General null handling is currently missing

scordio · 2025-05-16T17:06:41Z

...form-commons/src/main/java/org/junit/platform/commons/support/conversion/TypeDescriptor.java

+	@Override
+	public boolean equals(Object o) {
+		if (this == o) {
+			return true;
+		}
+		if (o == null || getClass() != o.getClass()) {
+			return false;
+		}
+		TypeDescriptor that = (TypeDescriptor) o;
+		return this.type.equals(that.type);
+	}
+
+	@Override
+	public int hashCode() {
+		return this.type.hashCode();
+	}


I noticed EqualsAndHashCodeAssertions under junit-jupiter-api to test equals/hashCode. It seems I can use the same in junit-platform-commons.

Out of curiosity, was EqualsVerifier ever considered for such tests?

I noticed EqualsAndHashCodeAssertions under junit-jupiter-api to test equals/hashCode. It seems I can use the same in junit-platform-commons.

👍

Out of curiosity, was EqualsVerifier ever considered for such tests?

I don't think it was discussed but it might be a good addition or even replacement but probably in a separate PR.

scordio force-pushed the conversion-service branch from c31ca83 to b19cba8 Compare December 23, 2024 01:49

scordio mentioned this pull request Dec 23, 2024

Add Locale conversion format configuration property #3410

Closed

6 tasks

scordio force-pushed the conversion-service branch from b19cba8 to a7a8aa3 Compare December 23, 2024 02:23

scordio force-pushed the conversion-service branch 3 times, most recently from 3304ad5 to c886b7a Compare December 31, 2024 11:26

scordio commented Dec 31, 2024

View reviewed changes

junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/ArgumentConverter.java Outdated Show resolved Hide resolved

scordio force-pushed the conversion-service branch from c886b7a to 7ea91b8 Compare December 31, 2024 12:17

marcphilipp reviewed Jan 2, 2025

View reviewed changes

scordio force-pushed the conversion-service branch 2 times, most recently from 2e17c2b to 0c2faa7 Compare January 2, 2025 16:35

scordio force-pushed the conversion-service branch from 0c2faa7 to 098c972 Compare January 26, 2025 11:41

scordio force-pushed the conversion-service branch from 098c972 to 8ed6eb6 Compare February 9, 2025 08:46

scordio commented Feb 9, 2025

View reviewed changes

...m-commons/src/main/java/org/junit/platform/commons/support/conversion/ConversionSupport.java Show resolved Hide resolved

scordio mentioned this pull request Feb 9, 2025

Move string-based argument conversion tests to platform-test #4305

Merged

6 tasks

sbrannen reviewed Feb 26, 2025

View reviewed changes

...-jupiter-params/src/main/java/org/junit/jupiter/params/converter/TypedArgumentConverter.java Outdated Show resolved Hide resolved

sbrannen added theme: extensions component: Jupiter component: Platform theme: parameterized tests type: new feature labels Feb 26, 2025

scordio force-pushed the conversion-service branch from 8ed6eb6 to 940d018 Compare April 14, 2025 23:22

scordio force-pushed the conversion-service branch 3 times, most recently from 0a36152 to e380b8f Compare April 27, 2025 11:33

This comment was marked as outdated.

Sign in to view

scordio force-pushed the conversion-service branch from 45effd9 to a8d8356 Compare May 11, 2025 13:00

scordio changed the title ~~Introduce ConversionService in junit-platform-commons~~ Introduce Converter in junit-platform-commons May 11, 2025

scordio force-pushed the conversion-service branch from a8d8356 to d3675e2 Compare May 11, 2025 13:03

scordio commented May 11, 2025

View reviewed changes

marcphilipp reviewed May 12, 2025

View reviewed changes

scordio force-pushed the conversion-service branch from 6001a2c to 5190e37 Compare May 16, 2025 06:19

scordio commented May 16, 2025

View reviewed changes

scordio mentioned this pull request May 16, 2025

Support binary literal format for String to Number conversion #3605

Open

marcphilipp mentioned this pull request May 16, 2025

Introduce generic ConversionService SPI #853

Open

scordio commented May 16, 2025

View reviewed changes

scordio added 4 commits May 16, 2025 19:14

Introduce Converter in junit-platform-commons

f17db61

Introduce TypeDescriptor

3cb2c7f

Remove ClassLoader parameter from canConvert

3499da1

Rewrite StringToObjectConverter hierarchy as Converter subclasses

b560cff

scordio force-pushed the conversion-service branch from 5190e37 to af01791 Compare May 16, 2025 17:14

Add sourceType to canConvert and convert

0034d7d

scordio force-pushed the conversion-service branch from af01791 to 0034d7d Compare May 16, 2025 17:40

scordio mentioned this pull request May 17, 2025

Add ClasspathRunner test utility #4544

Open

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce `Converter` in `junit-platform-commons` #4219

Introduce `Converter` in `junit-platform-commons` #4219

scordio commented Dec 23, 2024 •

edited

Loading

scordio commented Dec 23, 2024 •

edited

Loading

marcphilipp commented Jan 2, 2025

marcphilipp left a comment

marcphilipp Jan 2, 2025

scordio May 15, 2025

scordio May 16, 2025

scordio May 17, 2025

marcphilipp commented Jan 2, 2025

scordio commented Jan 15, 2025

scordio commented Apr 21, 2025

This comment was marked as outdated.

scordio commented May 5, 2025

marcphilipp commented May 5, 2025

scordio commented May 10, 2025 •

edited

Loading

sbrannen commented May 10, 2025

scordio commented May 10, 2025 •

edited

Loading

marcphilipp commented May 10, 2025

scordio commented May 10, 2025

marcphilipp commented May 10, 2025

scordio commented May 11, 2025 •

edited

Loading

scordio commented May 11, 2025

sbrannen commented May 11, 2025

scordio May 11, 2025 •

edited

Loading

scordio May 11, 2025 •

edited

Loading

scordio May 11, 2025 •

edited

Loading

marcphilipp May 12, 2025

scordio May 11, 2025 •

edited

Loading

marcphilipp May 12, 2025

marcphilipp May 12, 2025

scordio May 12, 2025

scordio May 16, 2025

scordio May 16, 2025 •

edited

Loading

marcphilipp May 17, 2025


		import org.junit.platform.commons.support.conversion.TypedConversionService;

		// FIXME delete

	private static void withTestServices(Runnable runnable) {
	var current = Thread.currentThread().getContextClassLoader();
	var url = LauncherFactoryTests.class.getClassLoader().getResource("testservices/");
	try (var classLoader = new URLClassLoader(new URL[] { url }, current)) {
	Thread.currentThread().setContextClassLoader(classLoader);
	runnable.run();
	}
	catch (IOException e) {
	throw new UncheckedIOException(e);
	}
	finally {
	Thread.currentThread().setContextClassLoader(current);
	}
	}

	protected abstract T convert(S source) throws ConversionException;
	protected abstract T convert(S source, TypeDescriptor targetType) throws ConversionException;

Introduce Converter in junit-platform-commons #4219

Are you sure you want to change the base?

Introduce Converter in junit-platform-commons #4219

Conversation

scordio commented Dec 23, 2024 • edited Loading

Overview

Definition of Done

scordio commented Dec 23, 2024 • edited Loading

marcphilipp commented Jan 2, 2025

marcphilipp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcphilipp commented Jan 2, 2025

scordio commented Jan 15, 2025

scordio commented Apr 21, 2025

This comment was marked as outdated.

scordio commented May 5, 2025

marcphilipp commented May 5, 2025

scordio commented May 10, 2025 • edited Loading

sbrannen commented May 10, 2025

scordio commented May 10, 2025 • edited Loading

marcphilipp commented May 10, 2025

scordio commented May 10, 2025

marcphilipp commented May 10, 2025

scordio commented May 11, 2025 • edited Loading

scordio commented May 11, 2025

sbrannen commented May 11, 2025

scordio May 11, 2025 • edited Loading

Choose a reason for hiding this comment

scordio May 11, 2025 • edited Loading

Choose a reason for hiding this comment

scordio May 11, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scordio May 11, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scordio May 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Introduce `Converter` in `junit-platform-commons` #4219

Introduce `Converter` in `junit-platform-commons` #4219

scordio commented Dec 23, 2024 •

edited

Loading

scordio commented Dec 23, 2024 •

edited

Loading

scordio commented May 10, 2025 •

edited

Loading

scordio commented May 10, 2025 •

edited

Loading

scordio commented May 11, 2025 •

edited

Loading

scordio May 11, 2025 •

edited

Loading

scordio May 11, 2025 •

edited

Loading

scordio May 11, 2025 •

edited

Loading

scordio May 11, 2025 •

edited

Loading

scordio May 16, 2025 •

edited

Loading