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}