001package com.streamconverter.controller;
002
003import com.streamconverter.CommandResult;
004import java.io.IOException;
005import java.io.InputStream;
006import java.io.OutputStream;
007import java.util.List;
008
009/**
010 * Controller interface for stream processing operations.
011 *
012 * <p>This interface defines the contract for controllers that manage the complete lifecycle of
013 * stream processing operations. Controllers are responsible for:
014 *
015 * <ul>
016 *   <li>Configuring and creating appropriate command pipelines based on use cases
017 *   <li>Managing external I/O connections and stream lifecycle
018 *   <li>Orchestrating StreamConverter execution
019 *   <li>Handling errors and providing feedback
020 * </ul>
021 *
022 * <p>The Controller layer sits between external systems and the StreamConverter core, implementing
023 * the ideal architecture:
024 *
025 * <pre>
026 * External Systems → Controller → StreamConverter → Commands
027 * </pre>
028 *
029 * <p>This separation ensures that:
030 *
031 * <ul>
032 *   <li>External systems don't need to know about StreamConverter internals
033 *   <li>Complex command configuration logic is centralized in controllers
034 *   <li>StreamConverter focuses purely on command orchestration
035 *   <li>Commands remain focused on stream transformation logic
036 * </ul>
037 *
038 * @author StreamConverter Team
039 * @version 1.0
040 * @since 1.0
041 */
042public interface IStreamController {
043
044  /**
045   * Processes data from the input stream and writes results to the output stream.
046   *
047   * <p>This method represents the main entry point for stream processing. The controller is
048   * responsible for:
049   *
050   * <ul>
051   *   <li>Analyzing the processing requirements
052   *   <li>Configuring appropriate command pipelines
053   *   <li>Managing StreamConverter lifecycle
054   *   <li>Handling any processing errors
055   * </ul>
056   *
057   * @param inputStream the input stream to read data from
058   * @param outputStream the output stream to write results to
059   * @return list of command execution results for monitoring and debugging
060   * @throws IOException if an I/O error occurs during processing
061   * @throws IllegalArgumentException if input parameters are invalid
062   * @throws IllegalStateException if the controller is not properly configured
063   */
064  List<CommandResult> process(InputStream inputStream, OutputStream outputStream)
065      throws IOException;
066
067  /**
068   * Validates that the controller is properly configured and ready for processing.
069   *
070   * <p>This method should be called before attempting to process streams to ensure all required
071   * configuration is in place.
072   *
073   * @return true if the controller is ready for processing, false otherwise
074   */
075  boolean isConfigured();
076
077  /**
078   * Gets a human-readable description of the controller's configuration.
079   *
080   * <p>This method provides information about the controller's current state, configured commands,
081   * and processing capabilities. Useful for debugging and monitoring.
082   *
083   * @return description of the controller configuration
084   */
085  String getConfigurationDescription();
086
087  /**
088   * Gets the expected input data type that this controller can handle.
089   *
090   * <p>This information can be used by external systems to route data to appropriate controllers.
091   *
092   * @return the expected input data type (e.g., "CSV", "JSON", "XML", "BINARY")
093   */
094  String getInputDataType();
095
096  /**
097   * Gets the output data type that this controller produces.
098   *
099   * <p>This information helps external systems understand what type of data to expect from the
100   * processing.
101   *
102   * @return the output data type (e.g., "CSV", "JSON", "XML", "BINARY")
103   */
104  String getOutputDataType();
105}