001package jmri;
002
003import java.util.Vector;
004
005/**
006 * Access to signal appearance information.
007 * <p>
008 * Maps to an appearance file in a signal system.
009 *
010 * This interface does not provide any methods to change the map.
011 *
012 * @author Bob Jacobsen Copyright (C) 2010
013 */
014public interface SignalAppearanceMap {
015
016    /**
017     * Check if an aspect can be displayed.
018     *
019     * @param aspect the aspect to check
020     * @return true if the aspect can be displayed; false otherwise
021     */
022    boolean checkAspect(String aspect);
023
024    /**
025     * Get all available aspect names.
026     *
027     * @return an enumeration of available aspects
028     */
029    java.util.Enumeration<String> getAspects();
030
031    /**
032     * Get the associated signal system and the common information it contains.
033     *
034     * @return the signal system
035     */
036    SignalSystem getSignalSystem();
037
038    /**
039     * Get a property associated with a specific aspect
040     *
041     * @param aspect the aspect containing the property
042     * @param key    the property key
043     * @return the property value or null if none is defined for key
044     */
045    String getProperty(String aspect, String key);
046
047    /**
048     * Get an Image Link associated with a specific aspect and type
049     *
050     * @param aspect the aspect
051     * @param key    the image link key
052     * @return the image link or an empty String if none is defined
053     */
054    String getImageLink(String aspect, String key);
055
056    /**
057     * Get a list of valid icon sets.
058     *
059     * @param aspect the aspect to get icon sets for
060     * @return a list of sets or an empty list if none are defined
061     */
062    Vector<String> getImageTypes(String aspect);
063
064    /**
065     * Return the aspect for a specific appearance.
066     *
067     * @param appearance the appearance
068     * @return the aspect
069     */
070    String getSpecificAppearance(int appearance);
071
072    /**
073     * Constant representing the "held" aspect for a signal
074     */
075    final static int HELD = 0;
076
077    /**
078     * Constant representing the "permissive" aspect for a signal
079     */
080    final static int PERMISSIVE = 1;
081
082    /**
083     * Constant representing the "danger" aspect for a signal
084     */
085    final static int DANGER = 2;
086
087    /**
088     * Constant representing the "dark" aspect for a signal
089     */
090    final static int DARK = 3;
091
092    /**
093     * Get a list of potential aspects that we could set the SignalMast to,
094     * given the state of the advanced signal mast.
095     *
096     * @param advancedAspect the aspect
097     * @return a string array of potential aspects or null if none defined
098     */
099    String[] getValidAspectsForAdvancedAspect(String advancedAspect);
100
101    /**
102     * Provide a multi-line summary of the signal system content,
103     * typically for printing. 
104     * <p>
105     * Not intended for further parsing, 
106     * i.e. for persistence, as format likely to differ from type 
107     * to type, and to change often.
108     * @return summary string.
109     */
110    String summary();
111
112}