Exception Handling

/**
 * Abstract base class for all barcode reading exceptions.
 * Subclasses indicate specific failure reasons:
 * - NotFoundException: No barcode found
 * - ChecksumException: Barcode found but checksum failed
 * - FormatException: Barcode found but format invalid
 *
 * Note: ReaderException deliberately does not fill in stack trace
 * for performance reasons in high-frequency scanning scenarios.
 */
public abstract class ReaderException extends Exception {
    // Protected constructor - only subclasses can be instantiated
    protected ReaderException();

    protected ReaderException(Throwable cause);

    // Stack trace is not filled for performance
    @Override
    public final synchronized Throwable fillInStackTrace();
}

/**
 * Exception thrown when no barcode is found in an image.
 * This is the most common exception during scanning and typically
 * indicates:
 * - No barcode present in the image
 * - Barcode is too small, blurry, or damaged to detect
 * - Image quality is insufficient
 * - Wrong format being attempted (use POSSIBLE_FORMATS hint)
 *
 * Handling: Show "no barcode found" message or continue scanning.
 */
public final class NotFoundException extends ReaderException {
    private static final NotFoundException INSTANCE = new NotFoundException();

    private NotFoundException();

    /**
     * Gets the singleton instance (for performance).
     * @return Shared NotFoundException instance
     */
    public static NotFoundException getNotFoundInstance();
}

import com.google.zxing.*;

try {
    Reader reader = new MultiFormatReader();
    Result result = reader.decode(bitmap);
    System.out.println("Found: " + result.getText());

} catch (NotFoundException e) {
    // No barcode detected - very common during scanning
    System.out.println("No barcode found in image");
    // Continue scanning or show message to user

} catch (ChecksumException | FormatException e) {
    // Barcode detected but couldn't be decoded
    System.out.println("Barcode found but unreadable");
}

/**
 * Exception thrown when a barcode is found but checksum validation fails.
 * Indicates:
 * - Barcode was successfully located
 * - Pattern structure is valid
 * - But data has been corrupted or is incomplete
 *
 * Common causes:
 * - Physical damage to barcode
 * - Print quality issues
 * - Partial obscuration
 * - Insufficient error correction capacity
 *
 * Handling: Retry scan, request user to clean barcode,
 * or report damaged barcode.
 */
public final class ChecksumException extends ReaderException {
    private static final ChecksumException INSTANCE = new ChecksumException();

    private ChecksumException();

    /**
     * Gets the singleton instance (for performance).
     * @return Shared ChecksumException instance
     */
    public static ChecksumException getChecksumInstance();
}

import com.google.zxing.*;

try {
    Reader reader = new MultiFormatReader();
    Result result = reader.decode(bitmap);

} catch (ChecksumException e) {
    // Barcode found but damaged
    System.out.println("Barcode is damaged or unreadable");
    System.out.println("Please clean the barcode and try again");
    // Could retry with TRY_HARDER hint

} catch (NotFoundException e) {
    // No barcode found
    System.out.println("No barcode detected");
}

/**
 * Exception thrown when a barcode is found but violates format rules.
 * Indicates:
 * - Barcode pattern was detected
 * - But data structure is invalid for the format
 *
 * Common causes:
 * - Invalid character in barcode data
 * - Incorrect data length for fixed-length formats
 * - Invalid format version or configuration
 * - Corrupted metadata (version info, format info, etc.)
 *
 * Handling: Barcode is fundamentally invalid and cannot be decoded.
 * May indicate incorrectly generated barcode or wrong format assumption.
 */
public final class FormatException extends ReaderException {
    private static final FormatException INSTANCE = new FormatException();

    private FormatException();

    /**
     * Gets the singleton instance (for performance).
     * @return Shared FormatException instance
     */
    public static FormatException getFormatInstance();
}

import com.google.zxing.*;

try {
    Reader reader = new MultiFormatReader();
    Result result = reader.decode(bitmap);

} catch (FormatException e) {
    // Barcode structure is invalid
    System.out.println("Barcode format is invalid");
    System.out.println("This barcode may be incorrectly generated");

} catch (ChecksumException e) {
    // Barcode is damaged
    System.out.println("Barcode is damaged");

} catch (NotFoundException e) {
    // No barcode
    System.out.println("No barcode found");
}

/**
 * Exception thrown when encoding a barcode fails.
 * Indicates:
 * - Input data cannot be encoded in requested format
 * - Configuration parameters are invalid
 * - Data exceeds format capacity
 *
 * Common causes:
 * - Invalid characters for format
 * - Data too long for format/settings
 * - Invalid hint combination
 * - Incorrect format specified
 *
 * Unlike ReaderException, WriterException includes stack traces
 * since encoding failures are less frequent and more critical.
 */
public class WriterException extends Exception {
    /**
     * Creates a WriterException.
     */
    public WriterException();

    /**
     * Creates a WriterException with a message.
     * @param message Error message
     */
    public WriterException(String message);

    /**
     * Creates a WriterException with a cause.
     * @param cause Underlying exception
     */
    public WriterException(Throwable cause);
}

import com.google.zxing.*;

try {
    Writer writer = new QRCodeWriter();
    BitMatrix matrix = writer.encode(
        "Data to encode",
        BarcodeFormat.QR_CODE,
        300,
        300
    );
    // Convert matrix to image...

} catch (WriterException e) {
    // Encoding failed
    System.err.println("Failed to encode barcode: " + e.getMessage());

    // Common causes:
    // - Data too long for format
    // - Invalid characters
    // - Invalid hints

    e.printStackTrace();
}

import com.google.zxing.*;

public Result scanBarcode(BinaryBitmap bitmap) {
    try {
        Reader reader = new MultiFormatReader();
        return reader.decode(bitmap);

    } catch (NotFoundException e) {
        // Normal - no barcode in this frame
        return null;

    } catch (ChecksumException e) {
        // Barcode damaged - might succeed on retry
        System.out.println("Damaged barcode detected");
        return null;

    } catch (FormatException e) {
        // Invalid barcode structure
        System.out.println("Invalid barcode format");
        return null;
    }
}

import com.google.zxing.*;
import java.util.*;

public Result scanWithRetry(BinaryBitmap bitmap) {
    Reader reader = new MultiFormatReader();

    // First attempt - fast
    try {
        return reader.decode(bitmap);
    } catch (NotFoundException e) {
        // Not found - try harder
    } catch (ChecksumException | FormatException e) {
        // Detected but bad - try harder
    }

    // Second attempt - with TRY_HARDER
    try {
        Map<DecodeHintType, Object> hints = new EnumMap<>(DecodeHintType.class);
        hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE);
        return reader.decode(bitmap, hints);

    } catch (NotFoundException | ChecksumException | FormatException e) {
        return null; // Give up
    }
}

import com.google.zxing.*;

public String getUserFriendlyMessage(Exception e) {
    if (e instanceof NotFoundException) {
        return "No barcode found. Please align camera with barcode.";

    } else if (e instanceof ChecksumException) {
        return "Barcode is damaged. Please clean and try again.";

    } else if (e instanceof FormatException) {
        return "Invalid barcode format. This barcode may be incorrectly generated.";

    } else if (e instanceof WriterException) {
        return "Failed to create barcode: " + e.getMessage();

    } else {
        return "Unknown error: " + e.getMessage();
    }
}

import com.google.zxing.*;

public BitMatrix encodeWithValidation(String data, BarcodeFormat format)
        throws WriterException {

    // Validate input
    if (data == null || data.isEmpty()) {
        throw new WriterException("Data cannot be empty");
    }

    // Validate format-specific requirements
    if (format == BarcodeFormat.EAN_13 && !data.matches("\\d{12,13}")) {
        throw new WriterException("EAN-13 requires 12-13 digits");
    }

    try {
        Writer writer = new MultiFormatWriter();
        return writer.encode(data, format, 300, 300);

    } catch (WriterException e) {
        // Add context to error
        throw new WriterException(
            "Failed to encode " + format + ": " + e.getMessage(), e);
    }
}