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}