1   /**
2    * Distribution License:
3    * JSword is free software; you can redistribute it and/or modify it under
4    * the terms of the GNU Lesser General Public License, version 2.1 or later
5    * as published by the Free Software Foundation. This program is distributed
6    * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
7    * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
8    * See the GNU Lesser General Public License for more details.
9    *
10   * The License is available on the internet at:
11   *      http://www.gnu.org/copyleft/lgpl.html
12   * or by writing to:
13   *      Free Software Foundation, Inc.
14   *      59 Temple Place - Suite 330
15   *      Boston, MA 02111-1307, USA
16   *
17   * © CrossWire Bible Society, 2005 - 2016
18   *
19   */
20  package org.crosswire.jsword.book.install;
21  
22  import org.crosswire.jsword.book.Book;
23  import org.crosswire.jsword.book.BookList;
24  
25  import java.net.URI;
26  import java.util.List;
27  
28  /**
29   * An interface that allows us to download from a specific source of Bible data.
30   * It is important that implementor of this interface define equals() and
31   * hashCode() properly.
32   * 
33   * <p>
34   * To start with I only envisage that we use Sword sourced Bible data however
35   * the rest of the system is designed to be able to use data from e-Sword, OLB,
36   * etc.
37   * </p>
38   * 
39   * @see gnu.lgpl.License The GNU Lesser General Public License for details.
40   * @author Joe Walker
41   * @author DM Smith
42   */
43  public interface Installer extends BookList {
44      /**
45       * Get the type of the Installer.
46       * 
47       * @return the type of the installer
48       */
49      String getType();
50  
51      /**
52       * Accessor for the URI
53       * 
54       * @return the source URI
55       */
56      String getInstallerDefinition();
57  
58      /**
59       * @param book
60       *            The book meta-data to get a URI from.
61       * @return the remote URI for the BookMetaData
62       */
63      URI toRemoteURI(final Book book);
64  
65      /**
66       * Get a list of BookMetaData objects that represent downloadable books. If
67       * no list has been retrieved from the remote source using reloadIndex()
68       * then we should just return an empty list and not attempt to contact the
69       * remote source. See notes on reload for more information.
70       * 
71       * @return the list of books
72       * @see Installer#reloadBookList()
73       */
74      List<Book> getBooks();
75  
76      /**
77       * Get a Book matching the name from the local cache. Null if none is found.
78       * 
79       * @param book the book name
80       * @return the instantiated book
81       */
82      Book getBook(final String book);
83  
84      /**
85       * Return true if the book is not installed or there is a newer version to
86       * install.
87       * 
88       * @param book
89       *            The book meta-data to check on.
90       * @return whether there is a newer version to install
91       */
92      int getSize(final Book book);
93  
94      /**
95       * Return true if the book is not installed or there is a newer version to
96       * install.
97       * 
98       * @param book
99       *            The book meta-data to check on.
100      * @return whether there is a newer version to install
101      */
102     boolean isNewer(final Book book);
103 
104     /**
105      * Re-fetch a list of names from the remote source. <b>It would make sense
106      * if the user was warned about the implications of this action. If the user
107      * lives in a country that persecutes Christians then this action might give
108      * the game away.</b>
109      * 
110      * @throws InstallException 
111      */
112     void reloadBookList() throws InstallException;
113 
114     /**
115      * Download and install a book locally. The name should be one from an index
116      * list retrieved from getIndex() or reloadIndex()
117      * 
118      *
119      *
120      * @param book
121      *            The book to install
122      * @throws InstallException 
123      */
124     void install(final Book book) throws InstallException;
125 
126     /**
127      * Download a search index for the given Book. The installation of the
128      * search index is the responsibility of the BookIndexer.
129      * 
130      * @param book
131      *            The book to download a search index for.
132      * @param tempDest
133      *            A temporary URI for downloading to. Passed to the BookIndexer
134      *            for installation.
135      * @throws InstallException 
136      */
137     void downloadSearchIndex(final Book book, final URI tempDest) throws InstallException;
138 
139     /** remove the cached book list to clear memory
140      */
141     void close();
142 }
143