82f3fa28a0f53c6c94671e86ef491670f871145c
1 package be
.nikiroo
.fanfix
.library
;
4 import java
.io
.IOException
;
6 import java
.net
.UnknownHostException
;
7 import java
.util
.ArrayList
;
8 import java
.util
.Collections
;
11 import java
.util
.TreeMap
;
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
;
25 * Manage a library of Stories: import, export, list, modify.
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}.
30 * Most of the {@link BasicLibrary} functions work on a partial (cover
31 * <b>MAY</b> not be included) {@link MetaData} object.
35 abstract public class BasicLibrary
{
37 * A {@link BasicLibrary} status.
42 /** The library is ready and r/w. */
44 /** The library is ready, but read-only. */
46 /** The library is invalid (not correctly set up). */
48 /** You are not allowed to access this library. */
50 /** The library is currently out of commission. */
54 * The library is available (you can query it).
56 * It does <b>not</b> specify if it is read-only or not.
58 * @return TRUE if it is
60 public boolean isReady() {
61 return (this == READ_WRITE
|| this == READ_ONLY
);
65 * This library can be modified (= you are allowed to modify it).
67 * @return TRUE if it is
69 public boolean isWritable() {
70 return (this == READ_WRITE
);
75 * Return a name for this library (the UI may display this).
79 * @return the name, or an empty {@link String} if none
81 public String
getLibraryName() {
88 * @return the current status
90 public Status
getStatus() {
91 return Status
.READ_WRITE
;
95 * Retrieve the main {@link File} corresponding to the given {@link Story},
96 * which can be passed to an external reader or instance.
98 * Do <b>NOT</b> alter this file.
101 * the Library UID of the story, can be NULL
103 * the optional {@link Progress}
105 * @return the corresponding {@link Story}
107 * @throws IOException
108 * in case of IOException
110 public abstract File
getFile(String luid
, Progress pg
) throws IOException
;
113 * Return the cover image associated to this story.
116 * the Library UID of the story
118 * @return the cover image
120 * @throws IOException
121 * in case of IOException
123 public abstract Image
getCover(String luid
) throws IOException
;
125 // TODO: ensure it is the main used interface
126 public MetaResultList
getList(Progress pg
) throws IOException
{
127 return new MetaResultList(getMetas(pg
));
130 // TODO: make something for (normal and custom) not-story covers
133 * Return the cover image associated to this source.
135 * By default, return the custom cover if any, and if not, return the cover
136 * of the first story with this source.
141 * @return the cover image or NULL
143 * @throws IOException
144 * in case of IOException
146 public Image
getSourceCover(String source
) throws IOException
{
147 Image custom
= getCustomSourceCover(source
);
148 if (custom
!= null) {
152 List
<MetaData
> metas
= getList().filter(source
, null, null);
153 if (metas
.size() > 0) {
154 return getCover(metas
.get(0).getLuid());
161 * Return the cover image associated to this author.
163 * By default, return the custom cover if any, and if not, return the cover
164 * of the first story with this author.
169 * @return the cover image or NULL
171 * @throws IOException
172 * in case of IOException
174 public Image
getAuthorCover(String author
) throws IOException
{
175 Image custom
= getCustomAuthorCover(author
);
176 if (custom
!= null) {
180 List
<MetaData
> metas
= getList().filter(null, author
, null);
181 if (metas
.size() > 0) {
182 return getCover(metas
.get(0).getLuid());
189 * Return the custom cover image associated to this source.
191 * By default, return NULL.
194 * the source to look for
196 * @return the custom cover or NULL if none
198 * @throws IOException
199 * in case of IOException
201 @SuppressWarnings("unused")
202 public Image
getCustomSourceCover(String source
) throws IOException
{
207 * Return the custom cover image associated to this author.
209 * By default, return NULL.
212 * the author to look for
214 * @return the custom cover or NULL if none
216 * @throws IOException
217 * in case of IOException
219 @SuppressWarnings("unused")
220 public Image
getCustomAuthorCover(String author
) throws IOException
{
225 * Set the source cover to the given story cover.
228 * the source to change
232 * @throws IOException
233 * in case of IOException
235 public abstract void setSourceCover(String source
, String luid
)
239 * Set the author cover to the given story cover.
242 * the author to change
246 * @throws IOException
247 * in case of IOException
249 public abstract void setAuthorCover(String author
, String luid
)
253 * Return the list of stories (represented by their {@link MetaData}, which
254 * <b>MAY</b> not have the cover included).
256 * The returned list <b>MUST</b> be a copy, not the original one.
259 * the optional {@link Progress}
261 * @return the list (can be empty but not NULL)
263 * @throws IOException
264 * in case of IOException
266 protected abstract List
<MetaData
> getMetas(Progress pg
) throws IOException
;
269 * Invalidate the {@link Story} cache (when the content should be re-read
270 * because it was changed).
272 protected void invalidateInfo() {
273 invalidateInfo(null);
277 * Invalidate the {@link Story} cache (when the content is removed).
279 * All the cache can be deleted if NULL is passed as meta.
282 * the LUID of the {@link Story} to clear from the cache, or NULL
285 protected abstract void invalidateInfo(String luid
);
288 * Invalidate the {@link Story} cache (when the content has changed, but we
289 * already have it) with the new given meta.
292 * the {@link Story} to clear from the cache
294 * @throws IOException
295 * in case of IOException
297 protected abstract void updateInfo(MetaData meta
) throws IOException
;
300 * Return the next LUID that can be used.
302 * @return the next luid
304 protected abstract int getNextId();
307 * Delete the target {@link Story}.
310 * the LUID of the {@link Story}
312 * @throws IOException
313 * in case of I/O error or if the {@link Story} wa not found
315 protected abstract void doDelete(String luid
) throws IOException
;
318 * Actually save the story to the back-end.
321 * the {@link Story} to save
323 * the optional {@link Progress}
325 * @return the saved {@link Story} (which may have changed, especially
326 * regarding the {@link MetaData})
328 * @throws IOException
329 * in case of I/O error
331 protected abstract Story
doSave(Story story
, Progress pg
)
335 * Refresh the {@link BasicLibrary}, that is, make sure all metas are
339 * the optional progress reporter
341 public void refresh(Progress pg
) {
344 } catch (IOException e
) {
345 // We will let it fail later
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 </tt>true</tt>).
356 * @return TRUE if it is
358 public boolean isCached(@SuppressWarnings("unused") String luid
) {
359 // By default, everything is cached
364 * Clear the {@link Story} from the cache, if needed.
366 * The next time we try to retrieve the {@link Story}, it may be required to
372 * @throws IOException
373 * in case of I/O error
375 @SuppressWarnings("unused")
376 public void clearFromCache(String luid
) throws IOException
{
377 // By default, this is a noop.
381 * @deprecated please use {@link BasicLibrary#getList()} and
382 * {@link MetaResultList#getSources()} instead.
385 public List
<String
> getSources() throws IOException
{
386 return getList().getSources();
390 * @deprecated please use {@link BasicLibrary#getList()} and
391 * {@link MetaResultList#getSourcesGrouped()} instead.
394 public Map
<String
, List
<String
>> getSourcesGrouped() throws IOException
{
395 return getList().getSourcesGrouped();
399 * @deprecated please use {@link BasicLibrary#getList()} and
400 * {@link MetaResultList#getAuthors()} instead.
403 public List
<String
> getAuthors() throws IOException
{
404 return getList().getAuthors();
408 * @deprecated please use {@link BasicLibrary#getList()} and
409 * {@link MetaResultList#getAuthorsGrouped()} instead.
411 public Map
<String
, List
<String
>> getAuthorsGrouped() throws IOException
{
412 return getList().getAuthorsGrouped();
416 * List all the stories in the {@link BasicLibrary}.
418 * Cover images <b>MAYBE</b> not included.
420 * @return the stories
422 * @throws IOException
423 * in case of IOException
425 public MetaResultList
getList() throws IOException
{
426 return getList(null);
430 * Retrieve a {@link MetaData} corresponding to the given {@link Story},
431 * cover image <b>MAY</b> not be included.
434 * the Library UID of the story, can be NULL
436 * @return the corresponding {@link Story} or NULL if not found
438 * @throws IOException
439 * in case of IOException
441 public MetaData
getInfo(String luid
) throws IOException
{
443 for (MetaData meta
: getMetas(null)) {
444 if (luid
.equals(meta
.getLuid())) {
454 * Retrieve a specific {@link Story}.
457 * the Library UID of the story
459 * the optional progress reporter
461 * @return the corresponding {@link Story} or NULL if not found
463 * @throws IOException
464 * in case of IOException
466 public Story
getStory(String luid
, Progress pg
) throws IOException
{
467 Progress pgMetas
= new Progress();
468 Progress pgStory
= new Progress();
470 pg
.setMinMax(0, 100);
471 pg
.addProgress(pgMetas
, 10);
472 pg
.addProgress(pgStory
, 90);
475 MetaData meta
= null;
476 for (MetaData oneMeta
: getMetas(pgMetas
)) {
477 if (oneMeta
.getLuid().equals(luid
)) {
485 Story story
= getStory(luid
, meta
, pgStory
);
492 * Retrieve a specific {@link Story}.
495 * the LUID of the story
497 * the meta of the story
499 * the optional progress reporter
501 * @return the corresponding {@link Story} or NULL if not found
503 * @throws IOException
504 * in case of IOException
506 public synchronized Story
getStory(String luid
, MetaData meta
, Progress pg
)
513 Progress pgGet
= new Progress();
514 Progress pgProcess
= new Progress();
517 pg
.addProgress(pgGet
, 1);
518 pg
.addProgress(pgProcess
, 1);
523 if (luid
!= null && meta
!= null) {
524 file
= getFile(luid
, pgGet
);
530 SupportType type
= SupportType
.valueOfAllOkUC(meta
.getType());
532 throw new IOException("Unknown type: " + meta
.getType());
535 URL url
= file
.toURI().toURL();
536 story
= BasicSupport
.getSupport(type
, url
) //
539 // Because we do not want to clear the meta cache:
540 meta
.setCover(story
.getMeta().getCover());
541 meta
.setResume(story
.getMeta().getResume());
544 } catch (IOException e
) {
545 // We should not have not-supported files in the library
546 Instance
.getInstance().getTraceHandler()
547 .error(new IOException(String
.format(
548 "Cannot load file of type '%s' from library: %s",
549 meta
.getType(), file
), e
));
559 * Import the {@link Story} at the given {@link URL} into the
560 * {@link BasicLibrary}.
563 * the {@link URL} to import
565 * the optional progress reporter
567 * @return the imported Story {@link MetaData}
569 * @throws UnknownHostException
570 * if the host is not supported
571 * @throws IOException
572 * in case of I/O error
574 public MetaData
imprt(URL url
, Progress pg
) throws IOException
{
578 pg
.setMinMax(0, 1000);
579 Progress pgProcess
= new Progress();
580 Progress pgSave
= new Progress();
581 pg
.addProgress(pgProcess
, 800);
582 pg
.addProgress(pgSave
, 200);
584 BasicSupport support
= BasicSupport
.getSupport(url
);
585 if (support
== null) {
586 throw new UnknownHostException("" + url
);
589 Story story
= save(support
.process(pgProcess
), pgSave
);
590 pg
.setName(story
.getMeta().getTitle());
593 return story
.getMeta();
597 * Import the story from one library to another, and keep the same LUID.
600 * the other library to import from
604 * the optional progress reporter
606 * @throws IOException
607 * in case of I/O error
609 public void imprt(BasicLibrary other
, String luid
, Progress pg
)
611 Progress pgGetStory
= new Progress();
612 Progress pgSave
= new Progress();
618 pg
.addProgress(pgGetStory
, 1);
619 pg
.addProgress(pgSave
, 1);
621 Story story
= other
.getStory(luid
, pgGetStory
);
623 story
= this.save(story
, luid
, pgSave
);
627 throw new IOException("Cannot find story in Library: " + luid
);
632 * Export the {@link Story} to the given target in the given format.
635 * the {@link Story} ID
637 * the {@link OutputType} to transform it to
639 * the target to save to
641 * the optional progress reporter
643 * @return the saved resource (the main saved {@link File})
645 * @throws IOException
646 * in case of I/O error
648 public File
export(String luid
, OutputType type
, String target
, Progress pg
)
650 Progress pgGetStory
= new Progress();
651 Progress pgOut
= new Progress();
654 pg
.addProgress(pgGetStory
, 1);
655 pg
.addProgress(pgOut
, 1);
658 BasicOutput out
= BasicOutput
.getOutput(type
, false, false);
660 throw new IOException("Output type not supported: " + type
);
663 Story story
= getStory(luid
, pgGetStory
);
665 throw new IOException("Cannot find story to export: " + luid
);
668 return out
.process(story
, target
, pgOut
);
672 * Save a {@link Story} to the {@link BasicLibrary}.
675 * the {@link Story} to save
677 * the optional progress reporter
679 * @return the same {@link Story}, whose LUID may have changed
681 * @throws IOException
682 * in case of I/O error
684 public Story
save(Story story
, Progress pg
) throws IOException
{
685 return save(story
, null, pg
);
689 * Save a {@link Story} to the {@link BasicLibrary} -- the LUID <b>must</b>
690 * be correct, or NULL to get the next free one.
692 * Will override any previous {@link Story} with the same LUID.
695 * the {@link Story} to save
697 * the <b>correct</b> LUID or NULL to get the next free one
699 * the optional progress reporter
701 * @return the same {@link Story}, whose LUID may have changed
703 * @throws IOException
704 * in case of I/O error
706 public synchronized Story
save(Story story
, String luid
, Progress pg
)
712 Instance
.getInstance().getTraceHandler().trace(
713 this.getClass().getSimpleName() + ": saving story " + luid
);
715 // Do not change the original metadata, but change the original story
716 MetaData meta
= story
.getMeta().clone();
719 pg
.setName("Saving story");
721 if (luid
== null || luid
.isEmpty()) {
722 meta
.setLuid(String
.format("%03d", getNextId()));
727 if (luid
!= null && getInfo(luid
) != null) {
731 story
= doSave(story
, pg
);
733 updateInfo(story
.getMeta());
735 Instance
.getInstance().getTraceHandler()
736 .trace(this.getClass().getSimpleName() + ": story saved ("
739 pg
.setName(meta
.getTitle());
745 * Delete the given {@link Story} from this {@link BasicLibrary}.
748 * the LUID of the target {@link Story}
750 * @throws IOException
751 * in case of I/O error
753 public synchronized void delete(String luid
) throws IOException
{
754 Instance
.getInstance().getTraceHandler().trace(
755 this.getClass().getSimpleName() + ": deleting story " + luid
);
758 invalidateInfo(luid
);
760 Instance
.getInstance().getTraceHandler()
761 .trace(this.getClass().getSimpleName() + ": story deleted ("
766 * Change the type (source) of the given {@link Story}.
769 * the {@link Story} LUID
773 * the optional progress reporter
775 * @throws IOException
776 * in case of I/O error or if the {@link Story} was not found
778 public synchronized void changeSource(String luid
, String newSource
,
779 Progress pg
) throws IOException
{
780 MetaData meta
= getInfo(luid
);
782 throw new IOException("Story not found: " + luid
);
785 changeSTA(luid
, newSource
, meta
.getTitle(), meta
.getAuthor(), pg
);
789 * Change the title (name) of the given {@link Story}.
792 * the {@link Story} LUID
796 * the optional progress reporter
798 * @throws IOException
799 * in case of I/O error or if the {@link Story} was not found
801 public synchronized void changeTitle(String luid
, String newTitle
,
802 Progress pg
) throws IOException
{
803 MetaData meta
= getInfo(luid
);
805 throw new IOException("Story not found: " + luid
);
808 changeSTA(luid
, meta
.getSource(), newTitle
, meta
.getAuthor(), pg
);
812 * Change the author of the given {@link Story}.
815 * the {@link Story} LUID
819 * the optional progress reporter
821 * @throws IOException
822 * in case of I/O error or if the {@link Story} was not found
824 public synchronized void changeAuthor(String luid
, String newAuthor
,
825 Progress pg
) throws IOException
{
826 MetaData meta
= getInfo(luid
);
828 throw new IOException("Story not found: " + luid
);
831 changeSTA(luid
, meta
.getSource(), meta
.getTitle(), newAuthor
, pg
);
835 * Change the Source, Title and Author of the {@link Story} in one single
839 * the {@link Story} LUID
847 * the optional progress reporter
849 * @throws IOException
850 * in case of I/O error or if the {@link Story} was not found
852 protected synchronized void changeSTA(String luid
, String newSource
,
853 String newTitle
, String newAuthor
, Progress pg
) throws IOException
{
854 MetaData meta
= getInfo(luid
);
856 throw new IOException("Story not found: " + luid
);
859 meta
.setSource(newSource
);
860 meta
.setTitle(newTitle
);
861 meta
.setAuthor(newAuthor
);
866 * Save back the current state of the {@link MetaData} (LUID <b>MUST NOT</b>
867 * change) for this {@link Story}.
869 * By default, delete the old {@link Story} then recreate a new
872 * Note that this behaviour can lead to data loss in case of problems!
875 * the new {@link MetaData} (LUID <b>MUST NOT</b> change)
877 * the optional {@link Progress}
879 * @throws IOException
880 * in case of I/O error or if the {@link Story} was not found
882 protected synchronized void saveMeta(MetaData meta
, Progress pg
)
888 Progress pgGet
= new Progress();
889 Progress pgSet
= new Progress();
890 pg
.addProgress(pgGet
, 50);
891 pg
.addProgress(pgSet
, 50);
893 Story story
= getStory(meta
.getLuid(), pgGet
);
895 throw new IOException("Story not found: " + meta
.getLuid());
898 // TODO: this is not safe!
899 delete(meta
.getLuid());
901 save(story
, meta
.getLuid(), pgSet
);