Module omix.api
Package omix.plugin.io

Interface ModelIOHandlerInterface

All Known Implementing Classes:
AbstractModelIODomHandler, AbstractModelIOHandler, StandardModelIODomHandler
public interface ModelIOHandlerInterface
This interface allows to realize a network import and export plugin.
Implementing classes must register a set of supported file name suffixes (like "xml", "fml", "doc"). Additionally, a description must be delivered for each file suffix.
A file format can be supported only for file read or file write operations or both. Depending of read or write support the specific file format appears in "open"/"import" file dialogs and/or in "export" file dialogs.
When a file of supported format is selected inside a file dialog, the method readThumbnail(URLConnection) is called for reading a thumbnail of the file (if available).
If a file is finally selected the method supports(URLConnection, String, IOFlag) must accept the file format once again before the file is finally loaded in #read(String, URLConnection, ModelFactory, InputUtilities) or written in write(String, URLConnection, Model, OutputUtilities).
Since:
Omix 1.3
Author:
Dr. Peter Droste, Omix Visualization

  • Method Summary

    Modifier and Type Method Description
    default boolean canImport​(String suffix)
    Determines if IO handler can import files of a specific format into current document.
    default boolean canOpen​(String suffix)
    Determines if IO handler can open files of a specific format as new document.
    boolean canRead​(String suffix)
    Determines if IO handler can read files of a specific format.
    boolean canWrite​(String suffix)
    Determines if IO handler can write files of a specific format.
    String getDescription​(String suffix)
    Returns a textual description of the file format displayed in the file dialogs.
    Example:
    String[] getSuffixes()
    Returns an array of all supported file suffixes.
    void read​(String suffix, URLConnection connection, Model model, InputUtilities utilities)
    Reading network content from file.
    byte[] readThumbnail​(URLConnection connection)
    This method is called when the user selects a file in the file dialog in order to get a thumbnail picture.
    boolean supports​(URLConnection connection, String fileName, IOFlag flag)
    Determines if the IO handler supports opening the specific file.
    The flag specifies if the file shall be read or written.
    void write​(String suffix, URLConnection connection, Model model, OutputUtilities utilities)
    Writing a network to file.

  • Method Details

    • getSuffixes

      String[] getSuffixes()
      Returns an array of all supported file suffixes. Example: new String[]{"xml", "fml", "doc"}
      Returns:
      all supported suffixes

    • getDescription

      String getDescription​(String suffix)
      Returns a textual description of the file format displayed in the file dialogs.
      Example:

      public String getDescription(String suffix){
          if("fml".equals(suffix)){
              return tr("13CFlux 2.0 Network");
          }
          else return null;
      }

      FileDialog

      Parameters:
      suffix - file format suffix
      Returns:
      description

    • canRead

      boolean canRead​(String suffix)
      Determines if IO handler can read files of a specific format.
      Parameters:
      suffix - file format suffix
      Returns:
      can read

    • canWrite

      boolean canWrite​(String suffix)
      Determines if IO handler can write files of a specific format.
      Parameters:
      suffix - file format suffix
      Returns:
      can write

    • canImport

      default boolean canImport​(String suffix)
      Determines if IO handler can import files of a specific format into current document.
      Parameters:
      suffix - file format suffix
      Returns:
      can read

    • canOpen

      default boolean canOpen​(String suffix)
      Determines if IO handler can open files of a specific format as new document.
      Parameters:
      suffix - file format suffix
      Returns:
      can read

    • readThumbnail

      byte[] readThumbnail​(URLConnection connection) throws IOException
      This method is called when the user selects a file in the file dialog in order to get a thumbnail picture. The file dialog requires a byte[] array of a valid "png" or "xpm" picture in order to show a thumbnail.
      Providing a thumbnail picture is optional. This method is not called for remote connections.
      Parameters:
      connection - an URL connection which allows to get an inputstream of the file data (URLConnection.getInputStream()). The file path can be detected by URLConnection.getURL().
      Returns:
      a byte array of a valid "png" or "xpm" picture or null
      Throws:
      IOException - when an error occurs.

    • supports

      boolean supports​(URLConnection connection, String fileName, IOFlag flag)
      Determines if the IO handler supports opening the specific file.
      The flag specifies if the file shall be read or written. Usually, the fileName allows to decide if the format is supported:

      if(fileName.endsWith("pzr")) return true;

      In some cases (for example XML files) the file content is additionally important. Therefore, the connection parameter allows to open and analyzing the file by URLConnection.getInputStream().
      Example for an XML file:

      public boolean supports(URLConnection connection, String fileName, IOFlag flag){
          if(flag==IOFlag.read){
              try{
                 // checking if root element of XML file has is "sbml".
                 DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
                 Document doc = builder.parse(connection.getInputStream());
                 Element rootElement = doc.getDocumentElement();
                 return rootElement.getNodeName().equals("sbml");
              }catch(Exception e){}
          }
          return false;
      }

      Parameters:
      connection - helps to open the file (URLConnection.getInputStream()).
      fileName - the name of the file
      flag - kind of operation (read or write)
      Returns:
      support of given file

    • write

      void write​(String suffix, URLConnection connection, Model model, OutputUtilities utilities) throws IOException
      Writing a network to file.
      Parameters:
      suffix - the file suffix (identifier of the valid file filter).
      connection - helps to write the file (URLConnection.getOutputStream()).
      model - the network model
      utilities - utilities for file writing and reading network contents
      Throws:
      IOException

    • read

      void read​(String suffix, URLConnection connection, Model model, InputUtilities utilities) throws IOException
      Reading network content from file.
      Parameters:
      suffix - the file suffix (identifier of the valid file filter).
      connection - helps to open the file (URLConnection.getInputStream()).
      model - a writable model to create and interconnect network components.
      utilities - utilities for file reading and creating a network
      Throws:
      IOException