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 * <p> 023 * 024 * @author Bob Jacobsen Copyright (C) 2009 025 */ 026public interface SignalMastManager extends ProvidingManager<SignalMast> { 027 028 /** {@inheritDoc} */ 029 @Override 030 public void dispose(); 031 032 /** 033 * Get an existing SignalMast or return null if it doesn't exist. 034 * 035 * Locates via user name, then system name if needed. 036 * 037 * @param name User name or system name to match 038 * @return null if no match found 039 */ 040 @CheckForNull 041 public SignalMast getSignalMast(@Nonnull String name); 042 043 /** 044 * Get the SignalMast with the user name, then system name if needed; if that fails, create a 045 * new SignalMast. 046 * If the name is a valid system name, it will be used for the 047 * new SignalMast. 048 * 049 * @param name User name, system name, or address which can be promoted to 050 * system name 051 * @return never null 052 * @throws IllegalArgumentException if SignalMast doesn't already exist and 053 * the manager cannot create the SignalMast 054 * due to an illegal name or name that 055 * can't be parsed 056 */ 057 @Nonnull 058 public SignalMast provideSignalMast(@Nonnull String name) throws IllegalArgumentException; 059 060 /** 061 * Retrieve or create a new signal mast with a given system name. If a new object is created, 062 * it is also registered in this manager. 063 * 064 * @param systemName the system name by which to look up the mast, or to create anew. 065 * @param mastClass specific signal mast class. Must have a single-argument string 066 * constructor to crete it by system name. 067 * @return a registered signal mast (might be newly created), 068 * @throws JmriException if a signal mast with the given system name is already registered 069 * but it is not of the correct class, or an internal error happens during construction. 070 */ 071 @Nonnull 072 public SignalMast provideCustomSignalMast(@Nonnull String systemName, 073 Class<? extends SignalMast> mastClass) 074 throws JmriException; 075 076 @Nonnull 077 public SignalMast provideSignalMast(@Nonnull String prefix, // nominally IF$shsm 078 @Nonnull String signalSystem, 079 @Nonnull String mastName, 080 @Nonnull String[] heads) throws JmriException; 081 082 /** {@inheritDoc} */ 083 @CheckForNull 084 @Override 085 public SignalMast getByUserName(@Nonnull String s); 086 087 /** {@inheritDoc} */ 088 @CheckForNull 089 @Override 090 public SignalMast getBySystemName(@Nonnull String s); 091 092}