willhains / udtopia Goto Github PK

As discussed in Shields issue: badges/shields#8736

Remove branch parameter from beta branch status badge URL.
The badge should show the latest result of build-beta.yml.
No need to specify the branch explicitly.

Current:

New:

- https://shields.io/github/actions/workflow/status/willhains/udtopia/build-beta.yml?label=beta+build&branch=beta/1.0.0
+ https://shields.io/github/actions/workflow/status/willhains/udtopia/build-beta.yml?label=beta+build

Summary

Errors per input

Errors in CONTRIBUTING.md

• [TIMEOUT] https://twitter.com/UDTopia_Java | Timeout

Errors in README.md

• [TIMEOUT] https://twitter.com/UDTopia_Java | Timeout
• [TIMEOUT] https://twitter.com/willhains | Timeout
• [521] https://javadoc.io/doc/org.udtopia/udtopia | Failed: Network error: Unknown status code
• [521] https://javadoc.io/badge2/org.udtopia/udtopia/javadoc.svg | Failed: Network error: Unknown status code

Errors in DOCUMENTATION.md

• [521] https://javadoc.io/doc/org.udtopia/udtopia/latest/index.html | Failed: Network error: Unknown status code

There is currently no way to create a rule annotation to normalize/validate a BigDecimal value.

Test that UDTopia works on later Java versions, and fix it if it doesn't.

Use-cases to test:

• Use the existing .jar (built on JDK 8) on higher-version JREs.
• With the versions in pom.xml as-is, build on higher-version JDKs.
• Build with higher source and target versions in pom.xml.

Replace all smart quotes with dumb quotes.

Warnings found in workflow logs:

Discard Safety Test (MultiField, ubuntu-latest, 11, temurin)
Node.js 12 actions are deprecated. Please update the following actions to use Node.js 16: actions/checkout@v2, actions/setup-java@v2. For more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/.

The @LowerCase and @UpperCase normalizer rules do only simple letter case coercion.

Should there be a normalizer rule for more sophisticated case conversion patterns for words?

Proposed APIs

@WordsAs(CAMEL_CASE) // camelCase
@WordsAs(CONCATENATED_TITLE_CASE) // ConcatenatedTitleCase
@WordsAs(TITLE_CASE) // Title Case
@WordsAs(SNAKE_CASE) // snake_case
@WordsAs(HYPHENATED) // hyphenated-words-like-this
@WordsAs(ENUM_CASE) // ENUM_CASE

The @Max validator shortens the input string value to prevent huge validation exception messages.
This safety feature should protect all string validators, not only @Max.

The Discard Safety Tests workflow failed with a diff that isn't a diff.

Run java -cp "./target/classes;./target/test-classes" org.udtopia.recycle.SingleFieldDiscardSafetyTest
  java -cp "./target/classes;./target/test-classes" org.udtopia.recycle.SingleFieldDiscardSafetyTest
  shell: C:\Program Files\PowerShell\7\pwsh.EXE -command ". '{0}'"
  env:
    JAVA_HOME: C:\hostedtoolcache\windows\Java_Zulu_jdk\8.0.312-7\x64
producer: (3451777) 1726071.26877399371005594730377197265625 -- RecycleBin[4]: Enable assertions (-ea) to see recycle stats <-- final value
consumer: (3451777) 1726071.26877399371005594730377197265625 <-- DIFF!
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
consumer: (3451777) 1726071.26877399371005594730377197265625
Error: Process completed with exit code 1.

A re-run of the same job passed.

The @Max(length) validator rule throws when the value is longer than length.
The @Trim normalizer rule trims whitespace characters only.

Should there be a normalizer rule to truncate string values to a specified length?

Use-Case Example

You want to capture the output of an operation to show in a progress summary.
When the command output is very long, you don't need to keep all of it, but the first X characters are useful, and you don't want a long value to cause an error.

Proposed API

@Truncate(60)
public final @Value class CommandOutput extends PureString<CommandOutput> {...}

The Maven dependency code sample in the README file currently says:

<version>RELEASE <!-- sub for real version --></version>

It would be better to have the real version there.

Ideally, automate the version number update with each new beta branch.

• Rename released branch to stable.
• Update docs with new name.
• Set stable as default branch.
• Automatically merge and delete beta/* branch upon release.

Email address validation can be tricky.
Should there be an explicit validator rule for email address strings?
There may also be some performance benefit to validate by code rather than by regex.

Proposed API

@EmailAddress
public final @Value class EmailAddress extends PureString<EmailAddress> {...}

@HostName
public final @Value class HostName extends PureString<HostName> {...}

@IPAddress
public final @Value class ServerIP extends PureString<ServerIP> {...}

Alternatives

Rather than creating separate annotations for each, provide constants for special cases:

@Matching(EMAIL_ADDRESS)
public final @Value class EmailAddress extends PureString<EmailAddress> {...}

@Matching(HOST_NAME)
public final @Value class HostName extends PureString<HostName> {...}

@Matching(IP_V4_ADDRESS)
public final @Value class ServerIP extends PureString<ServerIP> {...}

These could be well-tested regex patterns, or special constant string values that the @Matching rule checks for, and invokes non-regex logic for faster validation.

Currently, the UDT* value classes are subclassed by Pure* and Recyclable* classes.

The Recyclable* classes reuse existing instances, resetting their raw value on every "allocation".

Use-Case

There are use-cases where the same, small number of values are repeated many times.
In these cases, it might be better to keep a cache of previously created instances, similar to String.intern(). (And the UDTString subclass could actually intern the raw value as well.)

Proposed API

public final @Value class CityName extends FlyweightString<CityName> {...}

@Chars and @NotChars are fine when the set of allowed/disallowed characters is small, but there is a need to validate that string values conform to a given character set.

Use-Case Example

You want to save a text value into a file or database with ISO-8859-1 (US-ASCII) encoding.
The app needs to validate that the text can conform to that encoding.

Proposed API

Rather than hard-code any specific encoding, provide a parameter to specify the name of the character set:

@Max(50) @EncodableAs("US-ASCII")
public final @Value class SomeAsciiValue {...}

Currently, the role annotations @Value, @Mutable, @IO, and @ThreadSafe have RUNTIME retention. This retention level is unnecessary.

• UDTopia itself doesn't use them at runtime.
• There are no tools (yet) that use them for static code analysis.

Runtime retention means projects cannot use them without a runtime dependency.

Reduce the retention level to source-only.

Proposed API

@PowerOf(2)