/* ----------------------------------------------------------------------------
   The Kiwi Toolkit - A Java Class Library
   Copyright (C) 1998-2004 Mark A. Lindner

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU General Public License as
   published by the Free Software Foundation; either version 2 of the
   License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this library; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
   02111-1307, USA.
 
   The author may be contacted at: mark_a_lindner@yahoo.com
   ----------------------------------------------------------------------------
   $Log: DocumentDataSource.java,v $
   Revision 1.7  2004/05/31 07:30:26  markl
   Final cleanup and bugfixes of kiwi.ui.model.

   Revision 1.6  2004/03/23 06:49:44  markl
   Use Boolean.valueOf(), not new Boolean()

   Revision 1.5  2003/01/19 09:33:06  markl
   Javadoc & comment header updates.

   Revision 1.4  2001/03/12 04:11:41  markl
   Source code cleanup.

   Revision 1.3  2000/07/31 02:02:13  markl
   Modified to use a document icon for non-expandable nodes.

   Revision 1.2  1999/01/10 03:12:19  markl
   added GPL header & RCS tag
   ----------------------------------------------------------------------------
*/

package kiwi.ui.model;

import java.io.*;
import java.net.*;
import java.util.*;
import javax.swing.*;

import kiwi.util.*;

/** This class is an implementation of <code>TreeDataSource</code>
  * in which tree nodes represent HTML documents that are loaded as system
  * resources.
  * <p>
  * Documents are loaded using the provided <code>ResourceManager</code>. The
  * default base path for the documents is "docs/", and since they are loaded
  * as URL resources, they should be located relative to "html/docs/" which in
  * turn will be relative to the <code>ResourceManager</code>'s resource anchor
  * class. One form of the constructor allows an alternate base path to be
  * specified.
  * <p>
  * Documents may be organized in a hierarchy; each expandable node in the
  * hierarchy corresponds to a directory in the resource file tree. Each
  * directory (including the root directory, "docs/") is expected to contain
  * an index file named "_index.txt" describing the child nodes of that
  * directory. Nodes are listed in this file, one per line. Each line should
  * include the following fields, delimited by vertical bar characters (|):
  * <p>
  * <dl>
  * <dt>Icon name
  * <dd>The name of the icon for this node. If an asterisk (*) is specified
  * for the name, a default icon will be used.
  * <dt>Alternate Icon name
  * <dd>The name of an alternate icon for this node. This is the icon that
  * is used to display expanded nodes. If an asterisk (*) is specified for the
  * name, a default icon will be used. If a dash (-) is specified for the name,
  * the alternate icon will be the same as the normal icon (above).
  * <dt>Expandability flag
  * <dd>One of the characters '+' or '-', denoting expandable and
  * non-expandable, respectively.
  * <dt>Node label
  * <dd>A human-readable, brief textual description of the node.
  * <dt>File
  * <dd>The file corresponding to this resource--either a directory name if
  * this is an expandable node, or a filename if this is a leaf (document)
  * node.
  * </dl>
  * <p>
  * Here is an example entry:
  * <p>
  * <tt>book-closed.gif|book-open.gif|+|API Specification|api</tt>
  *
  * @see kiwi.util.ResourceManager
  * @see kiwi.ui.DocumentBrowserView
  * @see kiwi.ui.DocumentBrowserFrame
  *
  * @author Mark Lindner
  */

public class DocumentDataSource implements TreeDataSource
  {
  private ResourceManager resmgr;
  private String basePath;
  private DocumentNode root;
  private static Icon DOCUMENT_ICON = KiwiUtils.getResourceManager()
     .getIcon("document.gif");
  private static Icon BOOKS_ICON = KiwiUtils.getResourceManager()
     .getIcon("books.gif");
  private static Icon UNKNOWN_ICON = KiwiUtils.getResourceManager()
    .getIcon("document-unknown.gif");
  private static Icon BOOK_OPEN_ICON = KiwiUtils.getResourceManager()
    .getIcon("book-open.gif");
  private static Icon BOOK_CLOSED_ICON = KiwiUtils.getResourceManager()
    .getIcon("book-closed.gif");
  private static final String INDEX_FILE = "_index.txt";
  /** The default description of this set of documents. */
  public static final String DEFAULT_DESCRIPTION = "Help Topics";
  /** The default relative document base path. */
  public static final String DEFAULT_BASEPATH = "docs/";
  
  /** Construct a new <code>DocumentDataSource</code> with a default
    * description and base path.
    *
    * @param manager the <code>ResourceManager</code> that will be used to load
    * index files for the tree.
    */

  public DocumentDataSource(ResourceManager manager)
    {
    this(manager, DEFAULT_DESCRIPTION, DEFAULT_BASEPATH);
    }

  /** Construct a new <code>DocumentDataSource</code> with the specified
    * description and base path.
    *
    * @param manager The <code>ResourceManager</code> that will be used to load
    * index files for the tree.
    * @param description A brief description of this set of documents; this
    * becomes the label for the root node in the tree.
    */
  
  public DocumentDataSource(ResourceManager manager, String description,
                            String basePath)
    {
    this.resmgr = manager;
    if(! basePath.endsWith("/"))
      basePath += "/";
    this.basePath = basePath;

    URL rootURL = resmgr.getURL(basePath + INDEX_FILE);
    root = new DocumentNode(null, description, BOOKS_ICON, null, rootURL,
                            true, "");
    }

  /** Get the root object. */

  public Object getRoot()
    {
    return(root);
    }

  /** Get the children of a given node. */

  public Object[] getChildren(Object node)
    {
    DocumentNode n = (DocumentNode)node;
    Vector children = new Vector();

    try
      {
      String s;
      DocumentNode sect;

      InputStream is = n.getURL().openStream();
      BufferedReader reader = new BufferedReader(new InputStreamReader(is));

      while((s = reader.readLine()) != null)
        {
        if((sect = parseLine(n, s)) != null)
          children.addElement(sect);
        }
      reader.close();
      is.close();
      }
    catch(IOException ex)
      {
      }

    Object childlist[] = new Object[children.size()];
    children.copyInto(childlist);

    return(childlist);
    }

  public boolean isExpandable(Object node)
    { 
    DocumentNode doc = (DocumentNode)node;

    return(doc.isExpandable());
    }

  public Icon getIcon(Object node, boolean isExpanded)
    {
    DocumentNode doc = (DocumentNode)node;

    return(isExpanded ? doc.getAltIcon() : doc.getIcon());
    }

  public String getLabel(Object node)
    {
    DocumentNode doc = (DocumentNode)node;

    return(doc.getLabel());
    }
  
  /** Get the value for a given property. */

  public Object getValueForProperty(Object node, String property)
    {
    return(null);
    }

  /* parse a line of an index file */

  private DocumentNode parseLine(DocumentNode parent, String line)
    {
    StringTokenizer st = new StringTokenizer(line, "|");
    if(st.countTokens() != 5) return(null);

    String file;
    String iconName = st.nextToken();
    String altIconName = st.nextToken();
    boolean expandable = st.nextToken().equals("+");
    URL url;

    Icon icon = null, alticon = null;

    if(iconName.equals("*"))
      icon = (expandable ? BOOK_CLOSED_ICON : DOCUMENT_ICON);
    else
      icon = resmgr.getIcon(iconName);

    if(altIconName.equals("*"))
      alticon = (expandable ? BOOK_OPEN_ICON : DOCUMENT_ICON);
    else if(!altIconName.equals("-"))
      alticon = resmgr.getIcon(altIconName);

    String label = st.nextToken();

    try
      {
      String parentURL = parent.getURL().toString();
      int idx = parentURL.lastIndexOf("/");
      file = st.nextToken();
      String temp = parentURL.substring(0, idx) + "/" + file;
      if(expandable)
        temp += "/" + INDEX_FILE;
      url = new URL(temp);
      }
    catch(MalformedURLException ex)
      {
      return(null);
      }

    return(new DocumentNode(parent, label, icon, alticon, url, expandable,
                            file));
    }
  
  /* Internal class for managing help nodes. */

  public class DocumentNode
    {
    private String label, file;
    private Icon icon, alticon;
    private URL url;
    private boolean expandable;
    private DocumentNode parent = null;

    DocumentNode(DocumentNode parent, String label, Icon icon, Icon alticon,
                 URL url, boolean expandable, String file)
      {
      this.label = label;
      this.icon = ((icon != null) ? icon : UNKNOWN_ICON);
      this.alticon = ((alticon != null) ? alticon : this.icon);
      this.url = url;
      this.expandable = expandable;
      this.file = file;
      }

    public DocumentNode getParent()
      {
      return(parent);
      }

    public String getFile()
      {
      return(file);
      }
    
    public boolean isExpandable()
      {
      return(expandable);
      }

    public String getLabel()
      {
      return(label);
      }

    public Icon getIcon()
      {
      return(icon);
      }

    public Icon getAltIcon()
      {
      return(alticon);
      }

    public URL getURL()
      {
      return(url);
      }
    }
  
  }

/* end of source file */