spring_batch_rs/item/json/
mod.rs

1/// JSON support for reading and writing structured data.
2///
3/// This module provides components for reading JSON data from various sources and writing data to JSON output.
4/// The implementation uses `serde_json` for efficient JSON parsing and serialization.
5///
6/// # Module Architecture
7///
8/// The JSON module consists of two main components:
9///
10/// 1. **JsonItemReader**: A streaming JSON reader that can efficiently process large JSON arrays
11///    by reading and deserializing objects one at a time without loading the entire file into memory.
12///    It works by parsing the JSON buffer character by character, tracking nesting levels, and
13///    identifying complete JSON objects.
14///
15/// 2. **JsonItemWriter**: A JSON writer that serializes items into JSON format and writes them as
16///    a properly formatted JSON array. It handles opening and closing array brackets, adding commas
17///    between items, and supports both compact and pretty-printed output.
18///
19/// Each component follows the builder pattern for easy configuration.
20///
21/// # Features
22///
23/// - Read JSON data from files, strings, or any source implementing the `Read` trait
24/// - Write data to JSON files with configurable formatting options
25/// - Seamless integration with Serde for serialization and deserialization
26/// - Support for both compact and pretty-printed JSON output
27/// - Memory-efficient streaming processing for large datasets
28///
29/// # Examples
30///
31/// ## Reading from JSON
32///
33/// ```
34/// use spring_batch_rs::item::json::json_reader::JsonItemReaderBuilder;
35/// use spring_batch_rs::core::item::ItemReader;
36/// use serde::Deserialize;
37/// use std::io::Cursor;
38///
39/// // Define a data structure matching our JSON format
40/// #[derive(Debug, Deserialize, PartialEq)]
41/// struct User {
42///     id: u64,
43///     name: String,
44///     email: String,
45///     active: bool,
46/// }
47///
48/// // Sample JSON data
49/// let json_data = r#"[
50///   {
51///     "id": 1,
52///     "name": "AliceJohnson",
53///     "email": "alice@example.com",
54///     "active": true
55///   },
56///   {
57///     "id": 2,
58///     "name": "BobSmith",
59///     "email": "bob@example.com",
60///     "active": false
61///   }
62/// ]"#;
63///
64/// // Create a reader from our JSON
65/// let cursor = Cursor::new(json_data);
66/// let reader = JsonItemReaderBuilder::<User>::new()
67///     .capacity(1024)
68///     .from_reader(cursor);
69///
70/// // Read and process the users
71/// let mut users = Vec::new();
72/// while let Some(user) = reader.read().unwrap() {
73///     users.push(user);
74/// }
75///
76/// // Verify results
77/// assert_eq!(users.len(), 2);
78/// assert_eq!(users[0].id, 1);
79/// assert_eq!(users[0].name, "AliceJohnson");
80/// assert_eq!(users[0].email, "alice@example.com");
81/// assert_eq!(users[0].active, true);
82///
83/// assert_eq!(users[1].id, 2);
84/// assert_eq!(users[1].name, "BobSmith");
85/// assert_eq!(users[1].email, "bob@example.com");
86/// assert_eq!(users[1].active, false);
87/// ```
88///
89/// ## Writing to JSON
90///
91/// ```
92/// use spring_batch_rs::item::json::json_writer::JsonItemWriterBuilder;
93/// use spring_batch_rs::core::item::ItemWriter;
94/// use serde::Serialize;
95/// use std::io::Cursor;
96///
97/// // Define a data structure for serialization
98/// #[derive(Serialize)]
99/// struct User {
100///     id: u64,
101///     name: String,
102///     email: String,
103///     role: String,
104///     skills: Vec<String>,
105/// }
106///
107/// // Create some users
108/// let users = vec![
109///     User {
110///         id: 1,
111///         name: "Alice Johnson".to_string(),
112///         email: "alice@example.com".to_string(),
113///         role: "Developer".to_string(),
114///         skills: vec!["Rust".to_string(), "Python".to_string()],
115///     },
116///     User {
117///         id: 2,
118///         name: "Bob Smith".to_string(),
119///         email: "bob@example.com".to_string(),
120///         role: "Designer".to_string(),
121///         skills: vec!["UI".to_string(), "UX".to_string(), "Figma".to_string()],
122///     },
123/// ];
124///
125/// // Create a writer with a memory buffer and pretty formatting
126/// let buffer = Cursor::new(Vec::new());
127/// let writer = JsonItemWriterBuilder::<User>::new()
128///     .pretty_formatter(true)
129///     .from_writer(buffer);
130///
131/// // Write the users to JSON
132/// let writer_ref = &writer as &dyn ItemWriter<User>;
133/// writer_ref.open().unwrap();
134/// writer_ref.write(&users).unwrap();
135/// writer_ref.close().unwrap();
136///
137/// // The resulting JSON would look similar to:
138/// // [
139/// //   {
140/// //     "id": 1,
141/// //     "name": "Alice Johnson",
142/// //     "email": "alice@example.com",
143/// //     "role": "Developer",
144/// //     "skills": [
145/// //       "Rust",
146/// //       "Python"
147/// //     ]
148/// //   },
149/// //   {
150/// //     "id": 2,
151/// //     "name": "Bob Smith",
152/// //     "email": "bob@example.com",
153/// //     "role": "Designer",
154/// //     "skills": [
155/// //       "UI",
156/// //       "UX",
157/// //       "Figma"
158/// //     ]
159/// //   }
160/// // ]
161/// ```
162/// A module providing facilities for reading JSON data records.
163pub mod json_reader;
164/// The `json_writer` module contains the `JsonItemWriter` struct, which is the main entry point for writing items to a JSON data source.
165/// It implements the `ItemWriter` trait and provides methods for serializing Rust structs into JSON and writing them to a data source.
166pub mod json_writer;
167
168// Re-export the main types for easier access
169pub use json_reader::{JsonItemReader, JsonItemReaderBuilder};
170pub use json_writer::{JsonItemWriter, JsonItemWriterBuilder};
spring_batch_rs/item/json/mod.rs

spring_batch_rs/item/json/
mod.rs
