001package jmri;
002
003import javax.annotation.Nonnull;
004
005/**
006 * Extends the {@link Manager} class to handle "provide" methods that
007 * can create a {@link NamedBean} on request from just its system name.
008 *
009 *
010 * @param <E> the type of NamedBean supported by this manager
011 * @author Bob Jacobsen Copyright (C) 2003
012 */
013public interface ProvidingManager<E extends NamedBean> extends Manager<E> {
014
015    /**
016     * Get an existing instance via user name, then system name; if no matching instance is found, create a
017     * new NameBean from the system name.
018     * <p>
019     * If the name is a valid system name, it will be used for the
020     * new NamedBean. Otherwise, the {@link Manager#makeSystemName} method will attempt to turn it
021     * into a valid system name which the manager will attempt to use. If that fails,
022     * an exception is thrown.
023     * <p>
024     * This is similar to the specific methods found in certain
025     * type-specific managers:
026     * {@link TurnoutManager#provideTurnout},
027     * {@link SensorManager#provideSensor},
028     * et al.  Those might be more mnemonic; this one is more generic.  Neither
029     * is preferred nor deprecated; use your choice.
030     *
031     * @param name User name, system name, or address which can be promoted to
032     *             system name
033     * @return Never null
034     * @throws IllegalArgumentException if NamedBean doesn't already exist and the
035     *                                  manager cannot create it due to
036     *                                  an illegal name or name that can't
037     *                                  be parsed.
038     */
039    @Nonnull
040    E provide(@Nonnull String name) throws IllegalArgumentException;
041
042}