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 it's authors.
19   *
20   */
21  package org.crosswire.jsword.book.install;
22  
23  import java.net.URI;
24  import java.util.List;
25  
26  import org.crosswire.jsword.book.Book;
27  import org.crosswire.jsword.book.BookList;
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 for license details.<br>
41   *      The copyright to this program is held by it's authors.
42   * @author Joe Walker [joe at eireneh dot com]
43   * @author DM Smith
44   */
45  public interface Installer extends BookList {
46      /**
47       * Get the type of the Installer.
48       * 
49       * @return the type of the installer
50       */
51      String getType();
52  
53      /**
54       * Accessor for the URI
55       * 
56       * @return the source URI
57       */
58      String getInstallerDefinition();
59  
60      /**
61       * @param book
62       *            The book meta-data to get a URI from.
63       * @return the remote URI for the BookMetaData
64       */
65      URI toRemoteURI(final Book book);
66  
67      /**
68       * Get a list of BookMetaData objects that represent downloadable books. If
69       * no list has been retrieved from the remote source using reloadIndex()
70       * then we should just return an empty list and not attempt to contact the
71       * remote source. See notes on reload for more information.
72       * 
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      Book getBook(final String Book);
81  
82      /**
83       * Return true if the book is not installed or there is a newer version to
84       * install.
85       * 
86       * @param book
87       *            The book meta-data to check on.
88       * @return whether there is a newer version to install
89       */
90      int getSize(final Book book);
91  
92      /**
93       * Return true if the book is not installed or there is a newer version to
94       * install.
95       * 
96       * @param book
97       *            The book meta-data to check on.
98       * @return whether there is a newer version to install
99       */
100     boolean isNewer(final Book book);
101 
102     /**
103      * Re-fetch a list of names from the remote source. <b>It would make sense
104      * if the user was warned about the implications of this action. If the user
105      * lives in a country that persecutes Christians then this action might give
106      * the game away.</b>
107      */
108     void reloadBookList() throws InstallException;
109 
110     /**
111      * Download and install a book locally. The name should be one from an index
112      * list retrieved from getIndex() or reloadIndex()
113      * 
114      * @param book
115      *            The book to install
116      */
117     void install(final Book book) throws InstallException;
118 
119     /**
120      * Download a search index for the given Book. The installation of the
121      * search index is the responsibility of the BookIndexer.
122      * 
123      * @param book
124      *            The book to download a search index for.
125      * @param tempDest
126      *            A temporary URI for downloading to. Passed to the BookIndexer
127      *            for installation.
128      */
129     void downloadSearchIndex(final Book book, final URI tempDest) throws InstallException;
130     
131     /** remove the cached book list to clear memory
132      */
133     void close();
134 }
135