Package org.apache.juneau.commons.function

Interface BeanSupplier<T>

Type Parameters:
T - The type of bean provided by this supplier.
All Superinterfaces:
Iterable<T>
All Known Subinterfaces:
BeanChannel<T>
All Known Implementing Classes:
ListBeanChannel
public interface BeanSupplier<T> extends Iterable<T>
A lifecycle-aware producer for use as a serializer source, providing beans lazily one at a time.

Extends Iterable so that ClassMeta's existing ITERABLE category picks it up automatically — no new type category is needed in the framework.

The serializer drives the full lifecycle:

  1. Calls begin() before iteration starts
  2. Iterates elements via Iterable.iterator(), serializing each
  3. If an exception occurs during iteration, calls onError(Exception)
  4. Always calls complete() after iteration (like finally) — whether serialization succeeded or failed. Use this for resource cleanup (close cursors, connections, etc.)

For round-trip support (same property used for both serialization and parsing), use BeanChannel instead, which extends both BeanSupplier and BeanConsumer.

If a BeanSupplier is encountered during parsing (not serialization), the parser will throw an IllegalArgumentException with a message recommending BeanConsumer or BeanChannel.

Example (DB-backed supplier via JDBC cursor):

@Marshalled(factory=ItemSupplierFactory.class) public class ItemSupplier implements BeanSupplier<Item> { private Connection conn; private ResultSet rs; @Override public void begin() throws Exception { conn = ds.getConnection(); rs = conn.prepareStatement("SELECT * FROM items").executeQuery(); } @Override public Iterator<Item> iterator() { return new ResultSetIterator<>(rs, Item::fromRow); } @Override public void onError(Exception e) throws Exception { rs.close(); throw e; } @Override public void complete() throws Exception { rs.close(); conn.close(); } }

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    begin()
    Called before iteration starts.
    default void
    complete()
    Always called after iteration ends (like finally).
    default void
    onError(Exception e)
    Called when an exception occurs during iteration.

    Methods inherited from interface java.lang.Iterable

    forEach, iterator, spliterator

  • Method Details

    • begin

      default void begin() throws Exception
      Called before iteration starts.

      Use this to open database connections, execute queries, or perform other setup.

      Throws:
      Exception - If setup fails.

    • complete

      default void complete() throws Exception
      Always called after iteration ends (like finally).

      Use this to close database cursors, connections, or release other resources. This method is called whether serialization succeeded or onError(Exception) rethrew.

      Throws:
      Exception - If cleanup fails.

    • onError

      default void onError(Exception e) throws Exception
      Called when an exception occurs during iteration.

      The default implementation rethrows the exception, stopping serialization immediately. Note that complete() is always called afterward regardless.

      Parameters:
      e - The exception that occurred during iteration.
      Throws:
      Exception - If the error cannot be recovered from. Rethrow e to stop serialization.