001package jmri;
002
003import javax.annotation.CheckForNull;
004import javax.annotation.CheckReturnValue;
005import javax.annotation.Nonnull;
006
007/**
008 * Interface for obtaining signal heads.
009 * <p>
010 * This doesn't have a "new" method, as SignalHeads are separately implemented,
011 * instead of being system-specific.
012 *
013 * <hr>
014 * This file is part of JMRI.
015 * <p>
016 * JMRI is free software; you can redistribute it and/or modify it under the
017 * terms of version 2 of the GNU General Public License as published by the Free
018 * Software Foundation. See the "COPYING" file for a copy of this license.
019 * <p>
020 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
021 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
022 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
023 *
024 * @author Bob Jacobsen Copyright (C) 2001
025 */
026public interface SignalHeadManager extends Manager<SignalHead>, Disposable {
027
028    /** {@inheritDoc} */
029    @Override
030    void dispose();
031
032    /**
033     * Get an existing SignalHead 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    @CheckReturnValue
041    @CheckForNull
042    SignalHead getSignalHead(@Nonnull String name);
043
044    /**
045     * Get an existing SignalHead or return null if it doesn't exist. 
046     * 
047     * Locates via user name.
048     *
049     * @param name User name o to match
050     * @return null if no match found
051     */
052    @CheckReturnValue
053    @CheckForNull
054    @Override
055    SignalHead getByUserName(@Nonnull String name);
056
057    /**
058     * Get an existing SignalHead or return null if it doesn't exist. 
059     * 
060     * Locates via system name.
061     *
062     * @param name System name to match
063     * @return null if no match found
064     */
065    @CheckReturnValue
066    @CheckForNull
067    @Override
068    SignalHead getBySystemName(@Nonnull String name);
069
070}