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}