001package jmri.jmrit.logixng;
002
003import java.io.*;
004import java.util.Locale;
005
006import javax.annotation.CheckForNull;
007import javax.annotation.Nonnull;
008
009import jmri.*;
010
011/**
012 * A manager for a NamedTable
013 * 
014 * @author Dave Duchamp       Copyright (C) 2007
015 * @author Daniel Bergqvist   Copyright (C) 2018
016 */
017public interface NamedTableManager extends Manager<NamedTable> {
018
019    /**
020     * Create a new anonymous table.
021     * This table is not stored in the manager.
022     * @param numRows number of rows in the table
023     * @param numColumns number of columns in the table
024     * @return the new table
025     */
026    AnonymousTable newAnonymousTable(int numRows, int numColumns);
027    
028    /**
029     * Create a new CSV table.
030     * This table is stored in the manager but it's contents does only exists
031     * in the CSV file. If the CSV file is changed, the contents will be read
032     * on the next start of the program.
033     * @param systemName the system name of the table
034     * @param userName the user name of the table, or null if no user name
035     * @param fileName the file name of the CSV file
036     * @return the new table
037     */
038    NamedTable newCSVTable(String systemName, String userName, String fileName);
039
040
041    NamedTable newCSVTable(String systemName, String userName, String fileName, Table.CsvType csvType);
042
043
044    /**
045     * Create a new internal named table.
046     * This table is stored in the manager together with its contents. Note
047     * that a big table will take a lot of space in the panel file since the
048     * storage of table data has a lot of overhead. For larger tables, a CSV
049     * table is recommended.
050     * @param systemName the system name of the table
051     * @param userName the user name of the table, or null if no user name
052     * @param numRows number of rows in the table
053     * @param numColumns number of columns in the table
054     * @return the new table
055     */
056    NamedTable newInternalTable(String systemName, String userName, int numRows, int numColumns);
057    
058    /**
059     * Load a table from a CSV text.
060     * @param sys the system name of the new table
061     * @param user the user name of the new table or null if no user name
062     * @param text the CSV text
063     * @return the loaded table
064     * @throws java.io.IOException in case of an exception
065     */
066    NamedTable loadTableFromCSVData(
067            @Nonnull String sys, @CheckForNull String user, @Nonnull String text)
068            throws IOException;
069    
070    /**
071     * Load a table from a CSV finle.
072     * @param sys the system name of the new table
073     * @param user the user name of the new table or null if no user name
074     * @param fileName the file name of the CSV table
075     * @return the loaded table
076     * @throws java.io.IOException in case of an exception
077     */
078    NamedTable loadTableFromCSV(
079            @Nonnull String sys, @CheckForNull String user,
080            @Nonnull String fileName)
081            throws IOException;
082    
083    /**
084     * Load a table from a CSV finle.
085     * @param file the CSV file
086     * @param sys the system name of the new table
087     * @param user the user name of the new table or null if no user name
088     * @return the loaded table
089     * @throws java.io.IOException in case of an exception
090     */
091    NamedTable loadTableFromCSV(
092            @Nonnull String sys, @CheckForNull String user,
093            @Nonnull File file)
094            throws IOException;
095    
096    /**
097     * Locate via user name, then system name if needed. Does not create a new
098     * one if nothing found
099     *
100     * @param name User name or system name to match
101     * @return null if no match found
102     */
103    NamedTable getNamedTable(String name);
104    
105    /** {@inheritDoc} */
106    @Override
107    NamedTable getByUserName(String name);
108    
109    /** {@inheritDoc} */
110    @Override
111    NamedTable getBySystemName(String name);
112    
113    /**
114     * Create a new system name for a LogixNG.
115     * @return a new system name
116     */
117    String getAutoSystemName();
118    
119    /**
120     * {@inheritDoc}
121     * 
122     * The sub system prefix for the NamedTableManager is
123     * {@link #getSystemNamePrefix() } and "T";
124     */
125    @Override
126    default String getSubSystemNamePrefix() {
127        return getSystemNamePrefix() + "T";
128    }
129    
130    /**
131     * Delete NamedTable by removing it from the manager.
132     *
133     * @param x the NamedTable to delete
134     */
135    void deleteNamedTable(NamedTable x);
136
137    /**
138     * Print the tree to a stream.
139     * 
140     * @param writer the stream to print the tree to
141     * @param indent the indentation of each level
142     */
143    void printTree(PrintWriter writer, String indent);
144    
145    /**
146     * Print the tree to a stream.
147     * 
148     * @param locale The locale to be used
149     * @param writer the stream to print the tree to
150     * @param indent the indentation of each level
151     */
152    void printTree(Locale locale, PrintWriter writer, String indent);
153
154}