or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

array-utilities.mdbuilders.mdconcurrent-utilities.mddate-time-utilities.mdexception-utilities.mdindex.mdmath-utilities.mdobject-utilities.mdstring-utilities.mdvalidation-utilities.md
tile.json

tessl/maven-org-apache-commons--commons-lang3

Apache Commons Lang provides essential Java utility classes for string manipulation, object operations, array handling, date/time processing, reflection utilities, and more.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.apache.commons/commons-lang3@3.18.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-commons--commons-lang3@3.18.0

index.mddocs/

Apache Commons Lang 3.18.0

Apache Commons Lang is a comprehensive utility library that provides a rich set of helpers for Java development. This library contains 223+ public classes across 16 packages with over 2000 public static utility methods, making it one of the most essential libraries for Java developers.

Package Information

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.18.0</version>
</dependency>

Maven Coordinates: org.apache.commons/commons-lang3@3.18.0
Java Version: Java 8+
License: Apache License 2.0

Core Imports

The most commonly used classes can be imported as follows:

// String utilities
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.CharUtils;

// Array utilities  
import org.apache.commons.lang3.ArrayUtils;

// Object utilities
import org.apache.commons.lang3.ObjectUtils;
import org.apache.commons.lang3.ClassUtils;
import org.apache.commons.lang3.BooleanUtils;

// Math utilities
import org.apache.commons.lang3.math.NumberUtils;

// Builder pattern utilities
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.EqualsBuilder;
import org.apache.commons.lang3.builder.HashCodeBuilder;

// Validation
import org.apache.commons.lang3.Validate;

// Date/Time utilities
import org.apache.commons.lang3.time.DateUtils;
import org.apache.commons.lang3.time.StopWatch;

// Exception handling
import org.apache.commons.lang3.exception.ExceptionUtils;

Key APIs Overview

String Manipulation

StringUtils provides 233+ null-safe string operations:

// Null-safe string operations
String result = StringUtils.defaultString(null, "default");  // "default"
boolean empty = StringUtils.isEmpty(null);                   // true
boolean blank = StringUtils.isBlank("  ");                   // true
String clean = StringUtils.trimToNull("  text  ");          // "text"

// String formatting and manipulation
String abbrev = StringUtils.abbreviate("Long text here", 10); // "Long te..."
String padded = StringUtils.leftPad("123", 5, '0');          // "00123"
String joined = StringUtils.join(Arrays.asList("a", "b"), ","); // "a,b"

Array Operations

ArrayUtils provides 368+ methods for array manipulation:

// Array creation and manipulation
int[] array = ArrayUtils.add(new int[]{1, 2}, 3);           // [1, 2, 3]
boolean contains = ArrayUtils.contains(array, 2);            // true
int[] reversed = ArrayUtils.reverse(array);                 // [3, 2, 1]
String[] subarray = ArrayUtils.subarray(new String[]{"a", "b", "c"}, 1, 3);

// Null-safe operations
boolean isEmpty = ArrayUtils.isEmpty(null);                  // true
int length = ArrayUtils.getLength(array);                   // 3

Object Utilities

ObjectUtils provides null-safe object operations:

// Null-safe operations
String result = ObjectUtils.defaultIfNull(null, "default"); // "default"
String first = ObjectUtils.firstNonNull(null, null, "value"); // "value"
boolean allNull = ObjectUtils.allNull(null, null);          // true

// Object comparison and cloning
int comparison = ObjectUtils.compare("a", "b");             // -1
Object cloned = ObjectUtils.clone(originalObject);

Validation

The Validate class provides argument validation with clear error messages:

// Argument validation
Validate.notNull(object, "Object cannot be null");
Validate.notEmpty(collection, "Collection cannot be empty");
Validate.inclusiveBetween(1, 10, value, "Value must be between 1 and 10");
Validate.isTrue(condition, "Condition must be true");

Architecture

Apache Commons Lang is organized into focused packages:

  • org.apache.commons.lang3 - Core utility classes
  • org.apache.commons.lang3.builder - Builder pattern utilities
  • org.apache.commons.lang3.math - Mathematical operations
  • org.apache.commons.lang3.time - Date and time utilities
  • org.apache.commons.lang3.concurrent - Concurrency utilities
  • org.apache.commons.lang3.exception - Exception handling
  • org.apache.commons.lang3.reflect - Reflection utilities
  • org.apache.commons.lang3.tuple - Tuple classes (Pair, Triple)

Basic Usage

Here's a quick example showing common patterns:

import org.apache.commons.lang3.*;
import org.apache.commons.lang3.builder.*;
import org.apache.commons.lang3.math.*;

public class CommonsLangExample {
    public void demonstrateUsage() {
        // String operations
        String input = null;
        String safe = StringUtils.defaultString(input, "N/A");
        
        // Array operations  
        String[] array = {"apple", "banana", "cherry"};
        boolean hasApple = ArrayUtils.contains(array, "apple");
        
        // Number parsing
        int number = NumberUtils.toInt("123", 0);
        
        // Validation
        Validate.notEmpty(array, "Array cannot be empty");
        
        // Builder pattern
        String description = new ToStringBuilder(this)
            .append("safe", safe)
            .append("hasApple", hasApple)
            .append("number", number)
            .toString();
    }
}

Functional Areas

This library is organized into several functional areas, each with comprehensive documentation:

String Utilities

  • StringUtils (233 methods) - Comprehensive string manipulation
  • CharUtils (25 methods) - Character operations and validation
  • CharSetUtils - Character set operations
  • RegExUtils - Regular expression utilities

Array Utilities

  • ArrayUtils (368 methods) - Complete array manipulation toolkit
  • ArraySorter - Array sorting utilities
  • ArrayFill - Array filling operations

Object Utilities

  • ObjectUtils (52 methods) - Null-safe object operations
  • ClassUtils (54 methods) - Class introspection and utilities
  • BooleanUtils (46 methods) - Boolean operations and conversions

Math Utilities

  • NumberUtils (82 methods) - Number parsing and validation
  • Range classes - Range operations and validation
  • Fraction - Fraction arithmetic operations

Date/Time Utilities

  • DateUtils (52 methods) - Date manipulation and formatting
  • StopWatch - Performance timing
  • DurationFormatUtils - Duration formatting

Builder Utilities

  • ToStringBuilder - Fluent toString() method construction
  • EqualsBuilder - Fluent equals() method construction
  • HashCodeBuilder - Fluent hashCode() method construction
  • CompareToBuilder - Fluent compareTo() method construction

Validation Utilities

  • Validate (51 methods) - Comprehensive argument validation
  • Input validation with clear error messages
  • Range and boundary checking

Concurrent Utilities

  • Thread-safe initializers and factories
  • Circuit breakers for fault tolerance
  • Background task execution utilities

Exception Utilities

  • ExceptionUtils (35 methods) - Exception analysis and handling
  • Stack trace utilities and cause extraction
  • Contextual exception handling

Performance and Best Practices

Apache Commons Lang is designed for high performance with minimal overhead:

  • Null Safety: All utility methods handle null inputs gracefully
  • Immutability: Most operations return new objects rather than modifying inputs
  • Thread Safety: Utility classes are thread-safe for concurrent use
  • Zero Dependencies: No external dependencies beyond Java standard library

Memory Usage

  • Utility classes use static methods to minimize object creation
  • Builder classes reuse internal buffers where possible
  • Array operations minimize copying when feasible

Common Patterns

// Defensive programming with null checks
String result = StringUtils.trimToNull(input);
if (StringUtils.isNotBlank(result)) {
    // Process non-blank string
}

// Fluent validation
Validate.notNull(user, "User cannot be null")
    .notEmpty(user.getName(), "Name cannot be empty");

// Builder pattern for complex objects
String description = ToStringBuilder.reflectionToString(object, 
    ToStringStyle.SHORT_PREFIX_STYLE);

Integration Examples

Spring Framework Integration

@Component
public class UserService {
    
    public User createUser(String name, String email) {
        Validate.notBlank(name, "Name is required");
        Validate.notBlank(email, "Email is required");
        
        String cleanName = StringUtils.trim(name);
        String normalizedEmail = StringUtils.lowerCase(email);
        
        return new User(cleanName, normalizedEmail);
    }
}

Testing Support

@Test
public void testUserValidation() {
    // Using ArrayUtils for test data
    String[] validNames = {"John", "Jane", "Bob"};
    String[] invalidNames = {null, "", "  "};
    
    for (String name : validNames) {
        assertDoesNotThrow(() -> userService.createUser(name, "test@example.com"));
    }
    
    for (String name : invalidNames) {
        assertThrows(IllegalArgumentException.class, 
            () -> userService.createUser(name, "test@example.com"));
    }
}

Migration and Compatibility

From Commons Lang 2.x

Most methods are backward compatible, with key improvements:

  • Package name changed from org.apache.commons.lang to org.apache.commons.lang3
  • Enhanced null safety across all utility methods
  • New builder classes and functional programming support
  • Improved performance and reduced memory footprint

Java Version Compatibility

  • Java 8+: Full feature support including lambda integration
  • Java 11+: Enhanced with newer Java features
  • Java 17+: Optimized for modern JVM performance

Common Use Cases

  1. Input Validation: Use Validate class for comprehensive argument checking
  2. String Processing: StringUtils for all text manipulation needs
  3. Array Operations: ArrayUtils for collection-like operations on arrays
  4. Object Construction: Builder classes for clean object creation
  5. Error Handling: ExceptionUtils for robust exception management
  6. Performance Monitoring: StopWatch for timing operations
  7. Type Safety: NumberUtils for safe number parsing and conversion

This library serves as the foundation for robust, maintainable Java applications by providing well-tested, performant utilities for common programming tasks.