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