001package com.streamconverter.command;
002
003import com.streamconverter.context.ExecutionContext;
004import java.io.IOException;
005import java.io.InputStream;
006import java.io.OutputStream;
007
008/**
009 * Unified interface for stream commands with optional execution context support.
010 *
011 * <p>This interface defines methods for executing commands on input streams and writing results to
012 * output streams. Commands can optionally utilize ExecutionContext for enhanced logging,
013 * traceability, and multi-threaded context propagation.
014 *
015 * <p>Implementation options:
016 *
017 * <ul>
018 *   <li>Basic commands: Implement only the 2-parameter execute method
019 *   <li>Context-aware commands: Override the 3-parameter execute method for enhanced functionality
020 * </ul>
021 */
022public interface IStreamCommand {
023
024  /**
025   * Executes the command with ExecutionContext support for enhanced traceability.
026   *
027   * <p>This is the primary execution method that supports MDC context propagation, execution
028   * tracking, and enhanced logging capabilities.
029   *
030   * @param inputStream The input stream to read data from.
031   * @param outputStream The output stream to write data to.
032   * @param context The execution context for traceability and logging enhancement.
033   * @throws IOException If an I/O error occurs during the execution of the command.
034   */
035  default void execute(InputStream inputStream, OutputStream outputStream, ExecutionContext context)
036      throws IOException {
037    // Default implementation delegates to the basic execute method for backward compatibility
038    execute(inputStream, outputStream);
039  }
040
041  /**
042   * Executes the command on the provided input stream and writes the result to the output stream.
043   *
044   * <p>This method maintains backward compatibility for existing implementations. When called
045   * without ExecutionContext, a new context will be automatically created by the StreamConverter
046   * pipeline.
047   *
048   * @param inputStream The input stream to read data from.
049   * @param outputStream The output stream to write data to.
050   * @throws IOException If an I/O error occurs during the execution of the command.
051   */
052  void execute(InputStream inputStream, OutputStream outputStream) throws IOException;
053}