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}