001package jmri;
002
003import javax.annotation.CheckForNull;
004import javax.annotation.Nonnull;
005
006/**
007 * Interface for obtaining information about signal groups.
008 * <p>
009 * Each NamedBean here represents a single signal group. The actual objects are
010 * SignalGroupTable objects; that's a current anachronism.
011 * <p>
012 * See the common implementation for information on how loaded, etc.
013 * <hr>
014 * This file is part of JMRI.
015 *
016 * @author Bob Jacobsen Copyright (C) 2009, 2018
017 */
018public interface SignalGroupManager extends Manager<SignalGroup> {
019
020    /**
021     * Locate via user name, then system name if needed.
022     * <p>
023     * Does not create a new one if nothing found
024     *
025     * @param name User Name or System Name to match
026     * @return null if no match found
027     */
028    @CheckForNull
029    public SignalGroup getSignalGroup(@Nonnull String name);
030
031    /** {@inheritDoc} */
032    @CheckForNull
033    @Override
034    public SignalGroup getBySystemName(@Nonnull String name);
035
036    /** {@inheritDoc} */
037    @CheckForNull
038    @Override
039    public SignalGroup getByUserName(@Nonnull String name);
040
041    /**
042     * Create a new Signal group if the group does not exist.
043     * <p>
044     * Intended for use with
045     * User GUI, to allow the auto generation of systemNames, where the user can
046     * optionally supply a username.
047     *
048     * @param userName User name for the new group
049     * @return a Signal Group with the same userName if already exists
050     * @throws IllegalArgumentException if there is trouble creating a new Group
051     */
052    @Nonnull
053    public SignalGroup newSignalGroupWithUserName(@Nonnull String userName) throws IllegalArgumentException;
054
055    /**
056     * Create a new SignalGroup if the group does not exist.
057     *
058     * @param systemName the system name for the group
059     * @param userName   the user name for the group
060     * @return a Signal Group with the same systemName or userName if
061     *         already exists or
062     * @throws IllegalArgumentException if there is trouble creating a new Group.
063     */
064    @Nonnull
065    public SignalGroup provideSignalGroup(@Nonnull String systemName, String userName) throws IllegalArgumentException;
066
067    /**
068     * Delete Group by removing it from the manager. The Group must first be
069     * deactivated so it stops processing.
070     *
071     * @param s the group to remove
072     */
073    void deleteSignalGroup(@Nonnull SignalGroup s);
074
075}