README.md

UDTopia

User-defined types (UDTs) are the best way to control complexity and bring clarity to your code, but UDTs are unwieldy in Java. UDTopia makes Java UDTs delightful.

How to Use

UDTopia has no runtime dependencies. You can download and use the .jar file directly, or add org.udtopia:udtopia as a dependency in your project.

<dependency>
  <groupId>org.udtopia</groupId>
  <artifactId>udtopia</artifactId>
  <version>RELEASE <!-- sub for real version --></version>
</dependency>

Features

UDTopia makes it trivial to wrap a raw value in a custom class (UDT). For example, instead of using String to represent user IDs, wrap them in a UserId UDT:

public final @Value class UserId extends PureString<UserId>
{
  public UserId(String id) { super(UserId::new, id); }
}

Why do this?

• A well-named UDT makes code clearer and less error-prone.
• We can add methods to UserId for logic related to user IDs.
• UDTopia's Pure* classes take care of the usual Java class boilerplate, like equals, hashCode, and Comparable. More info in the docs.

Validate and Normalize Values

We don't allow just any old string as a user ID; there are rules. Let's constrain UserId so that invalid user IDs can't exist.

UDTopia's Rule Annotations make it easy:

@Trim // trim whitespace from start & end
@Chars(LETTERS + DIGITS + “_”) // allowed chars
@Min(2) @Max(18) // allowed length
@LowerCase // convert to lowercase
public final @Value class UserId extends PureString<UserId>

UDTopia comes with several built-in rules, and you can create your own.

Recycle UDT Objects

GC pressure is rarely a problem with UDT objects. But, for when profiling reveals excessive GC activity, UDTopia has an advanced object recycling feature.

UserId userId = UserId.parse(input);
// process the value...
userId.discard();

Recycling is fast and thread-safe. It's built into UDTopia's Recyclable* base classes, and you can use it in your own classes, too.

👋 Get in Touch

Have questions? Need help? Check the FAQ, search the issue tracker, or send a tweet/DM to @UDTopia_Java.

Want to help? Found a bug? Have an idea? Check out the contribution guidelines to get started.