001package jmri;
002
003import java.util.Set;
004import javax.annotation.Nonnull;
005
006/**
007 * Interface providing initialization of specific objects by default. This is
008 * used to move references to specific subtypes out of the jmri package and into
009 * more specialized packages.
010 * <p>
011 * Note that this is only needed when the object can't be created with a
012 * no-arguments constructor. In that case, the
013 * {@link InstanceManagerAutoDefault} mechanism is a better choice.
014 * <p>
015 * Instances of this class will normally be used only if they are annotated with
016 * {@code @ServiceProvider(service = InstanceInitializer.class)}
017 * <p>
018 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
019 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
020 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
021 *
022 * @author Bob Jacobsen Copyright (C) 2010
023 * @since 2.9.4
024 */
025public interface InstanceInitializer {
026
027    /**
028     * Provide a default instance of the given class.
029     * <p>
030     * <strong>Note</strong> calling this method twice for the same class should
031     * not be expected to return the same instance; however, there is no
032     * guarantee that the same instance will not be returned for two calls to
033     * this method.
034     *
035     * @param <T>  the class to get the default for
036     * @param type the class to get the default for
037     * @return the newly created default for the given class
038     * @throws IllegalArgumentException if creating an instance of type is not
039     *                                  supported by this InstanceInitalizer
040     */
041    @Nonnull
042    public <T> Object getDefault(@Nonnull Class<T> type);
043
044    /**
045     * Get the set of classes for which this InstanceInitializer can provide
046     * default instances for.
047     *
048     * @return the set of classes this InstanceInitalizer supports; if empty,
049     *         {@link #getDefault(java.lang.Class)} will never be called.
050     */
051    @Nonnull
052    public Set<Class<?>> getInitalizes();
053}