X-Git-Url: https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=blobdiff_plain;f=docs%2FDeveloper%2FUtilities%2FGenericFileImport.md;fp=docs%2FDeveloper%2FUtilities%2FGenericFileImport.md;h=87faea7514ccab8858fde1e113738da72938d0f9;hp=0000000000000000000000000000000000000000;hb=a9ec58f08ccc02e65b1cab6aedff25e0cf3c6444;hpb=5998374f7e179cfaf451c220216adc18c823047f

diff --git a/docs/Developer/Utilities/GenericFileImport.md b/docs/Developer/Utilities/GenericFileImport.md
new file mode 100644
index 000000000..87faea751
--- /dev/null
+++ b/docs/Developer/Utilities/GenericFileImport.md
@@ -0,0 +1,89 @@
+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:
+
+1. Call directly in Java `FileImportDropins.watchDropinsFolder()`
+2. Use SCL function `watchDropinsFolder` from `"Dropins/Core"`
+
+## Creating own File importer
+
+To create own File importer it is usually enough to extend the abstract class `SimanticsResourceFileImport` and implement the two methods:
+
+    /**
+     * Returns a key-value map for file extensions this importer can handle
+     *
+     * @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
+     */
+    Map<String, String> allowedExtensionsWithFilters();
+
+    /*
+     * Performs the import for the given file
+     *
+     * @param parent Resource parent of the imported entity in Simantics database
+     * @param file Path file location of file
+     * @return Optional Resource of the imported entity in Simantics database
+     * @throws Exception
+     */
+    public abstract Optional<Resource> perform(Resource parent, Path file) throws Exception;
+
+An example of such a class for importing FMU-files to Simantics workbench would be following:
+
+~~~
+public class FMIFileImport extends SimanticsResourceFileImport {
+
+    private static final Map<String, String> EXTENSIONS_FILTERS = Collections.singletonMap("*.fmu",
+            "Functional Mock-up Unit (*.fmu)");
+
+    @Override
+    public Optional<Resource> perform(Resource parent, Path file) throws IOException{
+        try {
+            Resource model = FMIStudioSCL.createFMIModel(parent, file);
+            return Optional.of(model);
+        } catch (FMILException | DatabaseException e) {
+            e.printStackTrace();
+            return Optional.empty();
+        }
+    }
+
+    @Override
+    public Map<String, String> allowedExtensionsWithFilters() {
+        return EXTENSIONS_FILTERS;
+    }
+
+}
+~~~
+
+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.
+
+Give the name for the XML file and and browse to the implementing class You just created.
+
+An example of XML-file is:
+
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="org.simantics.fmi.studio.fileimport">
+   <implementation class="org.simantics.fmi.studio.fileimport.FMIFileImport"/>
+   <service>
+      <provide interface="org.simantics.fileimport.IGenericFileImport"/>
+   </service>
+</scr:component>
+</pre>
+
+## FileImportService utility class
+
+The class `org.simantics.fileimport.FileImportService` contains utility methods for e.g. listing all current services and performing file imports:
+
+~~~
+    /**
+     * Lists all supported file extensions which have a registered service for handling the import
+     *
+     * @return Map containing the extension and the description of the extension in that order
+     */
+    public static Map<String, String> supportedExtensionsWithFilters();
+
+    /**
+     * 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
+     *
+     * @param file Path file to be imported
+     * @param callback Optional callback which can be used to catch Throwables thrown in the import process
+     */
+    public static void performFileImport(Path file, Optional<Consumer<Throwable>> callback);
+~~~