1 package eu.ehri.project.importers.base;
2
3 import eu.ehri.project.exceptions.ValidationError;
4 import eu.ehri.project.importers.ErrorCallback;
5 import eu.ehri.project.importers.ImportCallback;
6 import eu.ehri.project.models.base.Accessible;
7
8 import java.util.List;
9
10
11 /**
12 * Interface for importers that import documentary units, historical agents and virtual collections,
13 * with their constituent logical data, description(s), and date periods.
14 *
15 * @param <I> Type of node representation that can be imported,
16 * for example, {@code Map<String, Object>}.
17 */
18 public interface ItemImporter<I, T extends Accessible> {
19 /**
20 * Import an item representation into the graph, and return the Node.
21 *
22 * @param itemData the item representation to import
23 * @return the imported node
24 * @throws ValidationError when the item representation does not validate
25 */
26 T importItem(I itemData) throws ValidationError;
27
28 /**
29 * Import an item representation into the graph at a certain depth, and return the Node.
30 *
31 * @param itemData the item representation to import
32 * @param scopeIds parent identifiers for ID generation,
33 * not including permission scope
34 * @return the imported node
35 * @throws ValidationError when the item representation does not validate
36 */
37 T importItem(I itemData, List<String> scopeIds) throws ValidationError;
38
39 /**
40 * Used to indicate a validation error in the
41 * handler for a given element.
42 *
43 * @param ex a validation exception
44 */
45 void handleError(Exception ex);
46
47 /**
48 * Add a callback to run when an item is created.
49 *
50 * @param callback a callback function object
51 */
52 void addCallback(ImportCallback callback);
53
54 /**
55 * Add a callback to run when an item errors.
56 *
57 * @param callback a callback function object
58 */
59 void addErrorCallback(ErrorCallback callback);
60 }