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     * Method to get an existing Conditional. First looks up assuming that name
061     * is a User Name. Note: the parent Logix must be passed in x for user name
062     * lookup. If this fails, or if x == null, looks up assuming that name is a
063     * System Name. If both fail, returns null.
064     *
065     * @param x   parent Logix (may be null)
066     * @param name name to look up
067     * @return null if no match found
068     */
069    @CheckForNull
070    Conditional getConditional(Logix x, String name);
071
072    @CheckForNull
073    Conditional getConditional(String name);
074
075    @Override
076    @CheckForNull
077    Conditional getByUserName(String s);
078
079    Conditional getByUserName(Logix x, String s);
080
081    @Override
082    Conditional getBySystemName(String s);
083
084    /**
085     * Get a list of all Conditional system names with the specified Logix
086     * parent.
087     *
088     * @param x the logix
089     * @return a list of Conditional system names
090     */
091    List<String> getSystemNameListForLogix(Logix x);
092
093    /**
094     * Delete Conditional by removing it from the manager. The parent Logix must
095     * first be deactivated so it stops processing.
096     *
097     * @param c the conditional to remove
098     */
099    void deleteConditional(Conditional c);
100
101    /**
102     * Return a copy of the entire map.  Used by
103     * {@link jmri.jmrit.beantable.LogixTableAction#buildWhereUsedListing}
104     * @return a copy of the map
105     * @since 4.7.4
106     */
107    HashMap<String, ArrayList<String>> getWhereUsedMap();
108
109    /**
110     * Add a conditional reference to the array indicated by the target system name.
111     * @since 4.7.4
112     * @param target The system name for the target conditional
113     * @param reference The system name of the conditional that contains the conditional reference
114     */
115    void addWhereUsed(@CheckForNull String target, @CheckForNull String reference);
116
117    /**
118     * Get a list of conditional references for the indicated conditional
119     * @since 4.7.4
120     * @param target The target conditional for a conditional reference
121     * @return an ArrayList or null if none
122     */
123    ArrayList<String> getWhereUsed(String target);
124
125    /**
126     * Remove a conditional reference from the array indicated by the target system name.
127     * @since 4.7.4
128     * @param target The system name for the target conditional
129     * @param reference The system name of the conditional that contains the conditional reference
130     */
131    void removeWhereUsed(String target, String reference);
132
133    /**
134     * Display the complete structure, used for debugging purposes.
135     * @since 4.7.4
136     */
137    void displayWhereUsed();
138
139    /**
140     * Get the target system names used by this conditional
141     * @since 4.7.4
142     * @param reference The system name of the conditional the refers to other conditionals.
143     * @return a list of the target conditionals
144     */
145    ArrayList<String> getTargetList(String reference);
146
147}