White_Utils – Java Utility Library

A lightweight library containing shared and generic utility classes for Java-based projects.

1) What is this repository for?

1.1) Quick summary

Version: 1.0.9

White_Utils is a public Java library that provides standardized and generic utility classes to simplify common operations such as logging, formatting, and general helper functions across Java and Maven projects. It is published for public consumption and is also used as a standard within White Organization.

---

2) How to Use

WhiteUtils is designed to be as generic and dependency-minimal as possible so it can be integrated into any Java-based project.

Add dependency (example):

<dependency>
    <groupId>mx.whiteweb.sdev</groupId>
    <artifactId>white-utils</artifactId>
    <version>1.0.8</version>
</dependency>

Primary utilities (examples):

• WhiteLoggeable — standardized logging helpers (SLF4J-friendly usage).

Example:

@Slf4j
public class MyService implements WhiteLoggeable {
    @Override public org.slf4j.Logger getLogger() { return log;}
    
    public void myProcess(String name, int age) {
        // Method chaining is supported - all logging methods return LogContext
        var log = withSignature("myProcess(name, age)")
            .start("Processing user {} with age {}", name, age);
        
        log.debug("User age is {}", age);
        if (age < 18) {
            log.warn("User {} is a minor", name);
        }
        
        log.info("User processed successfully")
            .end("age is now {}", age);
    }
}

3) Configuration / Setup

How do I get set up for development?

3.1) Development environment

• JDK version: 1.8
• Maven

3.2) Project Dependencies

This library uses:

• Lombok to log errors and general logs.
  • Slf4j

3.3) Planned Dependencies (in the future)

• JUnit5. No tests have been added yet.

3.3) Configuration Steps

3.3.1) main Branch Protection

In order for us to ensure that the main branch isn't accidentally corrupted, we're implementing a check that will prevent users from pushing directly to main and forces every change to be merged with a pull request.

You can execute this file: main-protection-win.bat before editing any text, code, branches, or anything in this repository to help you with these cases.

3.3.2) Git Alias

When executing main-protection-win.bat, the script will open a file in notepad.

Only if you haven't done so already, paste the following git alias script at the end of that file :

[alias]
    main2branch = "!f() { \
        if [ \"$#\" -ne 1 ]; then \
            echo \"Usage: git main2branch <new_branch_name>\"; \
            exit 1; \
        fi; \
        current_branch=$(git rev-parse --abbrev-ref HEAD); \
        if [ \"$current_branch\" != \"main\" ]; then \
            echo \"Error: You must be on 'main' branch to use this alias.\"; \
            exit 1; \
        fi; \
        new_branch=$1; \
        git fetch origin main || exit 1; \
        git branch \"$new_branch\" || exit 1; \
        git reset --hard origin/main || exit 1; \
        echo \"Moved local-only commits to branch '$new_branch'.\"; \
        git checkout \"$new_branch\" || exit 1; \
    }; f"

This script creates a new alias, main2branch, that takes all local commits on main, that aren't present in origin, and moves them to a new branch, with a customizable name. Usage: git main2branch new-branch. This is useful for situations when you accidentally commit on main locally, and need to move those changes to the new branch.

4) How to Deploy?

The deployment process is automated at this point, once the new version is detected to be merge into main from a PR, a GitHub action will build the artifact and upload it to Maven Central.

5) What are the Contribution guidelines?

5.1) Writing tests.

• Unit tests using JUnit 5 will be required for new utility code.
• Keep test scope focused and deterministic.

5.2) Code review.

• Create feature branches and open PRs against main.
• Provide a clear description of the change, rationale, and any compatibility notes.
• Keep the API surface small and stable. Maintain backward compatibility where feasible.

5.3) Other guidelines.

Please ask for the code standard to use as a guideline and reflect it in the project.

• Ensure pom.xml contains appropriate metadata (groupId, artifactId, version, licenses, SCM, developers) when preparing releases for Maven Central.

6) Who do I talk to?

Role	Contact
Owner/admin	current main developer: obed.vazquez@gmail.com
Supporters	Currently none
Community	send us a message in our Discord Server

Please, contact me if you want to help; In general, I'm developing, maintaining, and supporting this project on my own with no help or support from anyone; any tip, comment, change, or help in general is well-received.