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