Skip to main content

ISOUtil

org.jpos.iso.ISOUtil is one of jPOS's oldest and most widely used utility classes. It started life as a set of encoding converters—ASCII to BCD, ASCII to EBCDIC, and back—required internally by field packagers to handle ISO-8583 wire formats. Over the years it grew steadily, accumulating methods for string padding and trimming, byte array manipulation, BitSet handling, hex encoding/decoding, Luhn check digit calculation, amount formatting, and more.

Why it matters​

It is tempting, when you need to left-pad a string or convert a hex string to bytes, to reach for a well-known library. Apache Commons Lang and Apache Commons Codec are popular choices—familiar, well-documented, and widely trusted. The problem is the dependency footprint.

A single commons-lang3 or commons-codec JAR pulls in transitive dependencies. Those dependencies have their own release cycles, their own CVEs, and their own audit surface. Payment and banking systems regularly face security audits, PCI-DSS scans, and vulnerability management processes where every JAR on the classpath must be justified. Introducing Apache Commons to pad a string to ten characters can, and does, lead to audit findings and remediation cycles that cost far more than the convenience was worth.

ISOUtil is already on the classpath in every jPOS application. It has no transitive dependencies of its own. Using it for common utility operations keeps your dependency surface minimal and your audit results clean.

What's available​

The class covers a broad range of operations. A representative selection:

String padding and trimming

  • padleft(s, len, c)—right-aligns s in a field of width len, padding with character c
  • padright(s, len, c)—left-aligns s, padding on the right
  • zeropad(s, len)—zero-pads a numeric string to len digits
  • zeropadRight(s, len)—zero-pads on the right
  • strpad(s, len)—space-pads to len
  • trim(s)—trims trailing spaces
  • unPadLeft(s, c) / unPadRight(s, c)—strips padding characters
  • blankUnPad(s) / zeroUnPad(s)—convenience variants for spaces and zeros

Substring helpers

  • takeFirstN(s, n)—first n characters
  • takeLastN(s, n)—last n characters

Encoding and conversion

  • str2bcd(s, padLeft)—ASCII decimal string to BCD bytes
  • bcd2str(b, offset, len, padLeft)—BCD bytes back to string
  • hexString(b)—byte array to hex string
  • hex2byte(s)—hex string to byte array
  • asciiToEbcdic(s) / ebcdicToAscii(b)—character set conversion
  • hexdump(b)—formatted hex dump for logging

Byte array operations

  • xor(op1, op2)—XOR two byte arrays
  • concat(array1, array2)—concatenate byte arrays
  • trim(array, length)—trim a byte array to length

BitSet utilities

  • bitSet2byte(b) / byte2BitSet(b, ...)—ISO-8583 bitmap conversion
  • hex2BitSet(b, ...)—parse a hex bitmap

Numeric helpers

  • parseInt(s, radix)—parse integers from strings, char arrays, or byte arrays
  • isNumeric(s, radix) / isAlphaNumeric(s) / isBlank(s) / isZero(s)—validation predicates
  • formatAmount(l, len)—format a long amount with implied decimal point
  • calcLUHN(p)—compute the Luhn check digit of a PAN
  • formatAmountConversionRate(rate) / parseAmountConversionRate(s)—ISO 4217 rate encoding

Miscellaneous

  • protect(s)—mask a PAN for logging (shows first 6 and last 4)
  • normalize(s)—strip non-printable characters for safe logging
  • commaEncode(ss...) / commaDecode(s)—encode/decode string arrays
  • sleep(millis)—interrupt-safe sleep
  • millisToString(millis)—human-readable duration

Before adding a dependency​

Check ISOUtil first. If what you need is not there, reach out through the usual channels—the jPOS team is responsive and will consider adding a method if the use case is broadly useful. A utility method added to ISOUtil benefits every project in the ecosystem and costs nothing in dependency footprint.

The rule of thumb

If you are about to add Apache Commons, Guava, or a similar general-purpose utility library solely for string manipulation, byte handling, or encoding, check ISOUtil first. The odds are good that what you need is already there.