001package jmri;
002
003import java.util.ArrayList;
004
005/**
006 * Interface for Consist Manager objects, which provide access to the existing
007 * Consists and allows for creation and destruction.
008 *
009 * <hr>
010 * This file is part of JMRI.
011 * <p>
012 * JMRI is free software; you can redistribute it and/or modify it under the
013 * terms of version 2 of the GNU General Public License as published by the Free
014 * Software Foundation. See the "COPYING" file for a copy of this license.
015 * <p>
016 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
017 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
018 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
019 *
020 * @author Paul Bender Copyright (C) 2003
021 */
022public interface ConsistManager {
023
024    /**
025     * Find a Consist with this consist address, and return it. If the Consist
026     * doesn't exist, create it.
027     *
028     * @param address the consist address
029     * @return an existing or new consist
030     */
031    Consist getConsist(LocoAddress address);
032
033    /**
034     * Remove an old Consist.
035     *
036     * @param address the consist address
037     */
038    void delConsist(LocoAddress address);
039
040    /**
041     * Does this implementation support Command Station Consists?
042     *
043     * @return true if command station consists are supported; false otherwise
044     */
045    boolean isCommandStationConsistPossible();
046
047    /**
048     * Does a command station consist require a separate consist address from
049     * locomotives in consist?
050     *
051     * @return true is command station consist requires separate address; false
052     *         otherwise
053     */
054    boolean csConsistNeedsSeperateAddress();
055
056    /**
057     * Get a list of known consist addresses.
058     *
059     * @return list of addresses
060     */
061    ArrayList<LocoAddress> getConsistList();
062
063    /**
064     * Translate Error Codes relieved by a consistListener into Strings
065     *
066     * @param errorCode the code
067     * @return the description
068     */
069    String decodeErrorCode(int errorCode);
070
071    /**
072     * Request an update from the layout, loading Consists from the command
073     * station.
074     */
075    void requestUpdateFromLayout();
076
077    /**
078     * Does this ConsistManager allow advanced consisting?
079     * @return true if this manager's protocols support DCC advanced consisting
080     */
081     default boolean isAdvancedConsistPossible() {
082        return true;
083     }
084     
085    /**
086     * Does this ConsistManager require that all locomotives in a consist
087     * use the same protocol?
088     * @return true if this manager requires that all locomotives in a consist 
089     *              use the same protocol
090     */
091     default boolean isSingleFormConsistRequired() {
092        return false;
093     }
094     
095    /**
096     * Register a ConsistListListener object with this ConsistManager
097     *
098     * @param listener a Consist List Listener object.
099     */
100    void addConsistListListener(ConsistListListener listener);
101
102    /**
103     * Remove a ConsistListListener object with this ConsistManager
104     *
105     * @param listener a Consist List Listener object.
106     */
107    void removeConsistListListener(ConsistListListener listener);
108
109    /**
110     * Notify the registered ConsistListListener objects that the ConsistList
111     * has changed.
112     */
113    void notifyConsistListChanged();
114
115    /**
116     * Can this consist manager be disabled?
117     * @return true if the manager can be disabled, false otherwise
118     */
119    default boolean canBeDisabled() {
120        return false;
121    }
122
123    /**
124     * Register a listener that is called if this manager is enabled or disabled.
125     * @param listener the listener
126     */
127    default void registerEnableListener(EnableListener listener) {
128        // Do nothing
129    }
130
131    /**
132     * Unregister a listener that is called if this manager is enabled or disabled.
133     * @param listener the listener
134     */
135    default void unregisterEnableListener(EnableListener listener) {
136        // Do nothing
137    }
138    
139    /**
140     * Check if this manager is enabled
141     * @return true if enabled
142     */
143    default boolean isEnabled() {
144        return true;
145    }
146
147    /**
148     * A listener that listens to whether the manager is enabled or disabled.
149     */
150    interface EnableListener {
151
152        void setEnabled(boolean value);
153    }
154
155}