docs/Developer/Utilities/GenericFileImport.md

   1 Simantics Generic File Import is a utility service that enables [Eclipse's Dropins](http://help.eclipse.org/mars/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fp2_dropins_format.html)-like functionality. The directory resides inside `~/workspace/.metadata/plugins/org.simantics.fileimport/dropins` and it is not watched by default. There are two ways to start the watchservice:\r
   2 \r
   3 1. Call directly in Java `FileImportDropins.watchDropinsFolder()`\r
   4 2. Use SCL function `watchDropinsFolder` from `"Dropins/Core"`\r
   5 \r
   6 ## Creating own File importer\r
   7 \r
   8 To create own File importer it is usually enough to extend the abstract class `SimanticsResourceFileImport` and implement the two methods:\r
   9 \r
  10     /**\r
  11      * Returns a key-value map for file extensions this importer can handle\r
  12      *\r
  13      * @return Map<String, String> allowed extensions this service can handle. Key is the extension e.g. <code>.sharedLibrary</code> and the value is the description of the extension\r
  14      */\r
  15     Map<String, String> allowedExtensionsWithFilters();\r
  16 \r
  17     /*\r
  18      * Performs the import for the given file\r
  19      *\r
  20      * @param parent Resource parent of the imported entity in Simantics database\r
  21      * @param file Path file location of file\r
  22      * @return Optional Resource of the imported entity in Simantics database\r
  23      * @throws Exception\r
  24      */\r
  25     public abstract Optional<Resource> perform(Resource parent, Path file) throws Exception;\r
  26 \r
  27 An example of such a class for importing FMU-files to Simantics workbench would be following:\r
  28 \r
  29 ~~~\r
  30 public class FMIFileImport extends SimanticsResourceFileImport {\r
  31 \r
  32     private static final Map<String, String> EXTENSIONS_FILTERS = Collections.singletonMap("*.fmu",\r
  33             "Functional Mock-up Unit (*.fmu)");\r
  34 \r
  35     @Override\r
  36     public Optional<Resource> perform(Resource parent, Path file) throws IOException{\r
  37         try {\r
  38             Resource model = FMIStudioSCL.createFMIModel(parent, file);\r
  39             return Optional.of(model);\r
  40         } catch (FMILException | DatabaseException e) {\r
  41             e.printStackTrace();\r
  42             return Optional.empty();\r
  43         }\r
  44     }\r
  45 \r
  46     @Override\r
  47     public Map<String, String> allowedExtensionsWithFilters() {\r
  48         return EXTENSIONS_FILTERS;\r
  49     }\r
  50 \r
  51 }\r
  52 ~~~\r
  53 \r
  54 It is important to create the component for defining declarative service. To do this right click the same plugin where the implmentation is and click New -> Other -> Plug-in Development -> Component Definition.\r
  55 \r
  56 Give the name for the XML file and and browse to the implementing class You just created.\r
  57 \r
  58 An example of XML-file is:\r
  59 \r
  60 <pre>\r
  61 <?xml version="1.0" encoding="UTF-8"?>\r
  62 <scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="org.simantics.fmi.studio.fileimport">\r
  63    <implementation class="org.simantics.fmi.studio.fileimport.FMIFileImport"/>\r
  64    <service>\r
  65       <provide interface="org.simantics.fileimport.IGenericFileImport"/>\r
  66    </service>\r
  67 </scr:component>\r
  68 </pre>\r
  69 \r
  70 ## FileImportService utility class\r
  71 \r
  72 The class `org.simantics.fileimport.FileImportService` contains utility methods for e.g. listing all current services and performing file imports:\r
  73 \r
  74 ~~~\r
  75     /**\r
  76      * Lists all supported file extensions which have a registered service for handling the import\r
  77      *\r
  78      * @return Map containing the extension and the description of the extension in that order\r
  79      */\r
  80     public static Map<String, String> supportedExtensionsWithFilters();\r
  81 \r
  82     /**\r
  83      * Method that performs the import of the given file. This method is called when e.g. {@link FileImportDropins} watcher detects {@link java.nio.file.StandardWatchEventKinds.ENTRY_CREATE} operation\r
  84      *\r
  85      * @param file Path file to be imported\r
  86      * @param callback Optional callback which can be used to catch Throwables thrown in the import process\r
  87      */\r
  88     public static void performFileImport(Path file, Optional<Consumer<Throwable>> callback);\r
  89 ~~~\r