001package jmri;
002
003import java.util.ArrayList;
004
005/**
006 * Interface for a Consist Object, describing one or more
007 * cooperatively-operating locomotives.
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-2008
021 */
022public interface Consist {
023
024    // Constants for the ConsistType
025    // For Advanced Consists
026    int ADVANCED_CONSIST = 0;
027    // For Command Station Consists
028    // This is for a: Digitrax Universal Consist,
029    // or Lenz Double Header,or NCE "old Style Consist",etc
030    int CS_CONSIST = 1;
031    // Position Constants
032    // 0x00 represents the lead locomotive
033    // 0xFF represents the trailing (or rear) locomotive in the consist
034    // All other values in between are middle locomotives
035    int POSITION_LEAD = 0x00;
036    int POSITION_TRAIL = 0xFF;
037
038    /**
039     * A method for cleaning up the consist
040     */
041    void dispose();
042
043    /**
044     * Set the Consist Type.
045     *
046     * @param consistType the consist type
047     */
048    void setConsistType(int consistType);
049
050    /**
051     * Get the Consist Type.
052     *
053     * @return the consist type
054     */
055    int getConsistType();
056
057    /**
058     * Get the Consist Address
059     *
060     * @return the consist address
061     */
062    DccLocoAddress getConsistAddress();
063
064    /**
065     * Is the specific address allowed? (needed for system specific
066     * restrictions)
067     *
068     * @param address the address
069     * @return true if allowed; false otherwise
070     */
071    boolean isAddressAllowed(DccLocoAddress address);
072
073    /**
074     * Is there a size limit for this type of consist?
075     *
076     * @return -1 if no limit; 0 if the Consist Type is not supported; or the
077     *         total number of usable spaces if the consist has a limit (do not
078     *         subtract used spaces).
079     */
080    int sizeLimit();
081
082    /**
083     * Get a list of the locomotives in the consist.
084     *
085     * @return the list of addresses
086     */
087    ArrayList<DccLocoAddress> getConsistList();
088
089    /**
090     * Does the consist contain the specified locomotive address?
091     *
092     * @param address the address to check
093     * @return true if in consist; false otherwise
094     */
095    boolean contains(DccLocoAddress address);
096
097    /**
098     * Get the relative direction setting for a specific locomotive in the
099     * consist.
100     *
101     * @param address the address to check
102     * @return true if locomotive is in consist in its normal direction of
103     *         travel; false otherwise
104     */
105    boolean getLocoDirection(DccLocoAddress address);
106
107    /**
108     * Add a Locomotive to a Consist
109     *
110     * @param address         is the Locomotive address to add to the locomotive
111     * @param directionNormal is True if the locomotive is traveling the same
112     *                        direction as the consist, or false otherwise.
113     */
114    void add(DccLocoAddress address, boolean directionNormal);
115
116    /**
117     * Restore a Locomotive to a Consist, but don't write to the command
118     * station. This is used for restoring the consist from a file or adding a
119     * consist read from the command station.
120     *
121     * @param address         is the Locomotive address to add to the consist
122     * @param directionNormal is True if the locomotive is traveling the same
123     *                        direction as the consist, or false otherwise.
124     */
125    void restore(DccLocoAddress address, boolean directionNormal);
126
127    /**
128     * Remove a Locomotive from this Consist
129     *
130     * @param address is the Locomotive address to add to the locomotive
131     */
132    void remove(DccLocoAddress address);
133
134    /**
135     * Set the position of a locomotive within the consist
136     *
137     * @param address  is the Locomotive address
138     * @param position is a constant representing the position within the
139     *                 consist.
140     */
141    void setPosition(DccLocoAddress address, int position);
142
143    /**
144     * Get the position of a locomotive within the consist
145     *
146     * @param address is the Locomotive address of interest
147     * @return integer equal to jmri.Consist.POSITION_LEAD for the designated
148     *         lead locomotive. equal to jmri.Consist.POSITION_TRAIL for the
149     *         designated trailing locomotive. between 1 and 254 for other
150     *         locomotives in the consist
151     */
152    int getPosition(DccLocoAddress address);
153
154    /**
155     * Set the roster entry of a locomotive within the consist
156     *
157     * @param address  is the Locomotive address
158     * @param rosterId is the roster Identifier of the associated roster entry.
159     */
160    void setRosterId(DccLocoAddress address, String rosterId);
161
162    /**
163     * Get the rosterId of a locomotive within the consist
164     *
165     * @param address is the Locomotive address of interest
166     * @return string roster Identifier associated with the given address 
167     *         in the consist.  Returns null if no roster entry is associated
168     *         with this entry.
169     */
170    String getRosterId(DccLocoAddress address);
171
172    /**
173     * Add a listener for consist events
174     *
175     * @param listener is a consistListener object
176     */
177    void addConsistListener(jmri.ConsistListener listener);
178
179    /**
180     * Remove a listener for consist events
181     *
182     * @param listener is a consistListener object
183     */
184    void removeConsistListener(jmri.ConsistListener listener);
185
186    /**
187     * Set the text ID associated with the consist
188     *
189     * @param id is a string identifier for the consist
190     */
191    void setConsistID(String id);
192
193    /**
194     * Get the text ID associated with the consist
195     *
196     * @return String identifier for the consist default value is the string
197     *         Identifier for the consist address.
198     */
199    String getConsistID();
200
201    /**
202     * Reverse the order of the consist and the direction the locomotives are
203     * traveling
204     */
205    void reverse();
206
207    /**
208     * Restore the consist to the command station.
209     */
210    void restore();
211
212}