001package jmri;
002
003import java.util.ArrayList;
004
005import javax.annotation.CheckForNull;
006import javax.annotation.Nonnull;
007
008/**
009 * Implementation of a Transit Manager
010 * <p>
011 * This doesn't need an interface, since Transits are globaly implemented,
012 * instead of being system-specific.
013 * <p>
014 * Note that Transit system names must begin with system prefix and type character,
015 * usually IZ, and be followed by a string, usually, but not always, a number. This
016 * is enforced when a Transit is created.
017 * <br>
018 * <hr>
019 * This file is part of JMRI.
020 * <p>
021 * JMRI is free software; you can redistribute it and/or modify it under the
022 * terms of version 2 of the GNU General Public License as published by the Free
023 * Software Foundation. See the "COPYING" file for a copy of this license.
024 * <p>
025 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
026 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
027 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
028 *
029 * @author Dave Duchamp Copyright (C) 2008, 2011
030 */
031public interface TransitManager extends Manager<Transit> {
032
033    /**
034     * Create a new Transit if the Transit does not exist.
035     * This is NOT a provide method.
036     *
037     * @param systemName the desired system name
038     * @param userName   the desired user name
039     * @return a new Transit
040     * @throws NamedBean.BadNameException if a Transit with the same systemName or
041     *         userName already exists, or if there is trouble creating a new
042     *         Transit.
043     */
044    @Nonnull
045    Transit createNewTransit(@CheckForNull String systemName, String userName) throws NamedBean.BadNameException;
046
047    /**
048     * For use with User GUI, to allow the auto generation of systemNames, where
049     * the user can optionally supply a username.
050     * <p>
051     * Note: Since system names should be kept short for use in Dispatcher,
052     * automatically generated system names are in the form {@code IZnn}, where
053     * {@code nn} is the first available number.
054     *
055     * @param userName the desired user name
056     * @return a new Transit
057     * @throws NamedBean.BadNameException if userName is already associated with
058     *         another Transit
059     */
060    @Nonnull
061    Transit createNewTransit(String userName) throws NamedBean.BadNameException;
062
063    /**
064     * Get an existing Transit.
065     * First looks up assuming that name is a User
066     * Name. If this fails looks up assuming that name is a System Name.
067     * If both fail, returns null.
068     *
069     * @param name User name or system name to match
070     * @return null if no match found
071     */
072    @CheckForNull
073    Transit getTransit(String name);
074
075    /**
076     * Remove an existing Transit.
077     *
078     * @param z the transit to remove
079     */
080    void deleteTransit(Transit z);
081
082    /**
083     * Get a list of Transits which use a specified Section.
084     *
085     * @param s the section to check Transits against
086     * @return a list, possibly empty, of Transits using section s.
087     */
088    @Nonnull
089    ArrayList<Transit> getListUsingSection(Section s);
090
091    @Nonnull
092    ArrayList<Transit> getListUsingBlock(Block b);
093
094    @Nonnull
095    ArrayList<Transit> getListEntryBlock(Block b);
096
097}