001 /* PAVLOV -- Multiple Choice Study System
002 * Copyright (C) 2000 - 2004 T.J. Willis
003 *
004 * This program is free software; you can redistribute it and/or
005 * modify it under the terms of the GNU General Public License
006 * as published by the Free Software Foundation; either version 2
007 * of the License, or (at your option) any later version.
008 *
009 * This program is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
012 * GNU General Public License for more details.
013 *
014 * You should have received a copy of the GNU General Public License
015 * along with this program; if not, write to the Free Software
016 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
017 *
018 * $Header: /cvsroot/pavlov/net/sourceforge/pavlov/library/AbstractBook.java,v 1.5 2004/06/29 02:51:16 tj_willis Exp $
019 */
020 package net.sourceforge.pavlov.library;
021
022 import java.io.IOException;
023 import java.io.Writer;
024 import java.util.Collection;
025 import javax.swing.tree.DefaultMutableTreeNode;
026 import org.apache.log4j.*;
027
028 /**
029 * An interface to be implemented by classes that can act as Pavlov books.
030 * As of Pavlov 1.0, the only implementation is Book, which reads a book
031 * from an XML file. However, there's no reason that an implementation
032 * couldn't be written to generate its chapters and questions programmatically,
033 * i.e., an arithmetic book with chapters "Addition" and "Subtraction" who
034 * generate questions algorithmically from the question ID.
035 *
036 * @author <a href="mailto:tj_willis@users.sourceforge.net"></a>
037 * @version 1.0
038 * @has 1 Has 1..n net.sourceforge.pavlov.library.AbstractChapter
039 */
040 public interface AbstractBook extends Comparable {
041 // FIXME: programmatic books as plugins?
042 /**
043 * Returns name of the author/maintainer of this book.
044 * @return a <code>String</code> value
045 */
046 String getAuthor();
047
048 /**
049 * Returns the named chapter, or null if it doesn't exist
050 * @param cpName a <code>String</code> value
051 * @return a <code>Chapter</code> value
052 */
053 Chapter getChapter(String cpName);
054
055 /**
056 * Returns filename of a descriptive image of this book.
057 * @return a <code>String</code> value
058 */
059 String getCover();
060
061 /**
062 * Returns textual description of this book's contents.
063 * @return a <code>String</code> value
064 */
065 String getDescription();
066
067 /**
068 * Returns descriptive name of this book.
069 * @return a <code>String</code> value
070 */
071 String getName();
072
073 /**
074 * Sums the number of questions of all my chapters and returns the total.
075 * @return an <code>int</code> value
076 */
077 int getNumberOfQuestions();
078
079 /**
080 * Describe <code>getTitle</code> method here.
081 *
082 * @return a <code>String</code> value
083 * @deprecated use getName() instead.
084 */
085 @Deprecated String getTitle();
086
087 /**
088 * Returns the book's chapters as a collection.
089 * @return a <code>Collection</code> value
090 * @deprecated
091 */
092 @Deprecated Collection<AbstractChapter> getValues();
093
094 /**
095 * Returns the book's chapters as a read-only collection.
096 * @return a <code>Collection</code> value
097 */
098 Collection<AbstractChapter> getChaptersReadOnly();
099
100 /**
101 * Displays chapters as a tree.
102 * @param bk a <code>DefaultMutableTreeNode</code> value
103 */
104 void populateTree(DefaultMutableTreeNode bk);
105
106 /**
107 * Returns the book's name
108 * @return a <code>String</code> value
109 */
110 String toString();
111
112 /**
113 * Dumps the Book in XML format to the given writer.
114 * Loops throught chapters, questions.
115 * @param writer a <code>Writer</code> value
116 * @exception IOException if an error occurs
117 */
118 void toXML(Writer writer) throws IOException;
119
120 void save(java.io.File directory) throws IOException;
121 }