001package jmri; 002 003import javax.annotation.CheckForNull; 004import javax.annotation.Nonnull; 005 006/** 007 * Interface for obtaining StringIOs. 008 * 009 * @author Daniel Bergqvist Copyright (C) 2020 010 */ 011public interface StringIOManager extends ProvidingManager<StringIO>, NameIncrementingManager { 012 013 @Override 014 @Nonnull 015 StringIO provide(@Nonnull String name) throws IllegalArgumentException; 016 017 @Nonnull 018 StringIO provideStringIO(@Nonnull String name) throws IllegalArgumentException; 019 020 /** 021 * Get an existing StringIO or return null if it doesn't exist. 022 * 023 * Locates via user name, then system name if needed. 024 * 025 * @param name User name or system name to match 026 * @return null if no match found 027 */ 028 @CheckForNull 029 StringIO getStringIO(@Nonnull String name); 030 031 /** 032 * Return a StringIO with the specified user or system name. 033 * Return StringIO by UserName else provide by SystemName. 034 * <p> 035 * Note that 036 * two calls with the same arguments will get the same instance; there is 037 * only one StringIO object with a specific system or user name. 038 * <p> 039 * This will always return a valid object reference; a new object will be 040 * created if necessary. If that's not possible, an IllegalArgumentException 041 * is thrown. 042 * <p> 043 * If a new object has to be created: 044 * <ul> 045 * <li>If a null reference is given for user name, no user name will be 046 * associated with the Sensor object created; a valid system name must be 047 * provided 048 * <li>If both names are provided, the system name defines the hardware 049 * access of the desired sensor, and the user address is associated with it. 050 * The system name must be valid. 051 * </ul> 052 * Note that it is possible to make an inconsistent request if both 053 * addresses are provided, but the given values are associated with 054 * different objects. This is a problem, and we don't have a good solution 055 * except to issue warnings. This will mostly happen if you're creating 056 * StringIOs when you should be looking them up. 057 * 058 * @param systemName the desired system name 059 * @param userName the desired user name 060 * @return requested StringIO object 061 * @throws IllegalArgumentException if cannot create the StringIO due to e.g. 062 * an illegal name or name that can't be 063 * parsed. 064 */ 065 @Nonnull 066 StringIO newStringIO(@Nonnull String systemName, @CheckForNull String userName) throws IllegalArgumentException; 067 068}