001package jmri; 002 003import javax.annotation.CheckForNull; 004import javax.annotation.Nonnull; 005 006/** 007 * Locate a Reporter object representing some specific device on the layout. 008 * <p> 009 * Reporter objects are obtained from a ReporterManager, which in turn is 010 * generally located from the InstanceManager. A typical call sequence might be: 011 * <pre> 012 * Reporter device = InstanceManager.getDefault(jmri.ReporterManager.class).newReporter("23",null); 013 * </pre> 014 * <p> 015 * Each Reporter has a two names. The "user" name is entirely free form, and can 016 * be used for any purpose. The "system" name is provided by the system-specific 017 * implementations, and provides a unique mapping to the layout control system 018 * (for example LocoNet or NCE) and address within that system. 019 * <p> 020 * Much of the book-keeping is implemented in the AbstractReporterManager class, 021 * which can form the basis for a system-specific implementation. 022 * 023 * <hr> 024 * This file is part of JMRI. 025 * <p> 026 * JMRI is free software; you can redistribute it and/or modify it under the 027 * terms of version 2 of the GNU General Public License as published by the Free 028 * Software Foundation. See the "COPYING" file for a copy of this license. 029 * <p> 030 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 031 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 032 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 033 * 034 * @author Bob Jacobsen Copyright (C) 2001 035 * @see jmri.Reporter 036 * @see jmri.InstanceManager 037 */ 038public interface ReporterManager extends ProvidingManager<Reporter>, NameIncrementingManager { 039 040 /** 041 * Locate via user name, then system name if needed. If that fails, create a 042 * new Reporter. If the name is a valid system name, it will be used for the 043 * new Reporter. Otherwise, the makeSystemName method will attempt to turn 044 * it into a valid system name. 045 * <p>This provides the same function as {@link ProvidingManager#provide} 046 * which has a more generic form. 047 * 048 * @param name User name, system name, or address which can be promoted to 049 * system name 050 * @return Never null 051 * @throws IllegalArgumentException if Reporter doesn't already exist and 052 * the manager cannot create the Reporter 053 * due to an illegal name or name that 054 * can't be parsed. 055 */ 056 @Nonnull 057 Reporter provideReporter(@Nonnull String name) throws IllegalArgumentException; 058 059 /** {@inheritDoc} */ 060 @Override 061 @Nonnull 062 default Reporter provide(@Nonnull String name) throws IllegalArgumentException { return provideReporter(name); } 063 064 /** 065 * Locate via user name, then system name if needed. If that fails, return 066 * null 067 * 068 * @param name User name or system name to match 069 * @return null if no match found 070 */ 071 @CheckForNull 072 Reporter getReporter(@Nonnull String name); 073 074 /** 075 * Locate an instance based on a system name. Returns null if no instance 076 * already exists. 077 * 078 * @param systemName the system name to locate 079 * @return requested Reporter object or null if none exists 080 */ 081 @CheckForNull 082 @Override 083 Reporter getBySystemName(@Nonnull String systemName); 084 085 /** 086 * Locate an instance based on a user name. Returns null if no instance 087 * already exists. 088 * 089 * @param userName the user name to locate 090 * @return requested Reporter object or null if none exists 091 */ 092 @CheckForNull 093 @Override 094 Reporter getByUserName(@Nonnull String userName); 095 096 /** 097 * Locate an instance based on a user name, or if that fails, by system 098 * name. Returns null if no instance already exists. 099 * 100 * @param userName the name to locate 101 * @return requested Reporter object or null if none exists 102 */ 103 @CheckForNull 104 Reporter getByDisplayName(@Nonnull String userName); 105 106 /** 107 * Return an instance with the specified system and user names. 108 * <p> 109 * Note that 110 * two calls with the same arguments will get the same instance; there is 111 * only one Reporter object representing a given physical Reporter and 112 * therefore only one with a specific system or user name. 113 * <p> 114 * This will always return a valid object reference; a new object will be 115 * created if necessary. In that case: 116 * <ul> 117 * <li>If a null reference is given for user name, no user name will be 118 * associated with the Reporter object created; a valid system name must be 119 * provided 120 * <li>If both names are provided, the system name defines the hardware 121 * access of the desired Reporter, and the user address is associated with 122 * it. The system name must be valid. 123 * </ul> 124 * Note that it is possible to make an inconsistent request if both 125 * addresses are provided, but the given values are associated with 126 * different objects. This is a problem, and we don't have a good solution 127 * except to issue warnings. This will mostly happen if you're creating 128 * Reporters when you should be looking them up. 129 * 130 * @param systemName the system name 131 * @param userName the user name 132 * @return requested Reporter object (never null) 133 * @throws IllegalArgumentException if cannot create the Reporter due to 134 * an illegal name or name that can't 135 * be parsed. 136 */ 137 @Nonnull 138 Reporter newReporter(@Nonnull String systemName, String userName) throws IllegalArgumentException; 139 140 /** 141 * Get a system name for a given hardware address and system prefix. 142 * 143 * @param curAddress desired hardware address 144 * @param prefix system prefix used in system name, excluding Bean type-letter.. 145 * @return the complete Reporter system name for the prefix and current 146 * address 147 * @throws jmri.JmriException if unable to create a system name for the 148 * given address, possibly due to invalid address 149 * format 150 */ 151 @Nonnull 152 String createSystemName(@Nonnull String curAddress, @Nonnull String prefix) throws JmriException; 153 154 /** 155 * {@inheritDoc} 156 */ 157 @Override 158 String getEntryToolTip(); 159 160}