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}