001package jmri;
002
003import javax.annotation.CheckForNull;
004import javax.annotation.Nonnull;
005
006/**
007 * Basic Implementation of a SectionManager.
008 * <p>
009 * This doesn't have a "new" interface, since Sections are independently
010 * implemented, instead of being system-specific.
011 * <p>
012 * Note that Section system names must begin with system prefix and type character,
013 * usually IY, and be followed by a string, usually, but not always, a number. This
014 * is enforced when a Section is created.
015 * <br>
016 * <hr>
017 * This file is part of JMRI.
018 * <p>
019 * JMRI is free software; you can redistribute it and/or modify it under the
020 * terms of version 2 of the GNU General Public License as published by the Free
021 * Software Foundation. See the "COPYING" file for a copy of this license.
022 * <p>
023 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
024 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
025 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
026 *
027 * @author Dave Duchamp Copyright (C) 2008
028 */
029public interface SectionManager extends Manager<Section> {
030
031    // void addListeners();
032
033    /**
034     * Create a new Section if the Section does not exist.
035     *
036     * @param systemName the desired system name
037     * @param userName   the desired user name
038     * @return a new Section or
039     * @throws IllegalArgumentException if a Section with the same systemName or
040     *         userName already exists, or if there is trouble creating a new
041     *         Section.
042     */
043    @Nonnull
044    Section createNewSection(@Nonnull String systemName, String userName) throws IllegalArgumentException;
045
046    /**
047     * Create a New Section with Auto System Name.
048     * @param userName UserName for new Section
049     * @return new Section with Auto System Name.
050     * @throws IllegalArgumentException if existing Section, or
051     *          unable to create a new Section.
052     */
053    @Nonnull
054    Section createNewSection(String userName) throws IllegalArgumentException;
055
056    /**
057     * Remove an existing Section.
058     *
059     * @param y the section to remove
060     */
061    void deleteSection(Section y);
062
063    /**
064     * Get an existing Section. First look up assuming that name is a User
065     * Name. If this fails look up assuming that name is a System Name.
066     *
067     * @param name the name to find; user names are searched for a match first,
068     *             followed by system names
069     * @return the found section of null if no matching Section found
070     */
071    @CheckForNull
072    Section getSection(String name);
073
074    /**
075     * Validate all Sections.
076     *
077     * @return number or validation errors; -2 is returned if there are no sections
078     */
079    int validateAllSections();
080
081    /**
082     * Check direction sensors in SSL for signals.
083     *
084     * @return the number or errors; 0 if no errors; -1 if the panel is null; -2 if there are no sections
085     */
086    int setupDirectionSensors();
087
088    /**
089     * Remove direction sensors from SSL for all signals.
090     *
091     * @return the number or errors; 0 if no errors; -1 if the panel is null; -2 if there are no sections
092     */
093    int removeDirectionSensorsFromSSL();
094
095    /**
096     * Initialize all blocking sensors that exist - set them to 'ACTIVE'.
097     */
098    void initializeBlockingSensors();
099
100    /**
101     * Generate Block Sections in stubs/sidings. Called after generating signal logic.
102     */
103    void generateBlockSections();
104
105}