UNITILITY - The Ultimate Units of Measurement and Physical Quantity Converter

Introducing <strong>UNITILITY</strong> - the Java library designed to simplify physics unit conversions and provide intuitive business types that represent aggregated physical quantities, including their type, value, and unit—all in one. <br>

If your project involves engineering or scientific work, you’ll love Unitility! <br>

With a wide range of value objects that represent commonly used physical quantities, this solution is built using plain Java for optimal speed and lightweight functionality. Whether you're looking to convert units within the same type or customize to meet your specific needs, the UNITILITY core module offers quick and easy usage in your project, without requiring heavy frameworks or external libraries. Additional framework support is available through the extension modules. <br>

<span style="color: green;"> - Thread-Safe Architecture:</span> Developed to ensure thread safety, allowing for concurrent access without compromising data integrity through the utilization of immutable objects. <br> <span style="color: teal;"> - Kotlin and Groovy friendly:</span> Developed to take some advantages of Kotlin and Groovy features, such as overloaded operators.

  <br>        

AUTHOR: Piotr Jazdzyk, MSc Eng <br> LINKEDIN: https://www.linkedin.com/in/pjazdzyk <br>

TABLE OF CONTENTS

1. Installation <br>
2. Tech & dependencies <br>
3. Supported physical quantities and units <br>
4. Usage and functionality <br> 4.1 Working with physical quantities <br> 4.2 Parsing quantities from string <br> 4.3 Logic operations <br> 4.4 Arithmetic operations <br> 4.5 Power and logarithmic operations <br> 4.6 Trigonometric operations <br> 4.7 Equality and sorting <br>
5. Unitility extension modules <br> 5.1 Jackson serializers / deserializers <br>   5.1.1 Default ser-de <br>   5.1.2 Plain SI value ser-de <br> 5.2 SpringBoot web extension <br> 5.3 Quarkus web extension <br> 5.4 Jakarta Validation <br>
6. Creating custom units and quantities <br> 6.1 Custom unit <br> 6.2 Registering custom quantity in Spring <br> 6.3 Registering custom quantity in Quarkus <br>
7. Compatibility with other JVM languages <br> 7.1 Groovy <br> 7.2 Kotlin <br>
8. Special types: geographic <br> 8.1 Latitude, Longitude, GeoCoordinate <br> 8.2 Bearing <br> 8.3 GeoDistance (Haversine equations) <br> 8.4 Parsing geographic quantities and JSON structures <br>
9. Persistence <br> 9.1 Attribute Converters - Default SI <br>
10. Collaboration, attribution and citation <br>
11. Acknowledgments <br>

1. INSTALLATION

Copy the Maven dependency provided below to your pom.xml file, and you are ready to go. For other package managers, check maven central repository: UNITILITY.

<dependency>
    <groupId>com.synerset</groupId>
    <artifactId>unitility-core</artifactId>
    <version>3.0.1</version>
</dependency>

If you use frameworks to develop web applications, it is recommended to use Unitility extension modules, to provide PhysicalQuantity instances serialization and deserialization including path and query parameters.<br>

Extension for the Spring Boot framework:

<dependency>
    <groupId>com.synerset</groupId>
    <artifactId>unitility-spring</artifactId>
    <version>3.0.1</version>
</dependency>

Extension for the Quarkus framework:

<dependency>
    <groupId>com.synerset</groupId>
    <artifactId>unitility-quarkus</artifactId>
    <version>3.0.1</version>
</dependency>

Extensions include CORE module, so you don't have to put it separate in your pom. See section on Spring or Quarkus for better explanation. Unitility has also provided BOM which can be used for dependency management.

2. TECH AND DEPENDENCIES

<strong>Unitility</strong> is developed using the following technologies: <br>

Core: <br>      

Extension modules:<br>    

CI/CD:<br>    

The Key concept of the core module is to use plain Java, to minimize any issues with compatibility, conflicting transitive dependencies or excessive dependency version management.

3. SUPPORTED PHYSICAL QUANTITIES AND UNITS

At the current level of development, the following units are listed below. Each quantity includes the most popular SI units and at least one Imperial unit.

COMMON:

• Distance, Length, Width, Height, Diameter, Thickness, Perimeter: meter [m], centimetre [cm], millimetre [mm], kilometre [km], mile [mi], nautical mile [nmi], feet [ft], inch [in], yard [yd], decameter [dam], hectometer[hm], data mile [datmi],
• Area: square meter [m²], square kilometre [km²], square centimetre [cm²], square millimetre [mm²], are [a], hectare [ha], square inch [in²], square foot [ft²], square yard [yd²], acre [ac], square mile [mi²]
• Volume: cubic meter [m³], cubic centimetre [L], liter [L], hectolitre [hL], millilitre [mL], ounce [fl.oz], pint [pt], gallon (US) [gal_us], gallon (UK) [gal_uk]
• Mass: kilogram [kg], gram [g], milligram [mg], tonne [t], ounce [oz], pound [lb]
• Angle: degrees [°], radians [rad]
• Ratio: percent [%], Decimal [-]
• LinearMassDensity: Kilogram per metre [kg/m], Tonne per metre [t/m], Ounce per foot [oz/ft], Pound per foot [lb/ft]
• Velocity: meter per second [m/s], centimeter per second [cm/s], kilometer per hour [km/h], inch per second, [in/s], feet per second [ft/s], mile per hour [mph], knot [kn], Mach [Mach]
• AngularVelocity: radians per second [rad/s], revolutions per minute, [rpm], revolutions per second [rps], degrees per second [°/s]
• Curvature: radians per meter [rad/m], radians per foot [rad/ft], degrees per meter [°/m], degrees per foot [°/ft], degrees per hundred feet [°/100ft]
• Data size: bits [bit], bytes [b], kilobytes[kb], megabytes [mb], gigabyte [gb], terabyte [tb], petabyte [pb]

MECHANICAL:

• Force: newton [N], kilonew