c6ce22dd24c1c4fa85f60edfdcea7bd5f8de1b05
[nikiroo-utils.git] / src / be / nikiroo / fanfix / library / BasicLibrary.java
1 package be.nikiroo.fanfix.library;
2
3 import java.io.File;
4 import java.io.IOException;
5 import java.net.URL;
6 import java.net.UnknownHostException;
7 import java.util.ArrayList;
8 import java.util.Collections;
9 import java.util.List;
10 import java.util.Map;
11 import java.util.TreeMap;
12
13 import be.nikiroo.fanfix.Instance;
14 import be.nikiroo.fanfix.data.MetaData;
15 import be.nikiroo.fanfix.data.Story;
16 import be.nikiroo.fanfix.output.BasicOutput;
17 import be.nikiroo.fanfix.output.BasicOutput.OutputType;
18 import be.nikiroo.fanfix.supported.BasicSupport;
19 import be.nikiroo.fanfix.supported.SupportType;
20 import be.nikiroo.utils.Image;
21 import be.nikiroo.utils.Progress;
22 import be.nikiroo.utils.StringUtils;
23
24 /**
25 * Manage a library of Stories: import, export, list, modify.
26 * <p>
27 * Each {@link Story} object will be associated with a (local to the library)
28 * unique ID, the LUID, which will be used to identify the {@link Story}.
29 * <p>
30 * Most of the {@link BasicLibrary} functions work on a partial (cover
31 * <b>MAY</b> not be included) {@link MetaData} object.
32 *
33 * @author niki
34 */
35 abstract public class BasicLibrary {
36 /**
37 * A {@link BasicLibrary} status.
38 *
39 * @author niki
40 */
41 public enum Status {
42 /** The library is ready and r/w. */
43 READ_WRITE,
44 /** The library is ready, but read-only. */
45 READ_ONLY,
46 /** The library is invalid (not correctly set up). */
47 INVALID,
48 /** You are not allowed to access this library. */
49 UNAUTHORIZED,
50 /** The library is currently out of commission. */
51 UNAVAILABLE;
52
53 /**
54 * The library is available (you can query it).
55 * <p>
56 * It does <b>not</b> specify if it is read-only or not.
57 *
58 * @return TRUE if it is
59 */
60 public boolean isReady() {
61 return (this == READ_WRITE || this == READ_ONLY);
62 }
63
64 /**
65 * This library can be modified (= you are allowed to modify it).
66 *
67 * @return TRUE if it is
68 */
69 public boolean isWritable() {
70 return (this == READ_WRITE);
71 }
72 }
73
74 /**
75 * Return a name for this library (the UI may display this).
76 * <p>
77 * Must not be NULL.
78 *
79 * @return the name, or an empty {@link String} if none
80 */
81 public String getLibraryName() {
82 return "";
83 }
84
85 /**
86 * The library status.
87 *
88 * @return the current status
89 */
90 public Status getStatus() {
91 return Status.READ_WRITE;
92 }
93
94 /**
95 * Retrieve the main {@link File} corresponding to the given {@link Story},
96 * which can be passed to an external reader or instance.
97 * <p>
98 * Do <b>NOT</b> alter this file.
99 *
100 * @param luid
101 * the Library UID of the story
102 * @param pg
103 * the optional {@link Progress}
104 *
105 * @return the corresponding {@link Story}
106 *
107 * @throws IOException
108 * in case of IOException
109 */
110 public abstract File getFile(String luid, Progress pg) throws IOException;
111
112 /**
113 * Return the cover image associated to this story.
114 *
115 * @param luid
116 * the Library UID of the story
117 *
118 * @return the cover image
119 *
120 * @throws IOException
121 * in case of IOException
122 */
123 public abstract Image getCover(String luid) throws IOException;
124
125 // TODO: ensure it is the main used interface
126 public synchronized MetaResultList getList(Progress pg) throws IOException {
127 return new MetaResultList(getMetas(pg));
128 }
129
130 //TODO: make something for (normal and custom) not-story covers
131
132 /**
133 * Return the cover image associated to this source.
134 * <p>
135 * By default, return the custom cover if any, and if not, return the cover
136 * of the first story with this source.
137 *
138 * @param source
139 * the source
140 *
141 * @return the cover image or NULL
142 *
143 * @throws IOException
144 * in case of IOException
145 */
146 public Image getSourceCover(String source) throws IOException {
147 Image custom = getCustomSourceCover(source);
148 if (custom != null) {
149 return custom;
150 }
151
152 List<MetaData> metas = getListBySource(source);
153 if (metas.size() > 0) {
154 return getCover(metas.get(0).getLuid());
155 }
156
157 return null;
158 }
159
160 /**
161 * Return the cover image associated to this author.
162 * <p>
163 * By default, return the custom cover if any, and if not, return the cover
164 * of the first story with this author.
165 *
166 * @param author
167 * the author
168 *
169 * @return the cover image or NULL
170 *
171 * @throws IOException
172 * in case of IOException
173 */
174 public Image getAuthorCover(String author) throws IOException {
175 Image custom = getCustomAuthorCover(author);
176 if (custom != null) {
177 return custom;
178 }
179
180 List<MetaData> metas = getListByAuthor(author);
181 if (metas.size() > 0) {
182 return getCover(metas.get(0).getLuid());
183 }
184
185 return null;
186 }
187
188 /**
189 * Return the custom cover image associated to this source.
190 * <p>
191 * By default, return NULL.
192 *
193 * @param source
194 * the source to look for
195 *
196 * @return the custom cover or NULL if none
197 *
198 * @throws IOException
199 * in case of IOException
200 */
201 @SuppressWarnings("unused")
202 public Image getCustomSourceCover(String source) throws IOException {
203 return null;
204 }
205
206 /**
207 * Return the custom cover image associated to this author.
208 * <p>
209 * By default, return NULL.
210 *
211 * @param author
212 * the author to look for
213 *
214 * @return the custom cover or NULL if none
215 *
216 * @throws IOException
217 * in case of IOException
218 */
219 @SuppressWarnings("unused")
220 public Image getCustomAuthorCover(String author) throws IOException {
221 return null;
222 }
223
224 /**
225 * Set the source cover to the given story cover.
226 *
227 * @param source
228 * the source to change
229 * @param luid
230 * the story LUID
231 *
232 * @throws IOException
233 * in case of IOException
234 */
235 public abstract void setSourceCover(String source, String luid)
236 throws IOException;
237
238 /**
239 * Set the author cover to the given story cover.
240 *
241 * @param author
242 * the author to change
243 * @param luid
244 * the story LUID
245 *
246 * @throws IOException
247 * in case of IOException
248 */
249 public abstract void setAuthorCover(String author, String luid)
250 throws IOException;
251
252 /**
253 * Return the list of stories (represented by their {@link MetaData}, which
254 * <b>MAY</b> not have the cover included).
255 * <p>
256 * The returned list <b>MUST</b> be a copy, not the original one.
257 *
258 * @param pg
259 * the optional {@link Progress}
260 *
261 * @return the list (can be empty but not NULL)
262 *
263 * @throws IOException
264 * in case of IOException
265 */
266 protected abstract List<MetaData> getMetas(Progress pg) throws IOException;
267
268 /**
269 * Invalidate the {@link Story} cache (when the content should be re-read
270 * because it was changed).
271 */
272 protected void invalidateInfo() {
273 invalidateInfo(null);
274 }
275
276 /**
277 * Invalidate the {@link Story} cache (when the content is removed).
278 * <p>
279 * All the cache can be deleted if NULL is passed as meta.
280 *
281 * @param luid
282 * the LUID of the {@link Story} to clear from the cache, or NULL
283 * for all stories
284 */
285 protected abstract void invalidateInfo(String luid);
286
287 /**
288 * Invalidate the {@link Story} cache (when the content has changed, but we
289 * already have it) with the new given meta.
290 *
291 * @param meta
292 * the {@link Story} to clear from the cache
293 *
294 * @throws IOException
295 * in case of IOException
296 */
297 protected abstract void updateInfo(MetaData meta) throws IOException;
298
299 /**
300 * Return the next LUID that can be used.
301 *
302 * @return the next luid
303 */
304 protected abstract int getNextId();
305
306 /**
307 * Delete the target {@link Story}.
308 *
309 * @param luid
310 * the LUID of the {@link Story}
311 *
312 * @throws IOException
313 * in case of I/O error or if the {@link Story} wa not found
314 */
315 protected abstract void doDelete(String luid) throws IOException;
316
317 /**
318 * Actually save the story to the back-end.
319 *
320 * @param story
321 * the {@link Story} to save
322 * @param pg
323 * the optional {@link Progress}
324 *
325 * @return the saved {@link Story} (which may have changed, especially
326 * regarding the {@link MetaData})
327 *
328 * @throws IOException
329 * in case of I/O error
330 */
331 protected abstract Story doSave(Story story, Progress pg)
332 throws IOException;
333
334 /**
335 * Refresh the {@link BasicLibrary}, that is, make sure all metas are
336 * loaded.
337 *
338 * @param pg
339 * the optional progress reporter
340 */
341 public void refresh(Progress pg) {
342 try {
343 getMetas(pg);
344 } catch (IOException e) {
345 // We will let it fail later
346 }
347 }
348
349 /**
350 * Check if the {@link Story} denoted by this Library UID is present in the
351 * cache (if we have no cache, we default to </t>true</tt>).
352 *
353 * @param luid
354 * the Library UID
355 *
356 * @return TRUE if it is
357 */
358 public boolean isCached(String luid) {
359 // By default, everything is cached
360 return true;
361 }
362
363 /**
364 * Clear the {@link Story} from the cache, if needed.
365 * <p>
366 * The next time we try to retrieve the {@link Story}, it may be required to
367 * cache it again.
368 *
369 * @param luid
370 * the story to clear
371 *
372 * @throws IOException
373 * in case of I/O error
374 */
375 public void clearFromCache(String luid) throws IOException {
376 // By default, this is a noop.
377 }
378
379 /**
380 * List all the known types (sources) of stories.
381 *
382 * @return the sources
383 *
384 * @throws IOException
385 * in case of IOException
386 */
387 public synchronized List<String> getSources() throws IOException {
388 List<String> list = new ArrayList<String>();
389 for (MetaData meta : getMetas(null)) {
390 String storySource = meta.getSource();
391 if (!list.contains(storySource)) {
392 list.add(storySource);
393 }
394 }
395
396 Collections.sort(list);
397 return list;
398 }
399
400 /**
401 * List all the known types (sources) of stories, grouped by directory
402 * ("Source_1/a" and "Source_1/b" will be grouped into "Source_1").
403 * <p>
404 * Note that an empty item in the list means a non-grouped source (type) --
405 * e.g., you could have for Source_1:
406 * <ul>
407 * <li><tt></tt>: empty, so source is "Source_1"</li>
408 * <li><tt>a</tt>: empty, so source is "Source_1/a"</li>
409 * <li><tt>b</tt>: empty, so source is "Source_1/b"</li>
410 * </ul>
411 *
412 * @return the grouped list
413 *
414 * @throws IOException
415 * in case of IOException
416 */
417 public synchronized Map<String, List<String>> getSourcesGrouped()
418 throws IOException {
419 Map<String, List<String>> map = new TreeMap<String, List<String>>();
420 for (String source : getSources()) {
421 String name;
422 String subname;
423
424 int pos = source.indexOf('/');
425 if (pos > 0 && pos < source.length() - 1) {
426 name = source.substring(0, pos);
427 subname = source.substring(pos + 1);
428
429 } else {
430 name = source;
431 subname = "";
432 }
433
434 List<String> list = map.get(name);
435 if (list == null) {
436 list = new ArrayList<String>();
437 map.put(name, list);
438 }
439 list.add(subname);
440 }
441
442 return map;
443 }
444
445 /**
446 * List all the known authors of stories.
447 *
448 * @return the authors
449 *
450 * @throws IOException
451 * in case of IOException
452 */
453 public synchronized List<String> getAuthors() throws IOException {
454 List<String> list = new ArrayList<String>();
455 for (MetaData meta : getMetas(null)) {
456 String storyAuthor = meta.getAuthor();
457 if (!list.contains(storyAuthor)) {
458 list.add(storyAuthor);
459 }
460 }
461
462 Collections.sort(list);
463 return list;
464 }
465
466 /**
467 * Return the list of authors, grouped by starting letter(s) if needed.
468 * <p>
469 * If the number of author is not too high, only one group with an empty
470 * name and all the authors will be returned.
471 * <p>
472 * If not, the authors will be separated into groups:
473 * <ul>
474 * <li><tt>*</tt>: any author whose name doesn't contain letters nor numbers
475 * </li>
476 * <li><tt>0-9</tt>: any authors whose name starts with a number</li>
477 * <li><tt>A-C</tt> (for instance): any author whose name starts with
478 * <tt>A</tt>, <tt>B</tt> or <tt>C</tt></li>
479 * </ul>
480 * Note that the letters used in the groups can vary (except <tt>*</tt> and
481 * <tt>0-9</tt>, which may only be present or not).
482 *
483 * @return the authors' names, grouped by letter(s)
484 *
485 * @throws IOException
486 * in case of IOException
487 */
488 public Map<String, List<String>> getAuthorsGrouped() throws IOException {
489 int MAX = 20;
490
491 Map<String, List<String>> groups = new TreeMap<String, List<String>>();
492 List<String> authors = getAuthors();
493
494 // If all authors fit the max, just report them as is
495 if (authors.size() <= MAX) {
496 groups.put("", authors);
497 return groups;
498 }
499
500 // Create groups A to Z, which can be empty here
501 for (char car = 'A'; car <= 'Z'; car++) {
502 groups.put(Character.toString(car), getAuthorsGroup(authors, car));
503 }
504
505 // Collapse them
506 List<String> keys = new ArrayList<String>(groups.keySet());
507 for (int i = 0; i + 1 < keys.size(); i++) {
508 String keyNow = keys.get(i);
509 String keyNext = keys.get(i + 1);
510
511 List<String> now = groups.get(keyNow);
512 List<String> next = groups.get(keyNext);
513
514 int currentTotal = now.size() + next.size();
515 if (currentTotal <= MAX) {
516 String key = keyNow.charAt(0) + "-"
517 + keyNext.charAt(keyNext.length() - 1);
518
519 List<String> all = new ArrayList<String>();
520 all.addAll(now);
521 all.addAll(next);
522
523 groups.remove(keyNow);
524 groups.remove(keyNext);
525 groups.put(key, all);
526
527 keys.set(i, key); // set the new key instead of key(i)
528 keys.remove(i + 1); // remove the next, consumed key
529 i--; // restart at key(i)
530 }
531 }
532
533 // Add "special" groups
534 groups.put("*", getAuthorsGroup(authors, '*'));
535 groups.put("0-9", getAuthorsGroup(authors, '0'));
536
537 // Prune empty groups
538 keys = new ArrayList<String>(groups.keySet());
539 for (String key : keys) {
540 if (groups.get(key).isEmpty()) {
541 groups.remove(key);
542 }
543 }
544
545 return groups;
546 }
547
548 /**
549 * Get all the authors that start with the given character:
550 * <ul>
551 * <li><tt>*</tt>: any author whose name doesn't contain letters nor numbers
552 * </li>
553 * <li><tt>0</tt>: any authors whose name starts with a number</li>
554 * <li><tt>A</tt> (any capital latin letter): any author whose name starts
555 * with <tt>A</tt></li>
556 * </ul>
557 *
558 * @param authors
559 * the full list of authors
560 * @param car
561 * the starting character, <tt>*</tt>, <tt>0</tt> or a capital
562 * letter
563 *
564 * @return the authors that fulfil the starting letter
565 */
566 private List<String> getAuthorsGroup(List<String> authors, char car) {
567 List<String> accepted = new ArrayList<String>();
568 for (String author : authors) {
569 char first = '*';
570 for (int i = 0; first == '*' && i < author.length(); i++) {
571 String san = StringUtils.sanitize(author, true, true);
572 char c = san.charAt(i);
573 if (c >= '0' && c <= '9') {
574 first = '0';
575 } else if (c >= 'a' && c <= 'z') {
576 first = (char) (c - 'a' + 'A');
577 } else if (c >= 'A' && c <= 'Z') {
578 first = c;
579 }
580 }
581
582 if (first == car) {
583 accepted.add(author);
584 }
585 }
586
587 return accepted;
588 }
589
590 /**
591 * List all the stories in the {@link BasicLibrary}.
592 * <p>
593 * Cover images <b>MAYBE</b> not included.
594 *
595 * @return the stories
596 *
597 * @throws IOException
598 * in case of IOException
599 */
600 public synchronized List<MetaData> getList() throws IOException {
601 return getMetas(null);
602 }
603
604 /**
605 * List all the stories of the given source type in the {@link BasicLibrary} ,
606 * or all the stories if NULL is passed as a type.
607 * <p>
608 * Cover images not included.
609 *
610 * @param source the type of story to retrieve, or NULL for all
611 *
612 * @return the stories
613 *
614 * @throws IOException in case of IOException
615 *
616 * @deprecated use {@link BasicLibrary#getList(Progress)} and
617 * {@link MetaResultList#filter(String, String, String)}
618 */
619 @Deprecated
620 public synchronized List<MetaData> getListBySource(String source) throws IOException {
621 return getList(null).filter(source, null, null);
622 }
623
624 /**
625 * List all the stories of the given author in the {@link BasicLibrary}, or
626 * all the stories if NULL is passed as an author.
627 * <p>
628 * Cover images not included.
629 *
630 * @param author
631 * the author of the stories to retrieve, or NULL for all
632 *
633 * @return the stories
634 *
635 * @throws IOException
636 * in case of IOException
637 *
638 * @deprecated use {@link BasicLibrary#getList(Progress)} and
639 * {@link MetaResultList#filter(String, String, String)}
640 */
641 public synchronized List<MetaData> getListByAuthor(String author) throws IOException {
642 return getList(null).filter(null, author, null);
643 }
644
645 /**
646 * Retrieve a {@link MetaData} corresponding to the given {@link Story},
647 * cover image <b>MAY</b> not be included.
648 *
649 * @param luid
650 * the Library UID of the story
651 *
652 * @return the corresponding {@link Story}
653 *
654 * @throws IOException
655 * in case of IOException
656 */
657 public synchronized MetaData getInfo(String luid) throws IOException {
658 if (luid != null) {
659 for (MetaData meta : getMetas(null)) {
660 if (luid.equals(meta.getLuid())) {
661 return meta;
662 }
663 }
664 }
665
666 return null;
667 }
668
669 /**
670 * Retrieve a specific {@link Story}.
671 *
672 * @param luid
673 * the Library UID of the story
674 * @param pg
675 * the optional progress reporter
676 *
677 * @return the corresponding {@link Story} or NULL if not found
678 *
679 * @throws IOException
680 * in case of IOException
681 */
682 public synchronized Story getStory(String luid, Progress pg)
683 throws IOException {
684 Progress pgMetas = new Progress();
685 Progress pgStory = new Progress();
686 if (pg != null) {
687 pg.setMinMax(0, 100);
688 pg.addProgress(pgMetas, 10);
689 pg.addProgress(pgStory, 90);
690 }
691
692 MetaData meta = null;
693 for (MetaData oneMeta : getMetas(pgMetas)) {
694 if (oneMeta.getLuid().equals(luid)) {
695 meta = oneMeta;
696 break;
697 }
698 }
699
700 pgMetas.done();
701
702 Story story = getStory(luid, meta, pgStory);
703 pgStory.done();
704
705 return story;
706 }
707
708 /**
709 * Retrieve a specific {@link Story}.
710 *
711 * @param luid
712 * the meta of the story
713 * @param pg
714 * the optional progress reporter
715 *
716 * @return the corresponding {@link Story} or NULL if not found
717 *
718 * @throws IOException
719 * in case of IOException
720 */
721 public synchronized Story getStory(String luid,
722 @SuppressWarnings("javadoc") MetaData meta, Progress pg)
723 throws IOException {
724
725 if (pg == null) {
726 pg = new Progress();
727 }
728
729 Progress pgGet = new Progress();
730 Progress pgProcess = new Progress();
731
732 pg.setMinMax(0, 2);
733 pg.addProgress(pgGet, 1);
734 pg.addProgress(pgProcess, 1);
735
736 Story story = null;
737 File file = getFile(luid, pgGet);
738 pgGet.done();
739 try {
740 SupportType type = SupportType.valueOfAllOkUC(meta.getType());
741 URL url = file.toURI().toURL();
742 if (type != null) {
743 story = BasicSupport.getSupport(type, url) //
744 .process(pgProcess);
745
746 // Because we do not want to clear the meta cache:
747 meta.setCover(story.getMeta().getCover());
748 meta.setResume(story.getMeta().getResume());
749 story.setMeta(meta);
750 //
751 } else {
752 throw new IOException("Unknown type: " + meta.getType());
753 }
754 } catch (IOException e) {
755 // We should not have not-supported files in the
756 // library
757 Instance.getInstance().getTraceHandler().error(new IOException(
758 String.format("Cannot load file of type '%s' from library: %s", meta.getType(), file), e));
759 } finally {
760 pgProcess.done();
761 pg.done();
762 }
763
764 return story;
765 }
766
767 /**
768 * Import the {@link Story} at the given {@link URL} into the
769 * {@link BasicLibrary}.
770 *
771 * @param url
772 * the {@link URL} to import
773 * @param pg
774 * the optional progress reporter
775 *
776 * @return the imported Story {@link MetaData}
777 *
778 * @throws UnknownHostException
779 * if the host is not supported
780 * @throws IOException
781 * in case of I/O error
782 */
783 public MetaData imprt(URL url, Progress pg) throws IOException {
784 if (pg == null)
785 pg = new Progress();
786
787 pg.setMinMax(0, 1000);
788 Progress pgProcess = new Progress();
789 Progress pgSave = new Progress();
790 pg.addProgress(pgProcess, 800);
791 pg.addProgress(pgSave, 200);
792
793 BasicSupport support = BasicSupport.getSupport(url);
794 if (support == null) {
795 throw new UnknownHostException("" + url);
796 }
797
798 Story story = save(support.process(pgProcess), pgSave);
799 pg.done();
800
801 return story.getMeta();
802 }
803
804 /**
805 * Import the story from one library to another, and keep the same LUID.
806 *
807 * @param other
808 * the other library to import from
809 * @param luid
810 * the Library UID
811 * @param pg
812 * the optional progress reporter
813 *
814 * @throws IOException
815 * in case of I/O error
816 */
817 public void imprt(BasicLibrary other, String luid, Progress pg)
818 throws IOException {
819 Progress pgGetStory = new Progress();
820 Progress pgSave = new Progress();
821 if (pg == null) {
822 pg = new Progress();
823 }
824
825 pg.setMinMax(0, 2);
826 pg.addProgress(pgGetStory, 1);
827 pg.addProgress(pgSave, 1);
828
829 Story story = other.getStory(luid, pgGetStory);
830 if (story != null) {
831 story = this.save(story, luid, pgSave);
832 pg.done();
833 } else {
834 pg.done();
835 throw new IOException("Cannot find story in Library: " + luid);
836 }
837 }
838
839 /**
840 * Export the {@link Story} to the given target in the given format.
841 *
842 * @param luid
843 * the {@link Story} ID
844 * @param type
845 * the {@link OutputType} to transform it to
846 * @param target
847 * the target to save to
848 * @param pg
849 * the optional progress reporter
850 *
851 * @return the saved resource (the main saved {@link File})
852 *
853 * @throws IOException
854 * in case of I/O error
855 */
856 public File export(String luid, OutputType type, String target, Progress pg)
857 throws IOException {
858 Progress pgGetStory = new Progress();
859 Progress pgOut = new Progress();
860 if (pg != null) {
861 pg.setMax(2);
862 pg.addProgress(pgGetStory, 1);
863 pg.addProgress(pgOut, 1);
864 }
865
866 BasicOutput out = BasicOutput.getOutput(type, false, false);
867 if (out == null) {
868 throw new IOException("Output type not supported: " + type);
869 }
870
871 Story story = getStory(luid, pgGetStory);
872 if (story == null) {
873 throw new IOException("Cannot find story to export: " + luid);
874 }
875
876 return out.process(story, target, pgOut);
877 }
878
879 /**
880 * Save a {@link Story} to the {@link BasicLibrary}.
881 *
882 * @param story
883 * the {@link Story} to save
884 * @param pg
885 * the optional progress reporter
886 *
887 * @return the same {@link Story}, whose LUID may have changed
888 *
889 * @throws IOException
890 * in case of I/O error
891 */
892 public Story save(Story story, Progress pg) throws IOException {
893 return save(story, null, pg);
894 }
895
896 /**
897 * Save a {@link Story} to the {@link BasicLibrary} -- the LUID <b>must</b>
898 * be correct, or NULL to get the next free one.
899 * <p>
900 * Will override any previous {@link Story} with the same LUID.
901 *
902 * @param story
903 * the {@link Story} to save
904 * @param luid
905 * the <b>correct</b> LUID or NULL to get the next free one
906 * @param pg
907 * the optional progress reporter
908 *
909 * @return the same {@link Story}, whose LUID may have changed
910 *
911 * @throws IOException
912 * in case of I/O error
913 */
914 public synchronized Story save(Story story, String luid, Progress pg)
915 throws IOException {
916
917 Instance.getInstance().getTraceHandler().trace(this.getClass().getSimpleName() + ": saving story " + luid);
918
919 // Do not change the original metadata, but change the original story
920 MetaData meta = story.getMeta().clone();
921 story.setMeta(meta);
922
923 if (luid == null || luid.isEmpty()) {
924 meta.setLuid(String.format("%03d", getNextId()));
925 } else {
926 meta.setLuid(luid);
927 }
928
929 if (luid != null && getInfo(luid) != null) {
930 delete(luid);
931 }
932
933 story = doSave(story, pg);
934
935 updateInfo(story.getMeta());
936
937 Instance.getInstance().getTraceHandler()
938 .trace(this.getClass().getSimpleName() + ": story saved (" + luid + ")");
939
940 return story;
941 }
942
943 /**
944 * Delete the given {@link Story} from this {@link BasicLibrary}.
945 *
946 * @param luid
947 * the LUID of the target {@link Story}
948 *
949 * @throws IOException
950 * in case of I/O error
951 */
952 public synchronized void delete(String luid) throws IOException {
953 Instance.getInstance().getTraceHandler().trace(this.getClass().getSimpleName() + ": deleting story " + luid);
954
955 doDelete(luid);
956 invalidateInfo(luid);
957
958 Instance.getInstance().getTraceHandler()
959 .trace(this.getClass().getSimpleName() + ": story deleted (" + luid
960 + ")");
961 }
962
963 /**
964 * Change the type (source) of the given {@link Story}.
965 *
966 * @param luid
967 * the {@link Story} LUID
968 * @param newSource
969 * the new source
970 * @param pg
971 * the optional progress reporter
972 *
973 * @throws IOException
974 * in case of I/O error or if the {@link Story} was not found
975 */
976 public synchronized void changeSource(String luid, String newSource,
977 Progress pg) throws IOException {
978 MetaData meta = getInfo(luid);
979 if (meta == null) {
980 throw new IOException("Story not found: " + luid);
981 }
982
983 changeSTA(luid, newSource, meta.getTitle(), meta.getAuthor(), pg);
984 }
985
986 /**
987 * Change the title (name) of the given {@link Story}.
988 *
989 * @param luid
990 * the {@link Story} LUID
991 * @param newTitle
992 * the new title
993 * @param pg
994 * the optional progress reporter
995 *
996 * @throws IOException
997 * in case of I/O error or if the {@link Story} was not found
998 */
999 public synchronized void changeTitle(String luid, String newTitle,
1000 Progress pg) throws IOException {
1001 MetaData meta = getInfo(luid);
1002 if (meta == null) {
1003 throw new IOException("Story not found: " + luid);
1004 }
1005
1006 changeSTA(luid, meta.getSource(), newTitle, meta.getAuthor(), pg);
1007 }
1008
1009 /**
1010 * Change the author of the given {@link Story}.
1011 *
1012 * @param luid
1013 * the {@link Story} LUID
1014 * @param newAuthor
1015 * the new author
1016 * @param pg
1017 * the optional progress reporter
1018 *
1019 * @throws IOException
1020 * in case of I/O error or if the {@link Story} was not found
1021 */
1022 public synchronized void changeAuthor(String luid, String newAuthor,
1023 Progress pg) throws IOException {
1024 MetaData meta = getInfo(luid);
1025 if (meta == null) {
1026 throw new IOException("Story not found: " + luid);
1027 }
1028
1029 changeSTA(luid, meta.getSource(), meta.getTitle(), newAuthor, pg);
1030 }
1031
1032 /**
1033 * Change the Source, Title and Author of the {@link Story} in one single
1034 * go.
1035 *
1036 * @param luid
1037 * the {@link Story} LUID
1038 * @param newSource
1039 * the new source
1040 * @param newTitle
1041 * the new title
1042 * @param newAuthor
1043 * the new author
1044 * @param pg
1045 * the optional progress reporter
1046 *
1047 * @throws IOException
1048 * in case of I/O error or if the {@link Story} was not found
1049 */
1050 protected synchronized void changeSTA(String luid, String newSource,
1051 String newTitle, String newAuthor, Progress pg) throws IOException {
1052 MetaData meta = getInfo(luid);
1053 if (meta == null) {
1054 throw new IOException("Story not found: " + luid);
1055 }
1056
1057 meta.setSource(newSource);
1058 meta.setTitle(newTitle);
1059 meta.setAuthor(newAuthor);
1060 saveMeta(meta, pg);
1061
1062 invalidateInfo(luid);
1063 }
1064
1065 /**
1066 * Save back the current state of the {@link MetaData} (LUID <b>MUST NOT</b>
1067 * change) for this {@link Story}.
1068 * <p>
1069 * By default, delete the old {@link Story} then recreate a new
1070 * {@link Story}.
1071 * <p>
1072 * Note that this behaviour can lead to data loss in case of problems!
1073 *
1074 * @param meta
1075 * the new {@link MetaData} (LUID <b>MUST NOT</b> change)
1076 * @param pg
1077 * the optional {@link Progress}
1078 *
1079 * @throws IOException
1080 * in case of I/O error or if the {@link Story} was not found
1081 */
1082 protected synchronized void saveMeta(MetaData meta, Progress pg)
1083 throws IOException {
1084 if (pg == null) {
1085 pg = new Progress();
1086 }
1087
1088 Progress pgGet = new Progress();
1089 Progress pgSet = new Progress();
1090 pg.addProgress(pgGet, 50);
1091 pg.addProgress(pgSet, 50);
1092
1093 Story story = getStory(meta.getLuid(), pgGet);
1094 if (story == null) {
1095 throw new IOException("Story not found: " + meta.getLuid());
1096 }
1097
1098 // TODO: this is not safe!
1099 delete(meta.getLuid());
1100 story.setMeta(meta);
1101 save(story, meta.getLuid(), pgSet);
1102
1103 pg.done();
1104 }
1105 }