001package jmri.jmrit.logixng;
002
003import java.io.PrintWriter;
004import java.util.Locale;
005
006import jmri.Manager;
007
008/**
009 * Manager for GlobalVariable
010 *
011 * @author Dave Duchamp       Copyright (C) 2007
012 * @author Daniel Bergqvist   Copyright (C) 2022
013 */
014public interface GlobalVariableManager extends Manager<GlobalVariable> {
015
016    /**
017     * Create a new GlobalVariable if the GlobalVariable does not exist.
018     *
019     * @param systemName the system name
020     * @param userName   the user name
021     * @return a new GlobalVariable or null if unable to create
022     * @throws IllegalArgumentException when needed
023     */
024    GlobalVariable createGlobalVariable(String systemName, String userName)
025            throws IllegalArgumentException;
026
027    /**
028     * For use with User GUI, to allow the auto generation of systemNames, where
029     * the user can optionally supply a username.
030     *
031     * @param userName the user name
032     * @return a new GlobalVariable or null if unable to create
033     * @throws IllegalArgumentException when needed
034     */
035    GlobalVariable createGlobalVariable(String userName)
036            throws IllegalArgumentException;
037
038    /**
039     * Locate via user name, then system name if needed. Does not create a new
040     * one if nothing found
041     *
042     * @param name User name or system name to match
043     * @return null if no match found
044     */
045    GlobalVariable getGlobalVariable(String name);
046
047    /** {@inheritDoc} */
048    @Override
049    GlobalVariable getByUserName(String name);
050
051    /** {@inheritDoc} */
052    @Override
053    GlobalVariable getBySystemName(String name);
054
055    /**
056     * Create a new system name for a GlobalVariable.
057     * @return a new system name
058     */
059    String getAutoSystemName();
060
061    /**
062     * {@inheritDoc}
063     *
064     * The sub system prefix for the GlobalVariableManager is
065     * {@link #getSystemNamePrefix() } and "GV";
066     */
067    @Override
068    default String getSubSystemNamePrefix() {
069        return getSystemNamePrefix() + "GV";
070    }
071
072    /**
073     * Delete GlobalVariable by removing it from the manager. The GlobalVariable must first
074     * be deactivated so it stops processing.
075     *
076     * @param x the GlobalVariable to delete
077     */
078    void deleteGlobalVariable(GlobalVariable x);
079
080    /**
081     * Print the tree to a stream.
082     *
083     * @param locale The locale to be used
084     * @param writer the stream to print the tree to
085     * @param indent the indentation of each level
086     */
087    void printTree(Locale locale, PrintWriter writer, String indent);
088
089}