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}