fix changelog headers
[fanfix.git] / BasicLibrary.java
... / ...
CommitLineData
1package be.nikiroo.fanfix.library;
2
3import java.io.File;
4import java.io.IOException;
5import java.net.URL;
6import java.net.UnknownHostException;
7import java.util.ArrayList;
8import java.util.Collections;
9import java.util.List;
10
11import be.nikiroo.fanfix.Instance;
12import be.nikiroo.fanfix.data.MetaData;
13import be.nikiroo.fanfix.data.Story;
14import be.nikiroo.fanfix.output.BasicOutput;
15import be.nikiroo.fanfix.output.BasicOutput.OutputType;
16import be.nikiroo.fanfix.supported.BasicSupport;
17import be.nikiroo.fanfix.supported.SupportType;
18import be.nikiroo.utils.Image;
19import be.nikiroo.utils.Progress;
20
21/**
22 * Manage a library of Stories: import, export, list, modify.
23 * <p>
24 * Each {@link Story} object will be associated with a (local to the library)
25 * unique ID, the LUID, which will be used to identify the {@link Story}.
26 * <p>
27 * Most of the {@link BasicLibrary} functions work on a partial (cover
28 * <b>MAY</b> not be included) {@link MetaData} object.
29 *
30 * @author niki
31 */
32abstract public class BasicLibrary {
33 /**
34 * A {@link BasicLibrary} status.
35 *
36 * @author niki
37 */
38 public enum Status {
39 /** The library is ready. */
40 READY,
41 /** The library is invalid (not correctly set up). */
42 INVALID,
43 /** You are not allowed to access this library. */
44 UNAUTORIZED,
45 /** The library is currently out of commission. */
46 UNAVAILABLE,
47 }
48
49 /**
50 * Return a name for this library (the UI may display this).
51 * <p>
52 * Must not be NULL.
53 *
54 * @return the name, or an empty {@link String} if none
55 */
56 public String getLibraryName() {
57 return "";
58 }
59
60 /**
61 * The library status.
62 *
63 * @return the current status
64 */
65 public Status getStatus() {
66 return Status.READY;
67 }
68
69 /**
70 * Retrieve the main {@link File} corresponding to the given {@link Story},
71 * which can be passed to an external reader or instance.
72 * <p>
73 * Do <b>NOT</b> alter this file.
74 *
75 * @param luid
76 * the Library UID of the story
77 * @param pg
78 * the optional {@link Progress}
79 *
80 * @return the corresponding {@link Story}
81 */
82 public abstract File getFile(String luid, Progress pg);
83
84 /**
85 * Return the cover image associated to this story.
86 *
87 * @param luid
88 * the Library UID of the story
89 *
90 * @return the cover image
91 */
92 public abstract Image getCover(String luid);
93
94 /**
95 * Return the cover image associated to this source.
96 * <p>
97 * By default, return the cover of the first story with this source.
98 *
99 * @param source
100 * the source
101 *
102 * @return the cover image or NULL
103 */
104 public Image getSourceCover(String source) {
105 List<MetaData> metas = getListBySource(source);
106 if (metas.size() > 0) {
107 return getCover(metas.get(0).getLuid());
108 }
109
110 return null;
111 }
112
113 /**
114 * Fix the source cover to the given story cover.
115 *
116 * @param source
117 * the source to change
118 * @param luid
119 * the story LUID
120 */
121 public abstract void setSourceCover(String source, String luid);
122
123 /**
124 * Return the list of stories (represented by their {@link MetaData}, which
125 * <b>MAY</b> not have the cover included).
126 *
127 * @param pg
128 * the optional {@link Progress}
129 *
130 * @return the list (can be empty but not NULL)
131 */
132 protected abstract List<MetaData> getMetas(Progress pg);
133
134 /**
135 * Invalidate the {@link Story} cache (when the content should be re-read
136 * because it was changed).
137 */
138 protected void deleteInfo() {
139 deleteInfo(null);
140 }
141
142 /**
143 * Invalidate the {@link Story} cache (when the content is removed).
144 * <p>
145 * All the cache can be deleted if NULL is passed as meta.
146 *
147 * @param luid
148 * the LUID of the {@link Story} to clear from the cache, or NULL
149 * for all stories
150 */
151 protected abstract void deleteInfo(String luid);
152
153 /**
154 * Invalidate the {@link Story} cache (when the content has changed, but we
155 * already have it) with the new given meta.
156 *
157 * @param meta
158 * the {@link Story} to clear from the cache
159 */
160 protected abstract void updateInfo(MetaData meta);
161
162 /**
163 * Return the next LUID that can be used.
164 *
165 * @return the next luid
166 */
167 protected abstract int getNextId();
168
169 /**
170 * Delete the target {@link Story}.
171 *
172 * @param luid
173 * the LUID of the {@link Story}
174 *
175 * @throws IOException
176 * in case of I/O error or if the {@link Story} wa not found
177 */
178 protected abstract void doDelete(String luid) throws IOException;
179
180 /**
181 * Actually save the story to the back-end.
182 *
183 * @param story
184 * the {@link Story} to save
185 * @param pg
186 * the optional {@link Progress}
187 *
188 * @return the saved {@link Story} (which may have changed, especially
189 * regarding the {@link MetaData})
190 *
191 * @throws IOException
192 * in case of I/O error
193 */
194 protected abstract Story doSave(Story story, Progress pg)
195 throws IOException;
196
197 /**
198 * Refresh the {@link BasicLibrary}, that is, make sure all metas are
199 * loaded.
200 *
201 * @param pg
202 * the optional progress reporter
203 */
204 public void refresh(Progress pg) {
205 getMetas(pg);
206 }
207
208 /**
209 * List all the known types (sources) of stories.
210 *
211 * @return the sources
212 */
213 public synchronized List<String> getSources() {
214 List<String> list = new ArrayList<String>();
215 for (MetaData meta : getMetas(null)) {
216 String storySource = meta.getSource();
217 if (!list.contains(storySource)) {
218 list.add(storySource);
219 }
220 }
221
222 Collections.sort(list);
223 return list;
224 }
225
226 /**
227 * List all the known authors of stories.
228 *
229 * @return the authors
230 */
231 public synchronized List<String> getAuthors() {
232 List<String> list = new ArrayList<String>();
233 for (MetaData meta : getMetas(null)) {
234 String storyAuthor = meta.getAuthor();
235 if (!list.contains(storyAuthor)) {
236 list.add(storyAuthor);
237 }
238 }
239
240 Collections.sort(list);
241 return list;
242 }
243
244 /**
245 * List all the stories in the {@link BasicLibrary}.
246 * <p>
247 * Cover images not included.
248 *
249 * @return the stories
250 */
251 public synchronized List<MetaData> getList() {
252 return getMetas(null);
253 }
254
255 /**
256 * List all the stories of the given source type in the {@link BasicLibrary}
257 * , or all the stories if NULL is passed as a type.
258 * <p>
259 * Cover images not included.
260 *
261 * @param type
262 * the type of story to retrieve, or NULL for all
263 *
264 * @return the stories
265 */
266 public synchronized List<MetaData> getListBySource(String type) {
267 List<MetaData> list = new ArrayList<MetaData>();
268 for (MetaData meta : getMetas(null)) {
269 String storyType = meta.getSource();
270 if (type == null || type.equalsIgnoreCase(storyType)) {
271 list.add(meta);
272 }
273 }
274
275 Collections.sort(list);
276 return list;
277 }
278
279 /**
280 * List all the stories of the given author in the {@link BasicLibrary}, or
281 * all the stories if NULL is passed as an author.
282 * <p>
283 * Cover images not included.
284 *
285 * @param author
286 * the author of the stories to retrieve, or NULL for all
287 *
288 * @return the stories
289 */
290 public synchronized List<MetaData> getListByAuthor(String author) {
291 List<MetaData> list = new ArrayList<MetaData>();
292 for (MetaData meta : getMetas(null)) {
293 String storyAuthor = meta.getAuthor();
294 if (author == null || author.equalsIgnoreCase(storyAuthor)) {
295 list.add(meta);
296 }
297 }
298
299 Collections.sort(list);
300 return list;
301 }
302
303 /**
304 * Retrieve a {@link MetaData} corresponding to the given {@link Story},
305 * cover image <b>MAY</b> not be included.
306 *
307 * @param luid
308 * the Library UID of the story
309 *
310 * @return the corresponding {@link Story}
311 */
312 public synchronized MetaData getInfo(String luid) {
313 if (luid != null) {
314 for (MetaData meta : getMetas(null)) {
315 if (luid.equals(meta.getLuid())) {
316 return meta;
317 }
318 }
319 }
320
321 return null;
322 }
323
324 /**
325 * Retrieve a specific {@link Story}.
326 *
327 * @param luid
328 * the Library UID of the story
329 * @param pg
330 * the optional progress reporter
331 *
332 * @return the corresponding {@link Story} or NULL if not found
333 */
334 public synchronized Story getStory(String luid, Progress pg) {
335 if (pg == null) {
336 pg = new Progress();
337 }
338
339 Progress pgGet = new Progress();
340 Progress pgProcess = new Progress();
341
342 pg.setMinMax(0, 2);
343 pg.addProgress(pgGet, 1);
344 pg.addProgress(pgProcess, 1);
345
346 Story story = null;
347 for (MetaData meta : getMetas(null)) {
348 if (meta.getLuid().equals(luid)) {
349 File file = getFile(luid, pgGet);
350 pgGet.done();
351 try {
352 SupportType type = SupportType.valueOfAllOkUC(meta
353 .getType());
354 URL url = file.toURI().toURL();
355 if (type != null) {
356 story = BasicSupport.getSupport(type, url) //
357 .process(pgProcess);
358
359 // Because we do not want to clear the meta cache:
360 meta.setCover(story.getMeta().getCover());
361 story.setMeta(meta);
362 //
363 } else {
364 throw new IOException("Unknown type: " + meta.getType());
365 }
366 } catch (IOException e) {
367 // We should not have not-supported files in the
368 // library
369 Instance.getTraceHandler().error(
370 new IOException("Cannot load file from library: "
371 + file, e));
372 } finally {
373 pgProcess.done();
374 pg.done();
375 }
376
377 break;
378 }
379 }
380
381 return story;
382 }
383
384 /**
385 * Import the {@link Story} at the given {@link URL} into the
386 * {@link BasicLibrary}.
387 *
388 * @param url
389 * the {@link URL} to import
390 * @param pg
391 * the optional progress reporter
392 *
393 * @return the imported {@link Story}
394 *
395 * @throws UnknownHostException
396 * if the host is not supported
397 * @throws IOException
398 * in case of I/O error
399 */
400 public Story imprt(URL url, Progress pg) throws IOException {
401 if (pg == null)
402 pg = new Progress();
403
404 pg.setMinMax(0, 1000);
405 Progress pgProcess = new Progress();
406 Progress pgSave = new Progress();
407 pg.addProgress(pgProcess, 800);
408 pg.addProgress(pgSave, 200);
409
410 BasicSupport support = BasicSupport.getSupport(url);
411 if (support == null) {
412 throw new UnknownHostException("" + url);
413 }
414
415 Story story = save(support.process(pgProcess), pgSave);
416 pg.done();
417
418 return story;
419 }
420
421 /**
422 * Import the story from one library to another, and keep the same LUID.
423 *
424 * @param other
425 * the other library to import from
426 * @param luid
427 * the Library UID
428 * @param pg
429 * the optional progress reporter
430 *
431 * @throws IOException
432 * in case of I/O error
433 */
434 public void imprt(BasicLibrary other, String luid, Progress pg)
435 throws IOException {
436 Progress pgGetStory = new Progress();
437 Progress pgSave = new Progress();
438 if (pg == null) {
439 pg = new Progress();
440 }
441
442 pg.setMinMax(0, 2);
443 pg.addProgress(pgGetStory, 1);
444 pg.addProgress(pgSave, 1);
445
446 Story story = other.getStory(luid, pgGetStory);
447 if (story != null) {
448 story = this.save(story, luid, pgSave);
449 pg.done();
450 } else {
451 pg.done();
452 throw new IOException("Cannot find story in Library: " + luid);
453 }
454 }
455
456 /**
457 * Export the {@link Story} to the given target in the given format.
458 *
459 * @param luid
460 * the {@link Story} ID
461 * @param type
462 * the {@link OutputType} to transform it to
463 * @param target
464 * the target to save to
465 * @param pg
466 * the optional progress reporter
467 *
468 * @return the saved resource (the main saved {@link File})
469 *
470 * @throws IOException
471 * in case of I/O error
472 */
473 public File export(String luid, OutputType type, String target, Progress pg)
474 throws IOException {
475 Progress pgGetStory = new Progress();
476 Progress pgOut = new Progress();
477 if (pg != null) {
478 pg.setMax(2);
479 pg.addProgress(pgGetStory, 1);
480 pg.addProgress(pgOut, 1);
481 }
482
483 BasicOutput out = BasicOutput.getOutput(type, false, false);
484 if (out == null) {
485 throw new IOException("Output type not supported: " + type);
486 }
487
488 Story story = getStory(luid, pgGetStory);
489 if (story == null) {
490 throw new IOException("Cannot find story to export: " + luid);
491 }
492
493 return out.process(story, target, pgOut);
494 }
495
496 /**
497 * Save a {@link Story} to the {@link BasicLibrary}.
498 *
499 * @param story
500 * the {@link Story} to save
501 * @param pg
502 * the optional progress reporter
503 *
504 * @return the same {@link Story}, whose LUID may have changed
505 *
506 * @throws IOException
507 * in case of I/O error
508 */
509 public Story save(Story story, Progress pg) throws IOException {
510 return save(story, null, pg);
511 }
512
513 /**
514 * Save a {@link Story} to the {@link BasicLibrary} -- the LUID <b>must</b>
515 * be correct, or NULL to get the next free one.
516 * <p>
517 * Will override any previous {@link Story} with the same LUID.
518 *
519 * @param story
520 * the {@link Story} to save
521 * @param luid
522 * the <b>correct</b> LUID or NULL to get the next free one
523 * @param pg
524 * the optional progress reporter
525 *
526 * @return the same {@link Story}, whose LUID may have changed
527 *
528 * @throws IOException
529 * in case of I/O error
530 */
531 public synchronized Story save(Story story, String luid, Progress pg)
532 throws IOException {
533
534 Instance.getTraceHandler().trace(
535 this.getClass().getSimpleName() + ": saving story " + luid);
536
537 // Do not change the original metadata, but change the original story
538 MetaData meta = story.getMeta().clone();
539 story.setMeta(meta);
540
541 if (luid == null || luid.isEmpty()) {
542 meta.setLuid(String.format("%03d", getNextId()));
543 } else {
544 meta.setLuid(luid);
545 }
546
547 if (luid != null && getInfo(luid) != null) {
548 delete(luid);
549 }
550
551 story = doSave(story, pg);
552
553 updateInfo(story.getMeta());
554
555 Instance.getTraceHandler().trace(
556 this.getClass().getSimpleName() + ": story saved (" + luid
557 + ")");
558
559 return story;
560 }
561
562 /**
563 * Delete the given {@link Story} from this {@link BasicLibrary}.
564 *
565 * @param luid
566 * the LUID of the target {@link Story}
567 *
568 * @throws IOException
569 * in case of I/O error
570 */
571 public synchronized void delete(String luid) throws IOException {
572 Instance.getTraceHandler().trace(
573 this.getClass().getSimpleName() + ": deleting story " + luid);
574
575 doDelete(luid);
576 deleteInfo(luid);
577
578 Instance.getTraceHandler().trace(
579 this.getClass().getSimpleName() + ": story deleted (" + luid
580 + ")");
581 }
582
583 /**
584 * Change the type (source) of the given {@link Story}.
585 *
586 * @param luid
587 * the {@link Story} LUID
588 * @param newSource
589 * the new source
590 * @param pg
591 * the optional progress reporter
592 *
593 * @throws IOException
594 * in case of I/O error or if the {@link Story} was not found
595 */
596 public synchronized void changeSource(String luid, String newSource,
597 Progress pg) throws IOException {
598 MetaData meta = getInfo(luid);
599 if (meta == null) {
600 throw new IOException("Story not found: " + luid);
601 }
602
603 meta.setSource(newSource);
604 saveMeta(meta, pg);
605 }
606
607 /**
608 * Save back the current state of the {@link MetaData} (LUID <b>MUST NOT</b>
609 * change) for this {@link Story}.
610 * <p>
611 * By default, delete the old {@link Story} then recreate a new
612 * {@link Story}.
613 * <p>
614 * Note that this behaviour can lead to data loss.
615 *
616 * @param meta
617 * the new {@link MetaData} (LUID <b>MUST NOT</b> change)
618 * @param pg
619 * the optional {@link Progress}
620 *
621 * @throws IOException
622 * in case of I/O error or if the {@link Story} was not found
623 */
624 protected synchronized void saveMeta(MetaData meta, Progress pg)
625 throws IOException {
626 if (pg == null) {
627 pg = new Progress();
628 }
629
630 Progress pgGet = new Progress();
631 Progress pgSet = new Progress();
632 pg.addProgress(pgGet, 50);
633 pg.addProgress(pgSet, 50);
634
635 Story story = getStory(meta.getLuid(), pgGet);
636 if (story == null) {
637 throw new IOException("Story not found: " + meta.getLuid());
638 }
639
640 delete(meta.getLuid());
641
642 story.setMeta(meta);
643 save(story, meta.getLuid(), pgSet);
644
645 pg.done();
646 }
647}