001package jmri;
002
003import javax.swing.tree.TreeModel;
004
005/**
006 * Represents a CatalogTree, a tree displaying a taxonomy - e.g. a file system
007 * directory, or an index of references or a table of contents built according
008 * to the user's taxonomy.
009 * <p>
010 * Specific implementations are in the jmri.jmrit.catalog package.
011 * <p>
012 * The states and names are Java Bean parameters, so that listeners can be
013 * registered to be notified of any changes.
014 * <p>
015 * Each CatalogTree object has a two names. The "user" name is entirely free
016 * form, and can be used for any purpose. The "system" name is provided by the
017 * purpose-specific implementations.
018 * <br>
019 * <hr>
020 * This file is part of JMRI.
021 * <p>
022 * JMRI is free software; you can redistribute it and/or modify it under the
023 * terms of version 2 of the GNU General Public License as published by the Free
024 * Software Foundation. See the "COPYING" file for a copy of this license.
025 * <p>
026 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
027 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
028 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
029 *
030 * @author Pete Cressman Copyright (C) 2009
031 */
032public interface CatalogTree extends NamedBean, TreeModel {
033
034    char IMAGE = 'I';    // letter to filter for images/icons
035    char SOUND = 'S';    // letter to filter for sounds
036    char SCRIPT = 'T';    // letter to filter for scripts
037    char NOFILTER = 'N';    // letter for unfiltered
038    char FILESYS = 'F';    // typeLetter for tree based on file system
039    char XML = 'X';    // typeLetter for index tree stored in XML file
040
041    /**
042     * Recursively add a representation of the resources below a particular
043     * resource
044     *
045     * @param pName   Name of the resource to be scanned; this is only used for
046     *                the human-readable tree
047     * @param pPath   Path to this resource, including the pName part
048     * @param pParent Node for the parent of the resource to be scanned, e.g.
049     *                where in the tree to insert it.
050     */
051    void insertNodes(String pName, String pPath, CatalogTreeNode pParent);
052
053    /**
054     * Starting point to recursively add nodes to the tree by scanning a file
055     * directory
056     *
057     * @param pathToRoot Path to Directory to be scanned
058     */
059    void insertNodes(String pathToRoot);
060
061    /**
062     * Get the root element of the tree as a jmri.CatalogTreeNode object.
063     * (Instead of Object, as parent swing.TreeModel provides)
064     */
065    @Override
066    CatalogTreeNode getRoot();
067}