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