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   * Copyright: 2005
18   *     The copyright to this program is held by its authors.
19   *
20   */
21  package org.crosswire.jsword.book.install;
22  
23  import org.crosswire.jsword.book.Book;
24  import org.crosswire.jsword.book.BookList;
25  
26  import java.net.URI;
27  import java.util.List;
28  
29  /**
30   * An interface that allows us to download from a specific source of Bible data.
31   * It is important that implementor of this interface define equals() and
32   * hashCode() properly.
33   * 
34   * <p>
35   * To start with I only envisage that we use Sword sourced Bible data however
36   * the rest of the system is designed to be able to use data from e-Sword, OLB,
37   * etc.
38   * </p>
39   * 
40   * @see gnu.lgpl.License The GNU Lesser General Public License for details.
41   * @author Joe Walker
42   * @author DM Smith
43   */
44  public interface Installer extends BookList {
45      /**
46       * Get the type of the Installer.
47       * 
48       * @return the type of the installer
49       */
50      String getType();
51  
52      /**
53       * Accessor for the URI
54       * 
55       * @return the source URI
56       */
57      String getInstallerDefinition();
58  
59      /**
60       * @param book
61       *            The book meta-data to get a URI from.
62       * @return the remote URI for the BookMetaData
63       */
64      URI toRemoteURI(final Book book);
65  
66      /**
67       * Get a list of BookMetaData objects that represent downloadable books. If
68       * no list has been retrieved from the remote source using reloadIndex()
69       * then we should just return an empty list and not attempt to contact the
70       * remote source. See notes on reload for more information.
71       * 
72       * @return the list of books
73       * @see Installer#reloadBookList()
74       */
75      List<Book> getBooks();
76  
77      /**
78       * Get a Book matching the name from the local cache. Null if none is found.
79       * 
80       * @param book the book name
81       * @return the instantiated book
82       */
83      Book getBook(final String book);
84  
85      /**
86       * Return true if the book is not installed or there is a newer version to
87       * install.
88       * 
89       * @param book
90       *            The book meta-data to check on.
91       * @return whether there is a newer version to install
92       */
93      int getSize(final Book book);
94  
95      /**
96       * Return true if the book is not installed or there is a newer version to
97       * install.
98       * 
99       * @param book
100      *            The book meta-data to check on.
101      * @return whether there is a newer version to install
102      */
103     boolean isNewer(final Book book);
104 
105     /**
106      * Re-fetch a list of names from the remote source. <b>It would make sense
107      * if the user was warned about the implications of this action. If the user
108      * lives in a country that persecutes Christians then this action might give
109      * the game away.</b>
110      * 
111      * @throws InstallException 
112      */
113     void reloadBookList() throws InstallException;
114 
115     /**
116      * Download and install a book locally. The name should be one from an index
117      * list retrieved from getIndex() or reloadIndex()
118      * 
119      *
120      *
121      * @param book
122      *            The book to install
123      * @throws InstallException 
124      */
125     void install(final Book book) throws InstallException;
126 
127     /**
128      * Download a search index for the given Book. The installation of the
129      * search index is the responsibility of the BookIndexer.
130      * 
131      * @param book
132      *            The book to download a search index for.
133      * @param tempDest
134      *            A temporary URI for downloading to. Passed to the BookIndexer
135      *            for installation.
136      * @throws InstallException 
137      */
138     void downloadSearchIndex(final Book book, final URI tempDest) throws InstallException;
139 
140     /** remove the cached book list to clear memory
141      */
142     void close();
143 }
144