sz_rust_sdk/
traits.rs

1//! Core traits defining the Senzing SDK interface
2//!
3//! This module contains the main trait definitions that mirror the C# SDK interfaces.
4//! These traits define the contract for interacting with the Senzing engine.
5
6use crate::{error::SzResult, flags::SzFlags, types::*};
7use std::collections::HashSet;
8
9/// Main entry point and factory for Senzing SDK components
10///
11/// The `SzEnvironment` trait provides the primary interface for initializing
12/// the Senzing SDK and obtaining instances of other SDK components.
13pub trait SzEnvironment {
14    /// Destroys the environment and releases all resources
15    fn destroy(&mut self) -> SzResult<()>;
16
17    /// Checks if the environment has been destroyed
18    fn is_destroyed(&self) -> bool;
19
20    /// Reinitializes the environment with a specific configuration
21    /// Note: Sz_reinit is thread-safe, so this doesn't require a mutable reference
22    fn reinitialize(&self, config_id: ConfigId) -> SzResult<()>;
23
24    /// Gets the currently active configuration ID
25    fn get_active_config_id(&self) -> SzResult<ConfigId>;
26
27    /// Gets the product interface instance
28    fn get_product(&self) -> SzResult<Box<dyn SzProduct>>;
29
30    /// Gets the engine interface instance
31    fn get_engine(&self) -> SzResult<Box<dyn SzEngine>>;
32
33    /// Gets the configuration manager interface instance
34    fn get_config_manager(&self) -> SzResult<Box<dyn SzConfigManager>>;
35
36    /// Gets the diagnostic interface instance
37    fn get_diagnostic(&self) -> SzResult<Box<dyn SzDiagnostic>>;
38}
39
40/// Core entity resolution engine operations
41///
42/// The `SzEngine` trait provides methods for adding records, retrieving entities,
43/// performing searches, and conducting various types of analysis.
44pub trait SzEngine {
45    /// Primes the engine for optimal performance
46    fn prime_engine(&self) -> SzResult<()>;
47
48    /// Gets engine statistics
49    fn get_stats(&self) -> SzResult<JsonString>;
50
51    /// Adds a record for entity resolution
52    fn add_record(
53        &self,
54        data_source_code: &str,
55        record_id: &str,
56        record_definition: &str,
57        flags: Option<SzFlags>,
58    ) -> SzResult<JsonString>;
59
60    /// Gets a preview of how a record would be processed
61    fn get_record_preview(
62        &self,
63        record_definition: &str,
64        flags: Option<SzFlags>,
65    ) -> SzResult<JsonString>;
66
67    /// Deletes a record from the entity repository
68    fn delete_record(
69        &self,
70        data_source_code: &str,
71        record_id: &str,
72        flags: Option<SzFlags>,
73    ) -> SzResult<JsonString>;
74
75    /// Reevaluates a specific record
76    fn reevaluate_record(
77        &self,
78        data_source_code: &str,
79        record_id: &str,
80        flags: Option<SzFlags>,
81    ) -> SzResult<JsonString>;
82
83    /// Reevaluates all records for a specific entity
84    fn reevaluate_entity(
85        &self,
86        entity_id: EntityId,
87        flags: Option<SzFlags>,
88    ) -> SzResult<JsonString>;
89
90    /// Searches for entities by attributes
91    fn search_by_attributes(
92        &self,
93        attributes: &str,
94        search_profile: Option<&str>,
95        flags: Option<SzFlags>,
96    ) -> SzResult<JsonString>;
97
98    /// Analyzes why a search result was returned for an entity
99    fn why_search(
100        &self,
101        attributes: &str,
102        entity_id: EntityId,
103        search_profile: Option<&str>,
104        flags: Option<SzFlags>,
105    ) -> SzResult<JsonString>;
106
107    /// Gets entity information by entity ID
108    fn get_entity(&self, entity_id: EntityId, flags: Option<SzFlags>) -> SzResult<JsonString>;
109
110    /// Gets entity information by record identifier
111    fn get_entity_by_record(
112        &self,
113        data_source_code: &str,
114        record_id: &str,
115        flags: Option<SzFlags>,
116    ) -> SzResult<JsonString>;
117
118    /// Gets record information
119    fn get_record(
120        &self,
121        data_source_code: &str,
122        record_id: &str,
123        flags: Option<SzFlags>,
124    ) -> SzResult<JsonString>;
125
126    /// Finds interesting entities related to a given entity
127    fn find_interesting_entities_by_entity_id(
128        &self,
129        entity_id: EntityId,
130        flags: Option<SzFlags>,
131    ) -> SzResult<JsonString>;
132
133    /// Finds interesting entities related to a given record
134    fn find_interesting_entities_by_record(
135        &self,
136        data_source_code: &str,
137        record_id: &str,
138        flags: Option<SzFlags>,
139    ) -> SzResult<JsonString>;
140
141    /// Finds a path between two entities
142    fn find_path(
143        &self,
144        start_entity_id: EntityId,
145        end_entity_id: EntityId,
146        max_degrees: i64,
147        avoid_entity_ids: Option<&HashSet<EntityId>>,
148        required_data_sources: Option<&HashSet<String>>,
149        flags: Option<SzFlags>,
150    ) -> SzResult<JsonString>;
151
152    /// Finds a network of entities
153    fn find_network(
154        &self,
155        entity_list: &[EntityId],
156        max_degrees: i64,
157        build_out_degree: i64,
158        max_entities: i64,
159        flags: Option<SzFlags>,
160    ) -> SzResult<JsonString>;
161
162    /// Analyzes why two entities resolved together
163    fn why_entity(
164        &self,
165        entity_id1: EntityId,
166        entity_id2: EntityId,
167        flags: Option<SzFlags>,
168    ) -> SzResult<JsonString>;
169
170    /// Analyzes why two records resolved together
171    fn why_records(
172        &self,
173        data_source_code1: &str,
174        record_id1: &str,
175        data_source_code2: &str,
176        record_id2: &str,
177        flags: Option<SzFlags>,
178    ) -> SzResult<JsonString>;
179
180    /// Analyzes why a record is in an entity
181    fn why_record_in_entity(
182        &self,
183        data_source_code: &str,
184        record_id: &str,
185        flags: Option<SzFlags>,
186    ) -> SzResult<JsonString>;
187
188    /// Analyzes how an entity was resolved
189    fn how_entity(&self, entity_id: EntityId, flags: Option<SzFlags>) -> SzResult<JsonString>;
190
191    /// Gets a virtual entity based on record definitions
192    fn get_virtual_entity(
193        &self,
194        record_keys: &[(String, String)],
195        flags: Option<SzFlags>,
196    ) -> SzResult<JsonString>;
197
198    /// Processes a redo record
199    fn process_redo_record(
200        &self,
201        redo_record: &str,
202        flags: Option<SzFlags>,
203    ) -> SzResult<JsonString>;
204
205    /// Gets the next redo record
206    fn get_redo_record(&self) -> SzResult<JsonString>;
207
208    /// Counts the number of redo records
209    fn count_redo_records(&self) -> SzResult<i64>;
210
211    /// Exports entity data
212    fn export_json_entity_report(&self, flags: Option<SzFlags>) -> SzResult<ExportHandle>;
213
214    /// Exports CSV entity report
215    fn export_csv_entity_report(
216        &self,
217        csv_column_list: &str,
218        flags: Option<SzFlags>,
219    ) -> SzResult<ExportHandle>;
220
221    /// Fetches the next batch of export data
222    fn fetch_next(&self, export_handle: ExportHandle) -> SzResult<JsonString>;
223
224    /// Closes an export operation
225    fn close_export(&self, export_handle: ExportHandle) -> SzResult<()>;
226}
227
228/// Configuration management operations
229///
230/// The `SzConfig` trait provides methods for managing Senzing configuration data.
231pub trait SzConfig {
232    /// Exports the complete configuration as JSON
233    fn export(&self) -> SzResult<JsonString>;
234
235    /// Gets the data source registry
236    fn get_data_source_registry(&self) -> SzResult<JsonString>;
237
238    /// Registers a new data source
239    fn register_data_source(&self, data_source_code: &str) -> SzResult<JsonString>;
240
241    /// Removes a data source from the configuration
242    fn unregister_data_source(&self, data_source_code: &str) -> SzResult<()>;
243}
244
245/// Configuration lifecycle management
246///
247/// The `SzConfigManager` trait provides methods for managing configuration
248/// versions, registration, and deployment.
249pub trait SzConfigManager {
250    /// Creates a new configuration instance
251    fn create_config(&self) -> SzResult<Box<dyn SzConfig>>;
252
253    /// Creates a configuration from an existing configuration ID
254    fn create_config_from_id(&self, config_id: ConfigId) -> SzResult<Box<dyn SzConfig>>;
255
256    /// Creates a configuration from a JSON definition
257    fn create_config_from_definition(&self, config_definition: &str)
258    -> SzResult<Box<dyn SzConfig>>;
259
260    /// Gets the configuration registry
261    fn get_config_registry(&self) -> SzResult<JsonString>;
262
263    /// Gets the default configuration ID
264    fn get_default_config_id(&self) -> SzResult<ConfigId>;
265
266    /// Registers a new configuration
267    fn register_config(
268        &self,
269        config_definition: &str,
270        config_comment: Option<&str>,
271    ) -> SzResult<ConfigId>;
272
273    /// Replaces the default configuration ID
274    fn replace_default_config_id(
275        &self,
276        current_default_config_id: ConfigId,
277        new_default_config_id: ConfigId,
278    ) -> SzResult<()>;
279
280    /// Sets a new default configuration from definition
281    fn set_default_config(
282        &self,
283        config_definition: &str,
284        config_comment: Option<&str>,
285    ) -> SzResult<ConfigId>;
286
287    /// Sets the default configuration ID
288    fn set_default_config_id(&self, config_id: ConfigId) -> SzResult<()>;
289}
290
291/// System diagnostics and monitoring
292///
293/// The `SzDiagnostic` trait provides methods for system health monitoring,
294/// performance analysis, and repository maintenance.
295pub trait SzDiagnostic {
296    /// Runs a performance test for the specified duration
297    fn check_repository_performance(&self, seconds_to_run: i64) -> SzResult<JsonString>;
298
299    /// Gets feature information by feature ID
300    fn get_feature(&self, feature_id: FeatureId) -> SzResult<JsonString>;
301
302    /// Gets repository information and statistics
303    fn get_repository_info(&self) -> SzResult<JsonString>;
304
305    /// Purges all data from the repository (configuration remains)
306    fn purge_repository(&self) -> SzResult<()>;
307}
308
309/// Product version and license information
310///
311/// The `SzProduct` trait provides methods for retrieving product version
312/// and licensing information.
313pub trait SzProduct {
314    /// Gets the product license details
315    fn get_license(&self) -> SzResult<JsonString>;
316
317    /// Gets the product version information
318    fn get_version(&self) -> SzResult<JsonString>;
319}
sz_rust_sdk/traits.rs

sz_rust_sdk/
traits.rs
