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 *
022 * <p>This is a functional interface and can be implemented using lambda expressions or method
023 * references for simple stream processing operations.
024 *
025 * <p>Usage examples:
026 *
027 * <pre>{@code
028 * // Simple copy operation (IOException is propagated from execute method signature)
029 * IStreamCommand copyCommand = (in, out) -> in.transferTo(out);
030 *
031 * // Buffered stream processing with custom logic
032 * IStreamCommand bufferCommand = (in, out) -> {
033 *     byte[] buffer = new byte[8192];
034 *     int len;
035 *     while ((len = in.read(buffer)) != -1) {
036 *         out.write(buffer, 0, len);
037 *     }
038 * };
039 *
040 * // Using in StreamConverter pipeline
041 * StreamConverter converter = StreamConverter.create(copyCommand);
042 * converter.run(inputStream, outputStream);
043 * }</pre>
044 */
045@FunctionalInterface
046public interface IStreamCommand {
047
048  /**
049   * Executes the command with ExecutionContext support for enhanced traceability.
050   *
051   * <p>This is the primary execution method that supports MDC context propagation, execution
052   * tracking, and enhanced logging capabilities.
053   *
054   * @param inputStream The input stream to read data from.
055   * @param outputStream The output stream to write data to.
056   * @param context The execution context for traceability and logging enhancement.
057   * @throws IOException If an I/O error occurs during the execution of the command.
058   */
059  default void execute(InputStream inputStream, OutputStream outputStream, ExecutionContext context)
060      throws IOException {
061    // Default implementation delegates to the basic execute method for backward compatibility
062    execute(inputStream, outputStream);
063  }
064
065  /**
066   * Executes the command on the provided input stream and writes the result to the output stream.
067   *
068   * <p>This method maintains backward compatibility for existing implementations. When called
069   * without ExecutionContext, a new context will be automatically created by the StreamConverter
070   * pipeline.
071   *
072   * @param inputStream The input stream to read data from.
073   * @param outputStream The output stream to write data to.
074   * @throws IOException If an I/O error occurs during the execution of the command.
075   */
076  void execute(InputStream inputStream, OutputStream outputStream) throws IOException;
077}