001package jmri.util.startup;
002
003import java.util.Locale;
004import javax.annotation.Nonnull;
005import jmri.spi.JmriServiceProviderInterface;
006
007/**
008 * Provide an SPI for registering potential startup actions with the
009 * {@link StartupActionsManager}.
010 * <p>
011 * Instances of this class need to be registered with a
012 * {@link java.util.ServiceLoader}. The best way to register is include a file
013 * {@code META-INF/services/jmri.util.startup.StartupActionFactory} in the
014 * classpath (preferably in a JAR with the action the instance supports). JMRI
015 * code uses the {@link org.openide.util.lookup.ServiceProvider} annotation to
016 * generate that file.
017 * <p>
018 * {@link AbstractStartupActionFactory} provides an abstract base class for
019 * creating factories that implements most of the boilerplate needed.
020 *
021 * @author Randall Wood Copyright 2016, 2020
022 */
023public interface StartupActionFactory extends JmriServiceProviderInterface {
024
025    /**
026     * Get the title for the given class using the default locale.
027     *
028     * @param clazz the class
029     * @return the title
030     * @throws IllegalArgumentException if the class is not supported by this
031     *                                  factory
032     */
033    @Nonnull
034    String getTitle(@Nonnull Class<?> clazz) throws IllegalArgumentException;
035
036    /**
037     * Get the title for the given class.
038     *
039     * @param clazz  the class
040     * @param locale the desired locale for the title
041     * @return the title in the given locale
042     * @throws IllegalArgumentException if the class is not supported by this
043     *                                  factory
044     */
045    @Nonnull
046    String getTitle(@Nonnull Class<?> clazz, @Nonnull Locale locale) throws IllegalArgumentException;
047
048    /**
049     * Get the classes this factory supports.
050     *
051     * @return the supported classes or an empty array
052     */
053    @Nonnull
054    Class<?>[] getActionClasses();
055
056    /**
057     * Get startup actions overridden by the given class. This is designed to
058     * allow a new class to replace a deprecated class.
059     * <p>
060     * <strong>Note:</strong> the behavior is undefined if multiple classes
061     * override a single class.
062     *
063     * @param clazz the overriding class
064     * @return the overridden classes or an empty array
065     * @throws IllegalArgumentException if the class is not supported by this
066     *                                  factory
067     */
068    @Nonnull
069    String[] getOverriddenClasses(@Nonnull Class<?> clazz) throws IllegalArgumentException;
070
071}