1 /*
2 * Copyright 2015 Data Archiving and Networked Services (an institute of
3 * Koninklijke Nederlandse Akademie van Wetenschappen), King's College London,
4 * Georg-August-Universitaet Goettingen Stiftung Oeffentlichen Rechts
5 *
6 * Licensed under the EUPL, Version 1.1 or – as soon they will be approved by
7 * the European Commission - subsequent versions of the EUPL (the "Licence");
8 * You may not use this work except in compliance with the Licence.
9 * You may obtain a copy of the Licence at:
10 *
11 * https://joinup.ec.europa.eu/software/page/eupl
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the Licence is distributed on an "AS IS" basis,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the Licence for the specific language governing
17 * permissions and limitations under the Licence.
18 */
19
20 package eu.ehri.project.importers.managers;
21
22 import eu.ehri.project.exceptions.ValidationError;
23 import eu.ehri.project.importers.ImportLog;
24 import eu.ehri.project.importers.exceptions.InputParseError;
25 import org.apache.commons.compress.archivers.ArchiveInputStream;
26
27 import java.io.IOException;
28 import java.io.InputStream;
29 import java.util.List;
30
31 /**
32 * An Import Manager takes a single file or stream, or a list of files, and a log message
33 * and imports the data from the file into the database,
34 * linking the import as an action with the given log message.
35 */
36 public interface ImportManager {
37
38 /**
39 * Import a file by specifying its path.
40 *
41 * @param filePath path to the file to import
42 * @param logMessage an optional message to describe the import
43 * @return an ImportLog for the given file
44 * @throws IOException when reading or writing files fails
45 * @throws InputParseError when parsing the file fails
46 * @throws ValidationError when the content of the file is invalid
47 */
48 ImportLog importFile(String filePath, String logMessage)
49 throws IOException, InputParseError, ValidationError;
50
51 /**
52 * Import an item via an input stream.
53 *
54 * @param stream the input stream
55 * @param logMessage an optional log message to describe the import
56 * @return an ImportLog for the given stream
57 * @throws IOException when reading or writing fails
58 * @throws InputParseError when parsing the stream data fails
59 * @throws ValidationError when the content of the file is invalid
60 */
61 default ImportLog importInputStream(InputStream stream, String logMessage)
62 throws IOException, InputParseError, ValidationError {
63 return importInputStream(stream, null, logMessage);
64 }
65
66 /**
67 * Import an item via an input stream.
68 *
69 * @param stream the input stream
70 * @param tag an optional tag identifying the source of the stream
71 * @param logMessage an optional log message to describe the import
72 * @return an ImportLog for the given stream
73 * @throws IOException when reading or writing fails
74 * @throws InputParseError when parsing the stream data fails
75 * @throws ValidationError when the content of the file is invalid
76 */
77 ImportLog importInputStream(InputStream stream, String tag, String logMessage)
78 throws IOException, InputParseError, ValidationError;
79
80 /**
81 * Import multiple files via a list of file paths.
82 *
83 * @param filePaths a list of file paths
84 * @param logMessage an optional log message to describe the import
85 * @return an ImportLog for the given stream
86 * @throws IOException when reading or writing fails
87 * @throws InputParseError when parsing the stream data fails
88 * @throws ValidationError when the content of the file is invalid
89 */
90 ImportLog importFiles(List<String> filePaths, String logMessage)
91 throws IOException, InputParseError, ValidationError;
92
93 /**
94 * Import multiple items via an archive input stream.
95 *
96 * @param stream the archive input stream
97 * @param logMessage an optional log message to describe the import
98 * @return an ImportLog for the given stream
99 * @throws IOException when reading or writing fails
100 * @throws InputParseError when parsing the stream data fails
101 * @throws ValidationError when the content of the file is invalid
102 */
103 ImportLog importArchive(ArchiveInputStream stream, String logMessage)
104 throws IOException, InputParseError, ValidationError;
105 }