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