1 /*
2 * dpkg - Debian Package library and the Debian Package Maven plugin
3 * (c) Copyright 2016 Gerrit Hohl
4 *
5 * This program is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU General Public License
7 * as published by the Free Software Foundation; either version 2
8 * of the License, or (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 */
19 package net.sourceforge.javadpkg.store;
20
21 import java.io.IOException;
22 import java.security.MessageDigest;
23 import java.util.List;
24
25 import org.apache.commons.compress.archivers.tar.TarArchiveOutputStream;
26
27 import net.sourceforge.javadpkg.control.Size;
28 import net.sourceforge.javadpkg.io.DataSource;
29 import net.sourceforge.javadpkg.io.FileMode;
30 import net.sourceforge.javadpkg.io.FileOwner;
31
32 /**
33 * <p>
34 * A store for managing the files in the data archive of a Debian package.
35 * </p>
36 *
37 * @author Gerrit Hohl (gerrit-hohl@users.sourceforge.net)
38 * @version <b>1.0</b>, 26.04.2016 by Gerrit Hohl
39 */
40 public interface DataStore {
41
42
43 /**
44 * <p>
45 * Adds a directory to the store.
46 * </p>
47 * <p>
48 * This method is equal to the method
49 * {@link #addDirectory(String, FileOwner, FileMode)} using the following
50 * values:
51 * <table>
52 * <tr>
53 * <th>group ID</th>
54 * <th>group name</th>
55 * <th>user ID</th>
56 * <th>user name</th>
57 * <th>mode (octal)</th>
58 * </tr>
59 * <tr>
60 * <td>0</td>
61 * <td>root</td>
62 * <td>0</td>
63 * <td>root</td>
64 * <td>0755</td>
65 * </tr>
66 * </table>
67 * </p>
68 *
69 * @param path
70 * The installation path.
71 * @throws IllegalArgumentException
72 * If the installation path is <code>null</code>, the parent
73 * directory wasn't added before or already contains an entry
74 * with the same name. Only exception is the root "/"
75 * directory which always exists.
76 */
77 void addDirectory(String path);
78
79
80 /**
81 * <p>
82 * Adds a directory to the store.
83 * </p>
84 *
85 * @param path
86 * The installation path.
87 * @param owner
88 * The owner.
89 * @param mode
90 * The mode.
91 * @throws IllegalArgumentException
92 * If any of the parameters are <code>null</code>, the path
93 * doesn't contain an valid path, the parent directory wasn't
94 * added before or already contains an entry with the same name.
95 * Only exception is the root "/" directory which
96 * always exists.
97 */
98 void addDirectory(String path, FileOwner owner, FileMode mode);
99
100
101 /**
102 * <p>
103 * Adds a file to the store.
104 * </p>
105 * <p>
106 * This method is equal to the method
107 * {@link #addFile(DataSource, String, FileOwner, FileMode)} using the
108 * following values:
109 * <table>
110 * <tr>
111 * <th>group ID</th>
112 * <th>group name</th>
113 * <th>user ID</th>
114 * <th>user name</th>
115 * <th>mode (octal)</th>
116 * </tr>
117 * <tr>
118 * <td>0</td>
119 * <td>root</td>
120 * <td>0</td>
121 * <td>root</td>
122 * <td>0644</td>
123 * </tr>
124 * </table>
125 * </p>
126 *
127 * @param source
128 * The source for the context of the file.
129 * @param path
130 * The installation path.
131 * @throws IllegalArgumentException
132 * If any of the parameters are <code>null</code>, the parent
133 * directory wasn't added before or already contains an entry
134 * with the same name. Only exception is the root "/"
135 * directory which always exists.
136 */
137 void addFile(DataSource source, String path);
138
139
140 /**
141 * <p>
142 * Adds a file to the store.
143 * </p>
144 *
145 * @param source
146 * The source for the content of the file.
147 * @param path
148 * The installation path.
149 * @param owner
150 * The owner.
151 * @param mode
152 * The mode.
153 * @throws IllegalArgumentException
154 * If any of the parameters are <code>null</code>, the parent
155 * directory wasn't added before or already contains an entry
156 * with the same name. Only exception is the root "/"
157 * directory which always exists.
158 */
159 void addFile(DataSource source, String path, FileOwner owner, FileMode mode);
160
161
162 /**
163 * <p>
164 * Adds a symbolic link to the store.
165 * </p>
166 *
167 * @param path
168 * The installation path.
169 * @param target
170 * The target of the symbolic link.
171 * @param owner
172 * The owner.
173 * @param mode
174 * The mode.
175 * @throws IllegalArgumentException
176 * If any of the parameters are <code>null</code>, the parent
177 * directory wasn't added before or already contains an entry
178 * with the same name. Only exception is the root "/"
179 * directory which always exists.
180 */
181 void addSymLink(String path, String target, FileOwner owner, FileMode mode);
182
183
184 /**
185 * <p>
186 * Returns the flag if a directory or file with the specified path exists.
187 * </p>
188 *
189 * @param path
190 * The path.
191 * @return The flag: <code>true</code>, if the path exists,
192 * <code>false</code> otherwise.
193 * @throws IllegalArgumentException
194 * If the path is <code>null</code>.
195 */
196 boolean exists(String path);
197
198
199 /**
200 * <p>
201 * Returns the size of all files added to the store.
202 * </p>
203 *
204 * @return The size.
205 * @throws IOException
206 * If an I/O error occurs.
207 */
208 Size getSize() throws IOException;
209
210
211 /**
212 * <p>
213 * Writes the directories and files added to the store into a TAR archive
214 * using the specified stream.
215 * </p>
216 *
217 * @param out
218 * The stream on the TAR archive.
219 * @throws IllegalArgumentException
220 * If the stream is <code>null</code>.
221 * @throws IOException
222 * If an I/O error occurs.
223 */
224 void write(TarArchiveOutputStream out) throws IOException;
225
226
227 /**
228 * <p>
229 * Creates the hashes for all files in the store using the specified digest.
230 * </p>
231 *
232 * @param digest
233 * The digest.
234 * @return The hashes.
235 * @throws IllegalArgumentException
236 * If the digest is <code>null</code>.
237 * @throws IOException
238 * If an I/O error occurs.
239 */
240 List<FileHash> createFileHashes(MessageDigest digest) throws IOException;
241
242
243 }