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}