001package jmri; 002 003import javax.annotation.CheckForNull; 004import javax.annotation.Nonnull; 005 006/** 007 * Interface for obtaining signal masts. 008 * <p> 009 * This doesn't have a "new" method, as SignalMasts are separately implemented, 010 * instead of being system-specific. 011 * 012 * <hr> 013 * This file is part of JMRI. 014 * <p> 015 * JMRI is free software; you can redistribute it and/or modify it under the 016 * terms of version 2 of the GNU General Public License as published by the Free 017 * Software Foundation. See the "COPYING" file for a copy of this license. 018 * <p> 019 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 020 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 021 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 022 * 023 * @author Bob Jacobsen Copyright (C) 2009 024 */ 025public interface SignalMastManager extends ProvidingManager<SignalMast> { 026 027 /** {@inheritDoc} */ 028 @Override 029 void dispose(); 030 031 /** 032 * Get an existing SignalMast or return null if it doesn't exist. 033 * 034 * Locates via user name, then system name if needed. 035 * 036 * @param name User name or system name to match 037 * @return null if no match found 038 */ 039 @CheckForNull 040 SignalMast getSignalMast(@Nonnull String name); 041 042 /** 043 * Get the SignalMast with the user name, then system name if needed; if that fails, create a 044 * new SignalMast. 045 * If the name is a valid system name, it will be used for the 046 * new SignalMast. 047 * 048 * @param name User name, system name, or address which can be promoted to 049 * system name 050 * @return never null 051 * @throws IllegalArgumentException if SignalMast doesn't already exist and 052 * the manager cannot create the SignalMast 053 * due to an illegal name or name that 054 * can't be parsed 055 */ 056 @Nonnull 057 SignalMast provideSignalMast(@Nonnull String name) throws IllegalArgumentException; 058 059 /** 060 * Retrieve or create a new signal mast with a given system name. If a new object is created, 061 * it is also registered in this manager. 062 * 063 * @param systemName the system name by which to look up the mast, or to create anew. 064 * @param mastClass specific signal mast class. Must have a single-argument string 065 * constructor to crete it by system name. 066 * @return a registered signal mast (might be newly created), 067 * @throws JmriException if a signal mast with the given system name is already registered 068 * but it is not of the correct class, or an internal error happens during construction. 069 */ 070 @Nonnull 071 SignalMast provideCustomSignalMast(@Nonnull String systemName, 072 Class<? extends SignalMast> mastClass) 073 throws JmriException; 074 075 @Nonnull 076 SignalMast provideSignalMast(@Nonnull String prefix, // nominally IF$shsm 077 @Nonnull String signalSystem, 078 @Nonnull String mastName, 079 @Nonnull String[] heads) throws JmriException; 080 081 /** {@inheritDoc} */ 082 @CheckForNull 083 @Override 084 SignalMast getByUserName(@Nonnull String s); 085 086 /** {@inheritDoc} */ 087 @CheckForNull 088 @Override 089 SignalMast getBySystemName(@Nonnull String s); 090 091}