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