abacus-common

abacus-common is a general-purpose Java programming library that provides a rich set of utilities, data structures, and functional APIs.

Key Features:

1. Frequently used utilities — e.g., Strings, Numbers, Maps, Joiner, Splitter.
2. Additional data structures — Dataset, Sheet, Multiset, Multimap, Pair, Tuple, Range, Fraction.
3. Comprehensive functional programming APIs — including Stream, EntryStream, Collectors.

How it differs from other libraries?

1. Comprehensive and consistent: abacus-common offers unified APIs across data types — for example, N.isEmpty(String/byte[]/Collection/Map/...) — instead of relying on separate utilities like StringUtils/ArrayUtils/Collections/MapUtils.isEmpty(...) from different classes/libraries.

2. Simple and concise: All APIs are well organized and follow consistent design principles:

   • Use concise, consistent method names and parameter orders.
   • Ensure predictable and uniform behavior across components.
   • Empty strings/collections/maps or Optional are preferred over null as return values whenever appropriate.
   • More ... refer to: How To Design A Good API and Why it Matters, video

3. Powerful and extensive: The library provides thousands of utility methods — covering everything from daily-use helpers to advanced support for I/O, concurrency, JSON/XML serialization, and functional programming(e.g.,Stream.of(persons).map(Person::getEmail())...filter(Strings::isNotEmpty).groupBy(Person::getLastName).persist(file)...).

Why abacus-common?

abacus-common is a mega-library unlike most others. It contains thousands of public methods across tens of classes, covering nearly all common programming use cases. You no longer need to search multiple libraries or maintain your own StringUtils or CollectionUtils — everything is conveniently available in one place with clean, consistent, and easy-to-use APIs. Well-designed APIs and data structures steady your mind ♪ 𝆑 ♪ and set your keyboard alight ♪♫♪♫. It may very well change the way you write Java. The ultimate goal is to make code that uses this library easy to read and maintain by simplifying the implementation and enhancing readability through concise APIs and data structures.

Features:

• Frequently Used APIs: CommonUtil, N, Strings, Numbers, Array, Iterables, Iterators, Maps, Beans, Dates, IOUtil, Files, Multiset, Multimap, ListMultimap, SetMultimap, Dataset, Sheet, BiMap, ImmutableList, ImmutableSet, ImmutableMap, Result, Holder, Pair, Triple, Tuple, Range, Duration, Stopwatch, RateLimiter, Fraction, Splitter, Joiner, Builder, Difference, Comparators, Index, Median, Wrapper, Indexed, Keyed, Timed, IndexedKeyed, TypeReference, Clazz, If, Try, Synchronized, Retry, Hashing, Hex, DigestUtil, RegExUtil, URLEncodedUtil, CSVUtil, ExcelUtil, ClassUtil, AsyncExecutor, ContinuableFuture, Futures, Profiler...

• Streams, both sequential and parallel, are supported with more functions:
  BaseStream, Stream, CharStream, ByteStream, ShortStream, IntStream, LongStream, FloatStream, DoubleStream, EntryStream, Fn, MoreCollectors, Seq, Fnn and Throwables.

• Optional: OptionalBoolean, OptionalChar, OptionalByte, OptionalShort, OptionalInt, OptionalLong, OptionalFloat, OptionalDouble, Optional and Nullable

• Primitive Mutable: MutableBoolean, MutableChar, MutableByte, MutableShort, MutableInt, MutableLong, MutableFloat and MutableDouble.

• Primitive/Immutable Iterator: ObjIterator, BooleanIterator, CharIterator, ByteIterator, ShortIterator, IntIterator, LongIterator, FloatIterator, DoubleIterator, BiIterator, TriIterator and LineIterator.

• Primitive List: PrimitiveList, BooleanList, CharList, ByteList, ShortList, IntList, LongList, FloatList and DoubleList.

• Http: HttpClient, HttpRequest, OkHttpRequest, WebUtil, and More ...

• JSON/XML Data Binding: Parser, JSONParser, XMLParser, KryoParser, ParserFactory, JsonMappers, XmlMappers, FastJson, JSONUtil and More ...

• Pool: Pool, ObjectPool, KeyedObjectPool, PoolFactory and More ...

• Misc: CodeGenerationUtil, Charsets, Ascii, CalendarField, NamingPolicy, Properties, PropertiesUtil, XmlUtil, EscapeUtil, AddrUtil, WSSecurityUtil, EmailUtil, IEEE754rUtil, FilenameUtil, Files, Traverser(copied from Apache commons, Google Guava...under Apache License v2) ...

Download/Installation & Changes:

• Maven

<dependency>
	<groupId>com.landawn</groupId>
	<artifactId>abacus-common</artifactId>
	<version>7.1.2</version> 
<dependency>

• Gradle:

// JDK 17 or above:
compile 'com.landawn:abacus-common:7.1.2'

Design and Implementation Considerations:

• In general, empty values—such as an empty String, Collection, or Map—are returned instead of null. However, certain methods (e.g., Strings.firstNonEmpty() or Strings.emptyToNull()) may legitimately return null. Methods that may return null are typically annotated with @MayReturnNull or explicitly documented in the Javadoc.

• Most methods are designed to support broad and general use cases. null parameters are generally permitted as long as they do not violate the method’s intended contract. For example: Numbers.createNumber(...) or N.filter(...). It is the user’s responsibility to handle null values appropriately if they are considered invalid in a given context.

• In general, extensive method overloading is discouraged, as it is often unnecessary and may be considered a design smell in many scenarios. However, in this library, extreme code simplicity and high performance are primary goals, and method overloading (for example, N.occurrencesOf(...) and N.filter(...)) is intentionally used to support those objectives.

• Immutable vs. Mutable: Immutable objects are not preferred over mutable ones in this library. Mutable variables and parameters are generally used as the base cases. a), when a variable is passed as a method parameter, it should typically not be modified within the called method, unless it is explicitly intended to serve as an output parameter or modifying the input parameter is (part of) the purpose of the method call. b), a value returned from a method may be freely modified by the caller, as the caller is considered the owner/holder of the returned value. If the returned value is not meant to be modified by the caller, an immutable value should be returned instead. c), variables must not be modified concurrently by multiple threads without proper synchronization, regardless of whether they are mutable or immutable. In other words, if no modifications occur, it makes no difference whether the variables are mutable or immutable.

• Given the large number of methods across this library, maintaining strict consistency in handling exceptions such as IllegalArgumentException, IndexOutOfBoundsException, NullPointerException, and similar is inherently challenging. Therefore, these exceptions should not be treated differently, and the following approach must be avoided:

		try {
		    call some methods which may throw: IllegalArgumentException/IndexOutOfBoundsException/NullPointerException in this library.
		} catch (IllegalArgumentException e) {
		    // do something...
		} catch (IndexOutOfBoundsException e) {
		    // do something else...
		} catch (NullPointerException e) {
		    // otherwise...
		}

Comparison with Apache Commons Lang, Google Guava and other libraries:

First of all, some code in abacus-common was originally derived from Apache Commons Lang, Google Guava, and other libraries under the Apache License v2. In addition, abacus-common includes wrapper classes built on top of third-party APIs. Whether the code is adapted from existing libraries or implemented as wrappers(e.g., OkHttpRequest/Hashing), the primary goal is to provide a unified API and consistent programming experience through a cohesive and integrated design. (abacus-common could serve as a replacement for Apache Commons Lang or Google Guava in certain scenarios; however, this is not a recommendation. Developers are encouraged to choose the library that best fits their preferences and project requirements.)

Secondly, although abacus-common includes thousands of public methods across dozens of classes and additional data structures, its APIs mainly focus on solving common everyday programming problems. The design centers around the most frequently used Java data structures, such as String/Number/Collection/Map/Bean/Stream.... APIs for HTTP web requests and JSON/XML serialization are also included because these are widely used in daily programming—much like collections. Beyond that, the library provides a few small miscellaneous utility classes.

There are no plans to extend abacus-common into unrelated domains such as compression, artificial intelligence, or other specialized areas. The focus remains on providing a clean, consistent, and integrated utility foundation for general-purpose Java programming. The APIs are designed to remain stable and long-lasting, with no major changes anticipated in future releases, even though there have been numerous iterations and modifications in the past.

Functional Programming:

To fully leverage abacus-common, familiarity with Java 8+ lambdas and the Stream API is recommended. Helpful resources include:

Java Stream API

When to use parallel streams

Performance Hints

Top Java 8 stream questions on stackoverflow

Kotlin vs Java 8 on Collection

Also See: abacus-jdbc, abacus-query, abacus-extra, abacus-cache and abacus-android

Recommended Java programming libraries/frameworks:

lombok, Guava, protobuf, Kyro, snappy-java, lz4-java, Caffeine, Ehcache, Chronicle-Map, echarts, Chartjs, Highcharts, Apache POI, easyexcel, opencsv, mapstruct, fastutil, hppc, re2j ... awesome-java

Recommended Java programming tools:

Spotbugs, JaCoCo...

If Proposals is slow with Big class: N, Strings, Stream, Open the class file and explore the methods in outline once. Then test again.

                           ...beyond imagination...