001package jmri;
002
003import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
004import javax.annotation.Nonnull;
005
006/**
007 * Locate a CatalogTree object representing some specific information.
008 * <p>
009 * CatalogTree objects are obtained from a CatalogTreeManager, which in turn is
010 * generally located from the InstanceManager.
011 * <p>
012 * Much of the book-keeping is implemented in the AbstractCatalogTreeManager
013 * class, which can form the basis for a system-specific implementation.
014 *
015 * <hr>
016 * This file is part of JMRI.
017 * <p>
018 * JMRI is free software; you can redistribute it and/or modify it under the
019 * terms of version 2 of the GNU General Public License as published by the Free
020 * Software Foundation. See the "COPYING" file for a copy of this license.
021 * <p>
022 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
023 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
024 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
025 *
026 * @author Pete Cressman Copyright (C) 2009
027 *
028 */
029public interface CatalogTreeManager extends Manager<CatalogTree> {
030
031    /**
032     * Locate via user name, then system name if needed. If that fails, return
033     * null
034     *
035     * @param name CatalogTree object to locate
036     * @return null if no match found
037     */
038    public CatalogTree getCatalogTree(@Nonnull String name);
039
040    /**
041     * Locate an instance based on a system name. Returns null if no instance
042     * already exists.
043     *
044     * @param systemName CatalogTree object to locate
045     * @return requested CatalogTree object or null if none exists
046     */
047    @Override
048    public CatalogTree getBySystemName(@Nonnull String systemName);
049
050    /**
051     * Locate an instance based on a user name. Returns null if no instance
052     * already exists.
053     *
054     * @param userName CatalogTree object to locate
055     * @return requested CatalogTree object or null if none exists
056     */
057    @Override
058    public CatalogTree getByUserName(@Nonnull String userName);
059
060    /**
061     * Get a CatalogTree instance with the specified system and user names.
062     * Note that two calls with the same arguments will get the same instance;
063     * there is only one CatalogTree object representing a given physical
064     * CatalogTree and therefore only one with a specific system or user name.
065     * <p>
066     * This will always return a valid object reference; a new object will be
067     * created if necessary. In that case:
068     * <ul>
069     * <li>If a null reference is given for user name, no user name will be
070     * associated with the CatalogTree object created; a valid system name must
071     * be provided
072     * <li>If both names are provided, the system name defines the hardware
073     * access of the desired CatalogTree, and the user address is associated
074     * with it. The system name must be valid.
075     * </ul>
076     * Note that it is possible to make an inconsistent request if both
077     * addresses are provided, but the given values are associated with
078     * different objects. This is a problem, and we don't have a good solution
079     * except to issue warnings. This will mostly happen if you're creating
080     * CatalogTree objects when you should be looking them up.
081     *
082     * @param systemName system name for new CatalogTree
083     * @param userName   user name for new CatalogTree
084     * @return requested CatalogTree object (never null)
085     */
086    public CatalogTree newCatalogTree(@Nonnull String systemName, String userName);
087
088    public void storeImageIndex();
089
090    public void loadImageIndex();
091
092    public boolean isIndexChanged();
093
094    public boolean isIndexLoaded();
095
096    public void indexChanged(boolean changed);
097
098    @SuppressFBWarnings(value = "MS_MUTABLE_ARRAY",
099            justification = "with existing code structure, just have to accept these exposed arrays. Someday...")
100    static final String[] IMAGE_FILTER = {"gif", "jpg", "jpeg", "png"};
101
102    @SuppressFBWarnings(value = "MS_OOI_PKGPROTECT",
103            justification = "with existing code structure, just have to accept these exposed arrays. Someday...")
104    static final String[] SOUND_FILTER = {"wav"};
105
106    @SuppressFBWarnings(value = "MS_OOI_PKGPROTECT",
107            justification = "with existing code structure, just have to accept these exposed arrays. Someday...")
108    static final String[] SCRIPT_FILTER = {"py", "scpt"};
109
110}