001package jmri;
002
003import java.util.ArrayList;
004import java.util.HashMap;
005import java.util.List;
006
007/**
008 * Interface for obtaining Conditionals
009 * <p>
010 * This doesn't have a "new" method, since Conditionals are separately
011 * implemented, instead of being system-specific.
012 *
013 * <hr>
014 * This file is part of JMRI.
015 * <p>
016 * JMRI is free software; you can redistribute it and/or modify it under the
017 * terms of version 2 of the GNU General Public License as published by the Free
018 * Software Foundation. See the "COPYING" file for a copy of this license.
019 * <p>
020 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
021 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
022 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
023 *
024 * @author Dave Duchamp Copyright (C) 2007
025 */
026public interface ConditionalManager extends Manager<Conditional> {
027
028    // to free resources when no longer used
029    @Override
030    void dispose();
031
032    /**
033     * Method to create a new Conditional if the Conditional does not exist
034     * Returns null if a Conditional with the same systemName or userName
035     * already exists, or if there is trouble creating a new Conditional If the
036     * parent Logix cannot be found, the userName cannot be checked, but the
037     * Conditional is still created. The scenario can happen when a Logix is
038     * loaded from a file after its Conditionals.
039     *
040     * @param systemName the system name
041     * @param userName   the user name
042     * @return the new conditional or null if a Conditional already exists with
043     *         either name
044     */
045    Conditional createNewConditional(String systemName, String userName);
046
047    /**
048     * Parses the Conditional system name to get the parent Logix system name,
049     * then gets the parent Logix, and returns it.
050     *
051     * @param name system name of Conditional
052     * @return the logix for the conditional
053     */
054    Logix getParentLogix(String name);
055
056    /**
057     * Method to get an existing Conditional. First looks up assuming that name
058     * is a User Name. Note: the parent Logix must be passed in x for user name
059     * lookup. If this fails, or if x == null, looks up assuming that name is a
060     * System Name. If both fail, returns null.
061     *
062     * @param x   parent Logix (may be null)
063     * @param name name to look up
064     * @return null if no match found
065     */
066    Conditional getConditional(Logix x, String name);
067
068    Conditional getConditional(String name);
069
070    @Override
071    Conditional getByUserName(String s);
072
073    Conditional getByUserName(Logix x, String s);
074
075    @Override
076    Conditional getBySystemName(String s);
077
078    /**
079     * Get a list of all Conditional system names with the specified Logix
080     * parent.
081     *
082     * @param x the logix
083     * @return a list of Conditional system names
084     */
085    List<String> getSystemNameListForLogix(Logix x);
086
087    /**
088     * Delete Conditional by removing it from the manager. The parent Logix must
089     * first be deactivated so it stops processing.
090     *
091     * @param c the conditional to remove
092     */
093    void deleteConditional(Conditional c);
094
095    /**
096     * Return a copy of the entire map.  Used by
097     * {@link jmri.jmrit.beantable.LogixTableAction#buildWhereUsedListing}
098     * @return a copy of the map
099     * @since 4.7.4
100     */
101    HashMap<String, ArrayList<String>> getWhereUsedMap();
102
103    /**
104     * Add a conditional reference to the array indicated by the target system name.
105     * @since 4.7.4
106     * @param target The system name for the target conditional
107     * @param reference The system name of the conditional that contains the conditional reference
108     */
109    void addWhereUsed(String target, String reference);
110
111    /**
112     * Get a list of conditional references for the indicated conditional
113     * @since 4.7.4
114     * @param target The target conditional for a conditional reference
115     * @return an ArrayList or null if none
116     */
117    ArrayList<String> getWhereUsed(String target);
118
119    /**
120     * Remove a conditional reference from the array indicated by the target system name.
121     * @since 4.7.4
122     * @param target The system name for the target conditional
123     * @param reference The system name of the conditional that contains the conditional reference
124     */
125    void removeWhereUsed(String target, String reference);
126
127    /**
128     * Display the complete structure, used for debugging purposes.
129     * @since 4.7.4
130     */
131    void displayWhereUsed();
132
133    /**
134     * Get the target system names used by this conditional
135     * @since 4.7.4
136     * @param reference The system name of the conditional the refers to other conditionals.
137     * @return a list of the target conditionals
138     */
139    ArrayList<String> getTargetList(String reference);
140
141}