001package com.streamconverter.examples.docs;
002
003import com.streamconverter.CommandResult;
004import com.streamconverter.StreamConverter;
005import com.streamconverter.command.IStreamCommand;
006import com.streamconverter.command.impl.LineEndingNormalizeCommand;
007import com.streamconverter.command.impl.LineEndingNormalizeCommand.LineEndingType;
008import com.streamconverter.command.impl.SampleStreamCommand;
009import com.streamconverter.command.impl.charcode.CharacterConvertCommand;
010import com.streamconverter.command.impl.csv.CsvFilterCommand;
011import com.streamconverter.command.impl.csv.CsvNavigateCommand;
012import com.streamconverter.command.impl.json.JsonNavigateCommand;
013import com.streamconverter.command.impl.xml.XmlNavigateCommand;
014import com.streamconverter.command.rule.PassThroughRule;
015import com.streamconverter.path.CSVPath;
016import com.streamconverter.path.TreePath;
017import java.io.ByteArrayInputStream;
018import java.io.ByteArrayOutputStream;
019import java.io.InputStream;
020import java.io.OutputStream;
021import java.nio.charset.StandardCharsets;
022import java.util.List;
023
024/**
025 * Verifiable code examples for StreamConverter documentation.
026 *
027 * <p>This class contains actual, compilable, and runnable code examples that are referenced from
028 * documentation. Each example is marked with START/END comments for potential extraction into
029 * documentation.
030 *
031 * <p>All examples in this file are tested to ensure they compile and execute correctly.
032 */
033public class BasicUsageExamples {
034
035  // [START csv-navigate-basic]
036  /**
037   * CSV navigation pipeline example - demonstrates pipeline structure with CSV column navigation.
038   * Note: Uses PassThroughRule (no transformation) and SampleStreamCommand (placeholder for actual
039   * processing).
040   */
041  public void csvNavigateBasic() throws Exception {
042    // Sample CSV data
043    String csvData = "id,productName,price\n" + "1,Apple,100\n" + "2,Banana,50\n";
044    InputStream inputStream = new ByteArrayInputStream(csvData.getBytes(StandardCharsets.UTF_8));
045    OutputStream outputStream = new ByteArrayOutputStream();
046
047    // Create pipeline: navigate CSV + process
048    IStreamCommand[] pipeline = {
049      new CsvNavigateCommand(new CSVPath("productName"), new PassThroughRule()),
050      new SampleStreamCommand("csv-processor")
051    };
052
053    StreamConverter converter = StreamConverter.create(pipeline);
054    List<CommandResult> results = converter.run(inputStream, outputStream);
055
056    // Verify execution
057    boolean success = results.stream().allMatch(CommandResult::isSuccess);
058    if (!success) {
059      throw new RuntimeException("CSV navigation failed");
060    }
061  }
062
063  // [END csv-navigate-basic]
064
065  // [START csv-filter-basic]
066  /**
067   * CSV filter pipeline example - demonstrates column extraction in a pipeline. Note:
068   * SampleStreamCommand is a placeholder for actual processing logic.
069   */
070  public void csvFilterBasic() throws Exception {
071    String csvData = "id,name,price\n" + "1,Apple,100\n" + "2,Banana,50\n";
072    InputStream inputStream = new ByteArrayInputStream(csvData.getBytes(StandardCharsets.UTF_8));
073    OutputStream outputStream = new ByteArrayOutputStream();
074
075    // Create pipeline: filter CSV + process
076    IStreamCommand[] pipeline = {
077      CsvFilterCommand.create(new CSVPath("price")), new SampleStreamCommand("filter-processor")
078    };
079
080    StreamConverter converter = StreamConverter.create(pipeline);
081    List<CommandResult> results = converter.run(inputStream, outputStream);
082
083    boolean success = results.stream().allMatch(CommandResult::isSuccess);
084    if (!success) {
085      throw new RuntimeException("CSV filter failed");
086    }
087  }
088
089  // [END csv-filter-basic]
090
091  // [START json-navigate-basic]
092  /**
093   * JSON navigation pipeline example - demonstrates pipeline structure with JSON path navigation.
094   * Note: Uses PassThroughRule (no transformation) and SampleStreamCommand (placeholder for actual
095   * processing).
096   */
097  public void jsonNavigateBasic() throws Exception {
098    String jsonData = "{\"user\": {\"name\": \"John\", \"age\": 30}}";
099    InputStream inputStream = new ByteArrayInputStream(jsonData.getBytes(StandardCharsets.UTF_8));
100    OutputStream outputStream = new ByteArrayOutputStream();
101
102    // Create pipeline: navigate JSON + process
103    IStreamCommand[] pipeline = {
104      new JsonNavigateCommand(TreePath.fromJson("$.user.name"), new PassThroughRule()),
105      new SampleStreamCommand("json-processor")
106    };
107
108    StreamConverter converter = StreamConverter.create(pipeline);
109    List<CommandResult> results = converter.run(inputStream, outputStream);
110
111    boolean success = results.stream().allMatch(CommandResult::isSuccess);
112    if (!success) {
113      throw new RuntimeException("JSON navigation failed");
114    }
115  }
116
117  // [END json-navigate-basic]
118
119  // [START xml-navigate-basic]
120  /**
121   * XML navigation pipeline example - demonstrates pipeline structure with XML path navigation.
122   * Note: Uses PassThroughRule (no transformation) and SampleStreamCommand (placeholder for actual
123   * processing).
124   */
125  public void xmlNavigateBasic() throws Exception {
126    String xmlData = "<?xml version=\"1.0\"?><root><user><name>John</name></user></root>";
127    InputStream inputStream = new ByteArrayInputStream(xmlData.getBytes(StandardCharsets.UTF_8));
128    OutputStream outputStream = new ByteArrayOutputStream();
129
130    // Create pipeline: navigate XML + process
131    IStreamCommand[] pipeline = {
132      new XmlNavigateCommand(TreePath.fromXml("root/user/name"), new PassThroughRule()),
133      new SampleStreamCommand("xml-processor")
134    };
135
136    StreamConverter converter = StreamConverter.create(pipeline);
137    List<CommandResult> results = converter.run(inputStream, outputStream);
138
139    boolean success = results.stream().allMatch(CommandResult::isSuccess);
140    if (!success) {
141      throw new RuntimeException("XML navigation failed");
142    }
143  }
144
145  // [END xml-navigate-basic]
146
147  // [START character-convert-basic]
148  /**
149   * Character encoding conversion pipeline example - demonstrates charset conversion in a pipeline.
150   * Note: SampleStreamCommand is a placeholder for actual processing logic.
151   */
152  public void characterConvertBasic() throws Exception {
153    String data = "Hello World";
154    InputStream inputStream = new ByteArrayInputStream(data.getBytes("Shift_JIS"));
155    OutputStream outputStream = new ByteArrayOutputStream();
156
157    // Create pipeline: convert encoding + process
158    IStreamCommand[] pipeline = {
159      new CharacterConvertCommand("Shift_JIS", "UTF-8"),
160      new SampleStreamCommand("encoding-processor")
161    };
162
163    StreamConverter converter = StreamConverter.create(pipeline);
164    List<CommandResult> results = converter.run(inputStream, outputStream);
165
166    boolean success = results.stream().allMatch(CommandResult::isSuccess);
167    if (!success) {
168      throw new RuntimeException("Character conversion failed");
169    }
170  }
171
172  // [END character-convert-basic]
173
174  // [START line-ending-normalize-basic]
175  /**
176   * Line ending normalization pipeline example - demonstrates line ending conversion in a pipeline.
177   * Note: SampleStreamCommand is a placeholder for actual processing logic.
178   */
179  public void lineEndingNormalizeBasic() throws Exception {
180    String data = "Line 1\r\nLine 2\rLine 3\n";
181    InputStream inputStream = new ByteArrayInputStream(data.getBytes(StandardCharsets.UTF_8));
182    OutputStream outputStream = new ByteArrayOutputStream();
183
184    // Create pipeline: normalize line endings + process
185    IStreamCommand[] pipeline = {
186      new LineEndingNormalizeCommand(LineEndingType.UNIX), new SampleStreamCommand("line-processor")
187    };
188
189    StreamConverter converter = StreamConverter.create(pipeline);
190    List<CommandResult> results = converter.run(inputStream, outputStream);
191
192    boolean success = results.stream().allMatch(CommandResult::isSuccess);
193    if (!success) {
194      throw new RuntimeException("Line ending normalization failed");
195    }
196  }
197
198  // [END line-ending-normalize-basic]
199
200  // [START pipeline-simple]
201  /** Simple pipeline example - chaining multiple commands. */
202  public void simplePipeline() throws Exception {
203    String csvData = "id,name,price\n1,Apple,100\n";
204    InputStream inputStream = new ByteArrayInputStream(csvData.getBytes("Shift_JIS"));
205    OutputStream outputStream = new ByteArrayOutputStream();
206
207    // CSV → Character conversion → Output
208    IStreamCommand[] pipeline = {
209      new CsvNavigateCommand(new CSVPath("name"), new PassThroughRule()),
210      new CharacterConvertCommand("Shift_JIS", "UTF-8")
211    };
212
213    StreamConverter converter = StreamConverter.create(pipeline);
214    List<CommandResult> results = converter.run(inputStream, outputStream);
215
216    boolean success = results.stream().allMatch(CommandResult::isSuccess);
217    if (!success) {
218      throw new RuntimeException("Pipeline execution failed");
219    }
220  }
221
222  // [END pipeline-simple]
223
224  // [START error-handling-basic]
225  /**
226   * Error handling pipeline example - demonstrates CommandResult usage for error detection. Note:
227   * SampleStreamCommand is a placeholder for actual processing logic.
228   */
229  public void errorHandlingBasic() throws Exception {
230    String csvData = "id,name\n1,Apple\n";
231    InputStream inputStream = new ByteArrayInputStream(csvData.getBytes(StandardCharsets.UTF_8));
232    OutputStream outputStream = new ByteArrayOutputStream();
233
234    // Create pipeline for error handling demonstration
235    IStreamCommand[] pipeline = {
236      new CsvNavigateCommand(new CSVPath("name"), new PassThroughRule()),
237      new SampleStreamCommand("error-handler")
238    };
239
240    StreamConverter converter = StreamConverter.create(pipeline);
241    List<CommandResult> results = converter.run(inputStream, outputStream);
242
243    // Check results
244    for (CommandResult result : results) {
245      if (!result.isSuccess()) {
246        System.err.println("Command failed: " + result.getCommandName());
247        System.err.println("Error: " + result.getErrorMessage());
248      } else {
249        System.out.println(
250            "Success: "
251                + result.getCommandName()
252                + " (duration: "
253                + result.getExecutionTimeMillis()
254                + "ms)");
255      }
256    }
257  }
258  // [END error-handling-basic]
259}