Class FWSimInterface<T>

java.lang.Object
net.simplace.sim.io.interfaces.FWSimInterface<T>
Type Parameters:
T - type of the access object returned by getInterface(FWSimVarMap, CONTENT_TYPE)
Direct Known Subclasses:
DatabaseInterface, FILEInterface, JSONInterface, MEMORYInterface

public abstract class FWSimInterface<T> extends Object
Base class of the interfaces (interface elements of the solution). An interface abstracts the access to a data medium and is used by resources (reading) and outputs (writing): getInterface(FWSimVarMap, CONTENT_TYPE) provides the access object (e.g. a database connection or a file pool); read(FWSimSession, String, Object, LinkedHashMap, FWSimInputAdapter, String, INTERFACE_TYPE) converts read data into a FWSimResourceCache. Files and connections are pooled.
Author:
Andreas Enders
  • Field Details

  • Constructor Details

    • FWSimInterface

      protected FWSimInterface(String aName, FWSimInterface.INTERFACE_TYPE aInterfaceType, org.jdom2.Element aInterfaceElement)
      Creates the interface from its element; to be called by the subclasses. The pool size is read from the child poolsize.
      Parameters:
      aName - name of the interface
      aInterfaceType - type of the interface
      aInterfaceElement - the interface element
    • FWSimInterface

      protected FWSimInterface(String aName, FWSimInterface.INTERFACE_TYPE aInterfaceType, int aPoolsize)
      Creates the interface without element; to be called by the subclasses.
      Parameters:
      aName - name of the interface
      aInterfaceType - type of the interface
      aPoolsize - number of pooled files or connections
  • Method Details

    • createInterface

      public static FWSimInterface<?> createInterface(org.jdom2.Element aInterfaceElement, FWSimSession aSession)
      Factory method: creates the interface of the type given in the attribute type. The ${...} parameters used in the children of the element are registered in the data frame of the session.
      Parameters:
      aInterfaceElement - the interface element
      aSession - the session, may be null
      Returns:
      the interface, or null if a custom interface cannot be created
    • createStatisticInterface

      public FWSimInterface<?> createStatisticInterface(String aStatisticPrefix)
      Creates an interface of the same type for writing the statistics of an output: the name gets the prefix, and for file interfaces also the file name (in the same directory). JSON interfaces are not supported (they are treated as custom interfaces).
      Parameters:
      aStatisticPrefix - prefix for name and file name, e.g. stat_
      Returns:
      the statistics interface
    • createInterface

      public static FWSimInterface<?> createInterface(String aName, FWSimInterface.INTERFACE_TYPE aInterfaceType, org.jdom2.Element aInterfaceElement)
      Factory method: creates the interface of the given type. For SHP the file name is changed to the .dbf file of the shape file, which is then read by a DBFInterface.
      Parameters:
      aName - name of the interface
      aInterfaceType - type of the interface
      aInterfaceElement - the interface element
      Returns:
      the interface, or null if a custom interface cannot be created
    • getInterface

      public abstract T getInterface(FWSimVarMap aVarMap, FWSimVariable.CONTENT_TYPE aContentType)
      Returns the access object of the interface, e.g. a database connection or a file pool.
      Parameters:
      aVarMap - variable map used for replacing tokens (e.g. in file names), may be null
      aContentType - res for reading, out for writing
      Returns:
      the access object
    • read

      public abstract FWSimResourceCache read(FWSimSession aFwSimSession, String aProjectID, Object aCache, LinkedHashMap<String,String> aKeyMap, FWSimInputAdapter aResourceAdapter, String aUniqueID, FWSimInterface.INTERFACE_TYPE aInterfaceType) throws MissingSimResourceException
      Converts read data into a resource cache: each data line is stored under the values of its key columns.
      Parameters:
      aFwSimSession - the session
      aProjectID - id of the current project
      aCache - the data read, in the format of the interface (e.g. String[][], result set, XML element)
      aKeyMap - key variables of the resource
      aResourceAdapter - the adapter the cache belongs to
      aUniqueID - unique id of the source data
      aInterfaceType - type of the source interface
      Returns:
      the new resource cache
      Throws:
      MissingSimResourceException - if the data cannot be converted
    • writeToDatabase

      protected void writeToDatabase(Object[] aValues, PreparedStatement aTargetStatement, boolean aAddIterationData) throws SQLException
      Writes a data line with a prepared insert statement into a database table (used for caching resources in the database). The values are set according to the data types of the columns; type errors are logged.
      Parameters:
      aValues - the values of the line
      aTargetStatement - the insert statement; nothing happens if null
      aAddIterationData - true to fill the first five columns with iteration 0, project id, simulation name, no simulation number and the generated simulation id
      Throws:
      SQLException - if the insert fails
    • transformArrays

      protected static Object[] transformArrays(List<Object[]> tArrays, FWSimVariable<?>[] aHeaderVariables)
      Combines several data lines (row mode) into one line: array columns collect the value of each line (element i from line i), other columns take the value of the first line.
      Parameters:
      tArrays - the data lines, each with one value per header variable
      aHeaderVariables - the header variables
      Returns:
      the combined line
    • readColArray

      protected static Object readColArray(String aProjectID, LinkedHashMap<String, FWSimVariable<?>> aHeaderVariables, MultiHashMap<Integer,Integer> aHeaderColModeMatch, List<?> aObjects, LinkedHashMap<String,String> aKeyMap, Object[] aArray)
      Converts the values of one data line into the data types of the header variables. In column mode an array variable is built from several columns (see checkHeaderForColMode(String[], LinkedHashMap)); its count is set to the number of columns. Number format errors are logged.
      Parameters:
      aProjectID - id of the current project (not used)
      aHeaderVariables - the header variables
      aHeaderColModeMatch - columns per header variable in column mode
      aObjects - the raw values of the line
      aKeyMap - key variables of the resource
      aArray - the array the converted values are written to (one per header variable)
      Returns:
      the key of the line: the value of the key column, or a list of values for several keys
    • readColArray

      protected static Object readColArray(String aProjectID, LinkedHashMap<String, FWSimVariable<?>> aHeaderVariables, MultiHashMap<Integer,Integer> aHeaderColModeMatch, List<?> aObjects, LinkedHashMap<String,String> aKeyMap, Object[] aArray, boolean aTypedCells)
      As readColArray(String, LinkedHashMap, MultiHashMap, List, LinkedHashMap, Object[]), optionally with cells that are already converted to the data type of their column (CSV table shared between resources, see CSVTable).
      Parameters:
      aProjectID - id of the current project (not used)
      aHeaderVariables - the header variables
      aHeaderColModeMatch - columns per header variable in column mode
      aObjects - the values of the line
      aKeyMap - key variables of the resource
      aArray - the array the converted values are written to (one per header variable)
      aTypedCells - true if cells that are neither null nor strings are already converted for the variable and are used as they are; false to convert every value via toString() (e.g. values from a database)
      Returns:
      the key of the line: the value of the key column, or a list of values for several keys
    • checkHeaderForColMode

      protected static MultiHashMap<Integer,Integer> checkHeaderForColMode(String[] aStrings, LinkedHashMap<String, FWSimVariable<?>> aHeaderVariables)
      Checks whether the file stores arrays in column mode, i.e. one column per array element named <name>_1, <name>_2, ... (or without underscore).
      Parameters:
      aStrings - the column names of the file
      aHeaderVariables - the header variables
      Returns:
      the column indices per header variable index, or null if the file has one column per variable or no array columns
    • getName

      public String getName()
      Returns:
      the name (id) of the interface
    • getPoolSize

      public int getPoolSize()
      Returns:
      the number of pooled files or connections
    • getInterfaceType

      public FWSimInterface.INTERFACE_TYPE getInterfaceType()
      Returns:
      the type of the interface
    • finalize

      public abstract void finalize() throws Exception
      Releases the resources of the interface (files, connections); to be implemented by the subclasses.
      Overrides:
      finalize in class Object
      Throws:
      Exception - if releasing fails
      See Also:
    • getInterfaceElement

      public org.jdom2.Element getInterfaceElement()
      Returns:
      the interface element of the solution (with the unresolved ${...} tokens), or null if the interface was created without element
    • toXML

      public org.jdom2.Element toXML()
      Creates the interface element with id, type and pool size; subclasses add their settings.
      Returns:
      the interface element
    • toString

      public String toString()
      Overrides:
      toString in class Object