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}