]>
Commit | Line | Data |
---|---|---|
7c673cae | 1 | // Copyright (c) 2011-present, Facebook, Inc. All rights reserved. |
11fdf7f2 TL |
2 | // This source code is licensed under both the GPLv2 (found in the |
3 | // COPYING file in the root directory) and Apache 2.0 License | |
4 | // (found in the LICENSE.Apache file in the root directory). | |
7c673cae FG |
5 | |
6 | package org.rocksdb; | |
7 | ||
8 | import java.io.File; | |
9 | ||
10 | /** | |
1e59de90 TL |
11 | * <p>BackupEngineOptions controls the behavior of a |
12 | * {@link org.rocksdb.BackupEngine}. | |
7c673cae FG |
13 | * </p> |
14 | * <p>Note that dispose() must be called before an Options instance | |
15 | * become out-of-scope to release the allocated memory in c++.</p> | |
16 | * | |
11fdf7f2 | 17 | * @see org.rocksdb.BackupEngine |
7c673cae | 18 | */ |
1e59de90 | 19 | public class BackupEngineOptions extends RocksObject { |
7c673cae FG |
20 | private Env backupEnv = null; |
21 | private Logger infoLog = null; | |
22 | private RateLimiter backupRateLimiter = null; | |
23 | private RateLimiter restoreRateLimiter = null; | |
24 | ||
25 | /** | |
1e59de90 | 26 | * <p>BackupEngineOptions constructor.</p> |
7c673cae FG |
27 | * |
28 | * @param path Where to keep the backup files. Has to be different than db | |
29 | * name. Best to set this to {@code db name_ + "/backups"} | |
30 | * @throws java.lang.IllegalArgumentException if illegal path is used. | |
31 | */ | |
1e59de90 TL |
32 | public BackupEngineOptions(final String path) { |
33 | super(newBackupEngineOptions(ensureWritableFile(path))); | |
7c673cae FG |
34 | } |
35 | ||
36 | private static String ensureWritableFile(final String path) { | |
37 | final File backupPath = path == null ? null : new File(path); | |
38 | if (backupPath == null || !backupPath.isDirectory() || | |
39 | !backupPath.canWrite()) { | |
40 | throw new IllegalArgumentException("Illegal path provided."); | |
41 | } else { | |
42 | return path; | |
43 | } | |
44 | } | |
45 | ||
46 | /** | |
1e59de90 | 47 | * <p>Returns the path to the BackupEngine directory.</p> |
7c673cae | 48 | * |
1e59de90 | 49 | * @return the path to the BackupEngine directory. |
7c673cae FG |
50 | */ |
51 | public String backupDir() { | |
52 | assert(isOwningHandle()); | |
53 | return backupDir(nativeHandle_); | |
54 | } | |
55 | ||
56 | /** | |
57 | * Backup Env object. It will be used for backup file I/O. If it's | |
58 | * null, backups will be written out using DBs Env. Otherwise | |
59 | * backup's I/O will be performed using this object. | |
60 | * | |
7c673cae FG |
61 | * Default: null |
62 | * | |
63 | * @param env The environment to use | |
1e59de90 | 64 | * @return instance of current BackupEngineOptions. |
7c673cae | 65 | */ |
1e59de90 | 66 | public BackupEngineOptions setBackupEnv(final Env env) { |
7c673cae FG |
67 | assert(isOwningHandle()); |
68 | setBackupEnv(nativeHandle_, env.nativeHandle_); | |
69 | this.backupEnv = env; | |
70 | return this; | |
71 | } | |
72 | ||
73 | /** | |
74 | * Backup Env object. It will be used for backup file I/O. If it's | |
75 | * null, backups will be written out using DBs Env. Otherwise | |
76 | * backup's I/O will be performed using this object. | |
77 | * | |
7c673cae FG |
78 | * Default: null |
79 | * | |
80 | * @return The environment in use | |
81 | */ | |
82 | public Env backupEnv() { | |
83 | return this.backupEnv; | |
84 | } | |
85 | ||
86 | /** | |
87 | * <p>Share table files between backups.</p> | |
88 | * | |
89 | * @param shareTableFiles If {@code share_table_files == true}, backup will | |
90 | * assume that table files with same name have the same contents. This | |
91 | * enables incremental backups and avoids unnecessary data copies. If | |
92 | * {@code share_table_files == false}, each backup will be on its own and | |
93 | * will not share any data with other backups. | |
94 | * | |
95 | * <p>Default: true</p> | |
96 | * | |
1e59de90 | 97 | * @return instance of current BackupEngineOptions. |
7c673cae | 98 | */ |
1e59de90 | 99 | public BackupEngineOptions setShareTableFiles(final boolean shareTableFiles) { |
7c673cae FG |
100 | assert(isOwningHandle()); |
101 | setShareTableFiles(nativeHandle_, shareTableFiles); | |
102 | return this; | |
103 | } | |
104 | ||
105 | /** | |
106 | * <p>Share table files between backups.</p> | |
107 | * | |
108 | * @return boolean value indicating if SST files will be shared between | |
109 | * backups. | |
110 | */ | |
111 | public boolean shareTableFiles() { | |
112 | assert(isOwningHandle()); | |
113 | return shareTableFiles(nativeHandle_); | |
114 | } | |
115 | ||
116 | /** | |
117 | * Set the logger to use for Backup info and error messages | |
118 | * | |
119 | * @param logger The logger to use for the backup | |
1e59de90 | 120 | * @return instance of current BackupEngineOptions. |
7c673cae | 121 | */ |
1e59de90 | 122 | public BackupEngineOptions setInfoLog(final Logger logger) { |
7c673cae FG |
123 | assert(isOwningHandle()); |
124 | setInfoLog(nativeHandle_, logger.nativeHandle_); | |
125 | this.infoLog = logger; | |
126 | return this; | |
127 | } | |
128 | ||
129 | /** | |
130 | * Set the logger to use for Backup info and error messages | |
131 | * | |
132 | * Default: null | |
133 | * | |
134 | * @return The logger in use for the backup | |
135 | */ | |
136 | public Logger infoLog() { | |
137 | return this.infoLog; | |
138 | } | |
139 | ||
140 | /** | |
141 | * <p>Set synchronous backups.</p> | |
142 | * | |
143 | * @param sync If {@code sync == true}, we can guarantee you'll get consistent | |
144 | * backup even on a machine crash/reboot. Backup process is slower with sync | |
145 | * enabled. If {@code sync == false}, we don't guarantee anything on machine | |
146 | * reboot. However, chances are some of the backups are consistent. | |
147 | * | |
148 | * <p>Default: true</p> | |
149 | * | |
1e59de90 | 150 | * @return instance of current BackupEngineOptions. |
7c673cae | 151 | */ |
1e59de90 | 152 | public BackupEngineOptions setSync(final boolean sync) { |
7c673cae FG |
153 | assert(isOwningHandle()); |
154 | setSync(nativeHandle_, sync); | |
155 | return this; | |
156 | } | |
157 | ||
158 | /** | |
159 | * <p>Are synchronous backups activated.</p> | |
160 | * | |
161 | * @return boolean value if synchronous backups are configured. | |
162 | */ | |
163 | public boolean sync() { | |
164 | assert(isOwningHandle()); | |
165 | return sync(nativeHandle_); | |
166 | } | |
167 | ||
168 | /** | |
169 | * <p>Set if old data will be destroyed.</p> | |
170 | * | |
171 | * @param destroyOldData If true, it will delete whatever backups there are | |
172 | * already. | |
173 | * | |
174 | * <p>Default: false</p> | |
175 | * | |
1e59de90 | 176 | * @return instance of current BackupEngineOptions. |
7c673cae | 177 | */ |
1e59de90 | 178 | public BackupEngineOptions setDestroyOldData(final boolean destroyOldData) { |
7c673cae FG |
179 | assert(isOwningHandle()); |
180 | setDestroyOldData(nativeHandle_, destroyOldData); | |
181 | return this; | |
182 | } | |
183 | ||
184 | /** | |
185 | * <p>Returns if old data will be destroyed will performing new backups.</p> | |
186 | * | |
187 | * @return boolean value indicating if old data will be destroyed. | |
188 | */ | |
189 | public boolean destroyOldData() { | |
190 | assert(isOwningHandle()); | |
191 | return destroyOldData(nativeHandle_); | |
192 | } | |
193 | ||
194 | /** | |
195 | * <p>Set if log files shall be persisted.</p> | |
196 | * | |
197 | * @param backupLogFiles If false, we won't backup log files. This option can | |
198 | * be useful for backing up in-memory databases where log file are | |
199 | * persisted, but table files are in memory. | |
200 | * | |
201 | * <p>Default: true</p> | |
202 | * | |
1e59de90 | 203 | * @return instance of current BackupEngineOptions. |
7c673cae | 204 | */ |
1e59de90 | 205 | public BackupEngineOptions setBackupLogFiles(final boolean backupLogFiles) { |
7c673cae FG |
206 | assert(isOwningHandle()); |
207 | setBackupLogFiles(nativeHandle_, backupLogFiles); | |
208 | return this; | |
209 | } | |
210 | ||
211 | /** | |
212 | * <p>Return information if log files shall be persisted.</p> | |
213 | * | |
214 | * @return boolean value indicating if log files will be persisted. | |
215 | */ | |
216 | public boolean backupLogFiles() { | |
217 | assert(isOwningHandle()); | |
218 | return backupLogFiles(nativeHandle_); | |
219 | } | |
220 | ||
221 | /** | |
222 | * <p>Set backup rate limit.</p> | |
223 | * | |
224 | * @param backupRateLimit Max bytes that can be transferred in a second during | |
225 | * backup. If 0 or negative, then go as fast as you can. | |
226 | * | |
227 | * <p>Default: 0</p> | |
228 | * | |
1e59de90 | 229 | * @return instance of current BackupEngineOptions. |
7c673cae | 230 | */ |
1e59de90 | 231 | public BackupEngineOptions setBackupRateLimit(long backupRateLimit) { |
7c673cae FG |
232 | assert(isOwningHandle()); |
233 | backupRateLimit = (backupRateLimit <= 0) ? 0 : backupRateLimit; | |
234 | setBackupRateLimit(nativeHandle_, backupRateLimit); | |
235 | return this; | |
236 | } | |
237 | ||
238 | /** | |
239 | * <p>Return backup rate limit which described the max bytes that can be | |
240 | * transferred in a second during backup.</p> | |
241 | * | |
242 | * @return numerical value describing the backup transfer limit in bytes per | |
243 | * second. | |
244 | */ | |
245 | public long backupRateLimit() { | |
246 | assert(isOwningHandle()); | |
247 | return backupRateLimit(nativeHandle_); | |
248 | } | |
249 | ||
250 | /** | |
251 | * Backup rate limiter. Used to control transfer speed for backup. If this is | |
252 | * not null, {@link #backupRateLimit()} is ignored. | |
253 | * | |
254 | * Default: null | |
255 | * | |
256 | * @param backupRateLimiter The rate limiter to use for the backup | |
1e59de90 | 257 | * @return instance of current BackupEngineOptions. |
7c673cae | 258 | */ |
1e59de90 | 259 | public BackupEngineOptions setBackupRateLimiter(final RateLimiter backupRateLimiter) { |
7c673cae FG |
260 | assert(isOwningHandle()); |
261 | setBackupRateLimiter(nativeHandle_, backupRateLimiter.nativeHandle_); | |
262 | this.backupRateLimiter = backupRateLimiter; | |
263 | return this; | |
264 | } | |
265 | ||
266 | /** | |
267 | * Backup rate limiter. Used to control transfer speed for backup. If this is | |
268 | * not null, {@link #backupRateLimit()} is ignored. | |
269 | * | |
270 | * Default: null | |
271 | * | |
272 | * @return The rate limiter in use for the backup | |
273 | */ | |
274 | public RateLimiter backupRateLimiter() { | |
275 | assert(isOwningHandle()); | |
276 | return this.backupRateLimiter; | |
277 | } | |
278 | ||
279 | /** | |
280 | * <p>Set restore rate limit.</p> | |
281 | * | |
282 | * @param restoreRateLimit Max bytes that can be transferred in a second | |
283 | * during restore. If 0 or negative, then go as fast as you can. | |
284 | * | |
285 | * <p>Default: 0</p> | |
286 | * | |
1e59de90 | 287 | * @return instance of current BackupEngineOptions. |
7c673cae | 288 | */ |
1e59de90 | 289 | public BackupEngineOptions setRestoreRateLimit(long restoreRateLimit) { |
7c673cae FG |
290 | assert(isOwningHandle()); |
291 | restoreRateLimit = (restoreRateLimit <= 0) ? 0 : restoreRateLimit; | |
292 | setRestoreRateLimit(nativeHandle_, restoreRateLimit); | |
293 | return this; | |
294 | } | |
295 | ||
296 | /** | |
297 | * <p>Return restore rate limit which described the max bytes that can be | |
298 | * transferred in a second during restore.</p> | |
299 | * | |
300 | * @return numerical value describing the restore transfer limit in bytes per | |
301 | * second. | |
302 | */ | |
303 | public long restoreRateLimit() { | |
304 | assert(isOwningHandle()); | |
305 | return restoreRateLimit(nativeHandle_); | |
306 | } | |
307 | ||
308 | /** | |
309 | * Restore rate limiter. Used to control transfer speed during restore. If | |
310 | * this is not null, {@link #restoreRateLimit()} is ignored. | |
311 | * | |
312 | * Default: null | |
313 | * | |
314 | * @param restoreRateLimiter The rate limiter to use during restore | |
1e59de90 | 315 | * @return instance of current BackupEngineOptions. |
7c673cae | 316 | */ |
1e59de90 | 317 | public BackupEngineOptions setRestoreRateLimiter(final RateLimiter restoreRateLimiter) { |
7c673cae FG |
318 | assert(isOwningHandle()); |
319 | setRestoreRateLimiter(nativeHandle_, restoreRateLimiter.nativeHandle_); | |
320 | this.restoreRateLimiter = restoreRateLimiter; | |
321 | return this; | |
322 | } | |
323 | ||
324 | /** | |
325 | * Restore rate limiter. Used to control transfer speed during restore. If | |
326 | * this is not null, {@link #restoreRateLimit()} is ignored. | |
327 | * | |
328 | * Default: null | |
329 | * | |
330 | * @return The rate limiter in use during restore | |
331 | */ | |
332 | public RateLimiter restoreRateLimiter() { | |
333 | assert(isOwningHandle()); | |
334 | return this.restoreRateLimiter; | |
335 | } | |
336 | ||
337 | /** | |
338 | * <p>Only used if share_table_files is set to true. If true, will consider | |
339 | * that backups can come from different databases, hence a sst is not uniquely | |
340 | * identified by its name, but by the triple (file name, crc32, file length) | |
341 | * </p> | |
342 | * | |
343 | * @param shareFilesWithChecksum boolean value indicating if SST files are | |
344 | * stored using the triple (file name, crc32, file length) and not its name. | |
345 | * | |
346 | * <p>Note: this is an experimental option, and you'll need to set it manually | |
347 | * turn it on only if you know what you're doing*</p> | |
348 | * | |
349 | * <p>Default: false</p> | |
350 | * | |
1e59de90 | 351 | * @return instance of current BackupEngineOptions. |
7c673cae | 352 | */ |
1e59de90 | 353 | public BackupEngineOptions setShareFilesWithChecksum(final boolean shareFilesWithChecksum) { |
7c673cae FG |
354 | assert(isOwningHandle()); |
355 | setShareFilesWithChecksum(nativeHandle_, shareFilesWithChecksum); | |
356 | return this; | |
357 | } | |
358 | ||
359 | /** | |
360 | * <p>Return of share files with checksum is active.</p> | |
361 | * | |
362 | * @return boolean value indicating if share files with checksum | |
363 | * is active. | |
364 | */ | |
365 | public boolean shareFilesWithChecksum() { | |
366 | assert(isOwningHandle()); | |
367 | return shareFilesWithChecksum(nativeHandle_); | |
368 | } | |
369 | ||
370 | /** | |
371 | * Up to this many background threads will copy files for | |
11fdf7f2 TL |
372 | * {@link BackupEngine#createNewBackup(RocksDB, boolean)} and |
373 | * {@link BackupEngine#restoreDbFromBackup(int, String, String, RestoreOptions)} | |
7c673cae FG |
374 | * |
375 | * Default: 1 | |
376 | * | |
377 | * @param maxBackgroundOperations The maximum number of background threads | |
1e59de90 | 378 | * @return instance of current BackupEngineOptions. |
7c673cae | 379 | */ |
1e59de90 | 380 | public BackupEngineOptions setMaxBackgroundOperations(final int maxBackgroundOperations) { |
7c673cae FG |
381 | assert(isOwningHandle()); |
382 | setMaxBackgroundOperations(nativeHandle_, maxBackgroundOperations); | |
383 | return this; | |
384 | } | |
385 | ||
386 | /** | |
387 | * Up to this many background threads will copy files for | |
11fdf7f2 TL |
388 | * {@link BackupEngine#createNewBackup(RocksDB, boolean)} and |
389 | * {@link BackupEngine#restoreDbFromBackup(int, String, String, RestoreOptions)} | |
7c673cae FG |
390 | * |
391 | * Default: 1 | |
392 | * | |
393 | * @return The maximum number of background threads | |
394 | */ | |
395 | public int maxBackgroundOperations() { | |
396 | assert(isOwningHandle()); | |
397 | return maxBackgroundOperations(nativeHandle_); | |
398 | } | |
399 | ||
400 | /** | |
401 | * During backup user can get callback every time next | |
402 | * {@link #callbackTriggerIntervalSize()} bytes being copied. | |
403 | * | |
404 | * Default: 4194304 | |
405 | * | |
406 | * @param callbackTriggerIntervalSize The interval size for the | |
407 | * callback trigger | |
1e59de90 | 408 | * @return instance of current BackupEngineOptions. |
7c673cae | 409 | */ |
1e59de90 | 410 | public BackupEngineOptions setCallbackTriggerIntervalSize( |
7c673cae FG |
411 | final long callbackTriggerIntervalSize) { |
412 | assert(isOwningHandle()); | |
413 | setCallbackTriggerIntervalSize(nativeHandle_, callbackTriggerIntervalSize); | |
414 | return this; | |
415 | } | |
416 | ||
417 | /** | |
418 | * During backup user can get callback every time next | |
419 | * {@link #callbackTriggerIntervalSize()} bytes being copied. | |
420 | * | |
421 | * Default: 4194304 | |
422 | * | |
423 | * @return The interval size for the callback trigger | |
424 | */ | |
425 | public long callbackTriggerIntervalSize() { | |
426 | assert(isOwningHandle()); | |
427 | return callbackTriggerIntervalSize(nativeHandle_); | |
428 | } | |
429 | ||
1e59de90 | 430 | private native static long newBackupEngineOptions(final String path); |
7c673cae FG |
431 | private native String backupDir(long handle); |
432 | private native void setBackupEnv(final long handle, final long envHandle); | |
433 | private native void setShareTableFiles(long handle, boolean flag); | |
434 | private native boolean shareTableFiles(long handle); | |
435 | private native void setInfoLog(final long handle, final long infoLogHandle); | |
436 | private native void setSync(long handle, boolean flag); | |
437 | private native boolean sync(long handle); | |
438 | private native void setDestroyOldData(long handle, boolean flag); | |
439 | private native boolean destroyOldData(long handle); | |
440 | private native void setBackupLogFiles(long handle, boolean flag); | |
441 | private native boolean backupLogFiles(long handle); | |
442 | private native void setBackupRateLimit(long handle, long rateLimit); | |
443 | private native long backupRateLimit(long handle); | |
444 | private native void setBackupRateLimiter(long handle, long rateLimiterHandle); | |
445 | private native void setRestoreRateLimit(long handle, long rateLimit); | |
446 | private native long restoreRateLimit(long handle); | |
447 | private native void setRestoreRateLimiter(final long handle, | |
448 | final long rateLimiterHandle); | |
449 | private native void setShareFilesWithChecksum(long handle, boolean flag); | |
450 | private native boolean shareFilesWithChecksum(long handle); | |
451 | private native void setMaxBackgroundOperations(final long handle, | |
452 | final int maxBackgroundOperations); | |
453 | private native int maxBackgroundOperations(final long handle); | |
454 | private native void setCallbackTriggerIntervalSize(final long handle, | |
455 | long callbackTriggerIntervalSize); | |
456 | private native long callbackTriggerIntervalSize(final long handle); | |
457 | @Override protected final native void disposeInternal(final long handle); | |
458 | } |