{"type":"doc","content":[{"type":"paragraph","content":[{"text":"Beginning with enaio® 11.0, the extraction-service can be extended by plug-ins.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"92e431e8-a696-4655-80dc-58bdcc19e10f"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"9b50c739-12aa-4bbb-939a-f9f548c2c8ec"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Including an Existing Plug-in in the Extraction-Service","type":"text"}]},{"type":"paragraph","content":[{"text":"The deployment of an existing plug-in is explained by setting up an example plug-in for processing ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]},{"text":"PGN","type":"text","marks":[{"type":"link","attrs":{"href":"https://en.wikipedia.org/wiki/Portable_Game_Notation"}}]},{"text":" files.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuring the Extraction-Service","type":"text"}]},{"type":"paragraph","content":[{"text":"By default, the use of plug-ins is disabled. In the ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]},{"text":"extraction-prod.yml","type":"text","marks":[{"type":"code"}]},{"text":" file, these settings can be adjusted:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]}]},{"type":"paragraph","content":[{"text":"plugins:","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":" enabled: true","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":" directory: '../../data/plugins'","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"The jar file of the plug-in must then be stored in the specified directory.","type":"text"}]},{"type":"mediaGroup","content":[{"type":"media","attrs":{"id":"7929401c-e953-42ed-805d-d65fc371476d","collection":"contentId-21407833","type":"file"}}]},{"type":"paragraph","content":[{"text":"The extraction-service must be restarted to enable the plug-in.","type":"text"},{"type":"hardBreak"},{"text":"Any number of plug-in files can be stored in this directory.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Checking the Logging of the Plug-in","type":"text"}]},{"type":"paragraph","content":[{"text":"As soon as the extraction-service has been restarted, available plug-ins are detected. Information on these plug-ins can be found in the log.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the ","type":"text"},{"text":"plugins.enabled","type":"text","marks":[{"type":"code"}]},{"text":" switch is not set to ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":", the following will be protocolled in the log:","type":"text"}]},{"type":"paragraph","content":[{"text":"... c.o.s.e.routing.PluginProcessor : plugins not enabled","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"If the plug-ins are enabled, but not stored in the directory, the log will look as follows:","type":"text"}]},{"type":"paragraph","content":[{"text":"... c.o.s.e.routing.PluginProcessor : plugins enabled: ../../data/plugins\n... c.o.s.e.routing.PluginProcessor : plugins found: 0","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"If plug-ins are found, they will be listed with their names and ","type":"text"},{"text":"namespaces","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"paragraph","content":[{"text":"... c.o.s.e.routing.PluginProcessor : plugins enabled: ./../data/plugins\n... c.o.s.e.routing.PluginProcessor : plugins found: 2\n... c.o.s.e.routing.PluginProcessor : plugin 'PgnFile': PGNFILE\n... c.o.s.e.routing.PluginProcessor : plugin 'CAD-File': CAD","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"If plug-ins are active for a specific file, the number of each extracted plug-in will be in the log:","type":"text"}]},{"type":"paragraph","content":[{"text":"... c.o.s.e.routing.PluginProcessor : extracted by plugin 'PgnFile': 7","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Result of the Extraction","type":"text"}]},{"type":"paragraph"},{"type":"mediaGroup","content":[{"type":"media","attrs":{"id":"22a7e4f2-0f69-4399-9157-6f75a199d7c2","collection":"contentId-21407833","type":"file"}}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"The result of the extraction from this PGN file will look like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\"OS:FileName\": \"schach_PGN.pgn\",\n \"OS:FileSize\": \"740\",\n \"OS:ModifyDate\": \"2023-02-10T09:42:24+01:00\",\n \"OS:CreateDate\": \"2023-02-10T09:42:24+01:00\",\n \"OS:FileType\": \"TXT\",\n \"OS:MimeType\": \"text/plain\",\n \"ExifTool:ExifToolVersion\": \"12.52\",\n \"System:FileName\": \"schach_PGN.pgn\",\n \"System:Directory\": \"C:/Temp/Local/Temp/20230210.094224.115-1/389a8d00-25f8-4f84-9d08-238f0e81594c\",\n \"System:FileSize\": \"740\",\n \"System:FileModifyDate\": \"2023:02:10 09:42:24+01:00\",\n \"System:FileAccessDate\": \"2023:02:10 09:42:24+01:00\",\n \"System:FileCreateDate\": \"2023:02:10 09:42:24+01:00\",\n \"System:FilePermissions\": \"100666\",\n \"File:FileType\": \"TXT\",\n \"File:FileTypeExtension\": \"TXT\",\n \"File:MIMEType\": \"text/plain\",\n \"File:MIMEEncoding\": \"us-ascii\",\n \"File:Newlines\": \"\\n\",\n \"File:LineCount\": \"16\",\n \"File:WordCount\": \"158\",\n \"PGNFILE:Site\": \"Belgrade, Serbia JUG\",\n \"PGNFILE:White\": \"Fischer, Robert J.\",\n \"PGNFILE:Event\": \"F/S Return Match\",\n \"PGNFILE:Round\": \"29\",\n \"PGNFILE:Black\": \"Spassky, Boris V.\",\n \"PGNFILE:Date\": \"1992-11-04T12:00:00+01:00\",\n \"PGNFILE:Result\": \"1/2-1/2\",","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":" ","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]},{"text":"Creating a Plug-in","type":"text"}]},{"type":"paragraph","content":[{"text":"This section describes how to set up and configure a new plug-in including its deployment and check.","type":"text"}]},{"type":"paragraph","content":[{"text":"The plug-in capability of the extraction-service is based on the ","type":"text"},{"text":"PF4J","type":"text","marks":[{"type":"link","attrs":{"href":"https://pf4j.org/"}}]},{"text":" framework.","type":"text"},{"type":"hardBreak"},{"text":"The extraction-service loads plug-ins via ","type":"text"},{"text":"PF4J-Spring","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/pf4j/pf4j-spring"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The plug-in must comply with the interface defined by PF4J-Spring. In particular, this is a constructor with a ","type":"text"},{"text":"PluginWrapper","type":"text","marks":[{"type":"code"}]},{"text":" as a parameter:","type":"text"}]},{"type":"codeBlock","content":[{"text":"public PgnFilePlugin(PluginWrapper wrapper) {\n super(wrapper);\n }","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Including the Library for the Definition of the Plug-in Interface","type":"text"}]},{"type":"paragraph","content":[{"text":"OPTIMAL SYSTEMS provides a library for the defintion of the plug-in interface. The ","type":"text"},{"text":"extractionservice-plugin-interface.jar","type":"text","marks":[{"type":"code"}]},{"text":" file is available for download below and must be added to the project. It defines the interface for the extraction-service and also brings the plug-in capability of PF4J.","type":"text"}]},{"type":"mediaGroup","content":[{"type":"media","attrs":{"id":"0ab9e94c-918b-49ee-b0d9-5d7b12c4f67c","collection":"contentId-21407833","type":"file"}}]},{"type":"paragraph","content":[{"text":"It is important that the dependency of the plug-in to the interface library is defined as ","type":"text"},{"text":"provided ","type":"text","marks":[{"type":"code"}]},{"text":"(in gradle ","type":"text"},{"text":"compileOnly","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\tcom.os.enaio.services.extraction\n\textractionservice-plugin-interface\n\t9.0.2\n\tprovided\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Implementing the Plug-in","type":"text"}]},{"type":"paragraph","content":[{"text":"As an example of a plug-in, the ","type":"text"},{"text":"extractionservice-plugin-demo.jar","type":"text","marks":[{"type":"code"}]},{"text":" file is also available for download:","type":"text"}]},{"type":"paragraph","content":[{"text":"The following example operates on ","type":"text"},{"text":"PGN","type":"text","marks":[{"type":"link","attrs":{"href":"https://en.wikipedia.org/wiki/Portable_Game_Notation"}}]},{"text":" files.","type":"text"}]},{"type":"paragraph","content":[{"text":"Plug-in example code:","type":"text"}]},{"type":"codeBlock","content":[{"text":"package com.os.services.extraction.plugin.demo;\n\nimport com.os.services.extraction.plugin.ExtractionDriver;\nimport com.os.services.extraction.plugin.ExtractionInfo;\nimport org.apache.commons.io.IOUtils;\nimport org.pf4j.Extension;\nimport org.pf4j.Plugin;\nimport org.pf4j.PluginWrapper;\nimport org.slf4j.Logger;\nimport org.slf4j.LoggerFactory;\n\nimport java.io.File;\nimport java.io.FileInputStream;\nimport java.util.HashMap;\nimport java.util.Map;\n\npublic class PgnFilePlugin extends Plugin {\n\n /**\n * Constructor to be used by plugin manager for plugin instantiation.\n * Your plugins have to provide constructor with this exact signature to\n * be successfully loaded by manager.\n *\n * @param wrapper\n */\n public PgnFilePlugin(PluginWrapper wrapper) {\n super(wrapper);\n }\n private final static Logger LOGGER = LoggerFactory.getLogger(PgnFilePlugin.class);\n\n @Override\n public void start() {\n LOGGER.info(\"Start\");\n }\n\n @Override\n public void stop() {\n LOGGER.info(\"Stop\");\n }\n\n @Extension\n public static class PgnFileProcessor implements ExtractionDriver {\n private final static Logger LOGGER = LoggerFactory.getLogger(PgnFileProcessor.class);\n\n private static final String PREFIX = \"PGNFILE\";\n\n @Override\n public ExtractionInfo info() {\n return null;\n }\n\n @Override\n public String getExtractionDriverName() {\n return \"PgnFile\";\n }\n\n @Override\n public String getExtractionNamespace() {\n return PREFIX;\n }\n\n @Override\n public boolean isApplicable (File file) {\n\n if (file.getName().endsWith(\".pgn\")) {\n return true;\n }\n return false;\n }\n\n @Override\n public Map extractData( File file ) {\n\n Map result = new HashMap<>();\n try {\n String str = IOUtils.toString(new FileInputStream(file), \"UTF-8\");\n\n String[] tokens = str.split(\"]\");\n if (tokens != null) {\n for (String token : tokens) {\n token = token.trim();\n if (token.startsWith(\"[\")) {\n String[] tag = token.substring(1).split(\"\\\"\");\n if (tag.length >= 2) {\n //do not add prefix to key\n //it will be set by extractionservice\n String key = tag[0].trim();\n String value = tag[1].trim();\n\n if (key.endsWith(\"Date\")) {\n value = value.replaceAll(\"\\\\?{2}\", \"01\")\n .replaceAll(\"\\\\.\", \"\\\\-\") + \"T12:00:00+01:00\";\n }\n\n result.put(key, value);\n }\n if (tag.length == 1) {\n //do not add prefix to key\n //it will be set by extractionservice\n String key = tag[0].trim();\n\n result.put(key, \"\");\n }\n\n }\n }\n }\n } catch (Exception e) {\n LOGGER.error(e.getMessage());\n }\n\n return result;\n }\n\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Building the ","type":"text"},{"text":"jar","type":"text","marks":[{"type":"code"}]},{"text":" File","type":"text"}]},{"type":"paragraph","content":[{"text":"If the plug-in is packaged in a ","type":"text"},{"text":"jar ","type":"text","marks":[{"type":"code"}]},{"text":"file, there are important points to note:","type":"text"},{"type":"hardBreak"},{"text":"The following attributes must be specified in the ","type":"text"},{"text":"MANIFEST.MF","type":"text","marks":[{"type":"code"}]},{"text":" file (in the example plug-in):","type":"text"}]},{"type":"codeBlock","content":[{"text":"Plugin-Class: com.os.services.extraction.plugin.demo.PgnFilePlugin\n Plugin-Dependencies:\n Plugin-Id: PgnFileProcessor-Plugin\n Plugin-Provider: os\n Plugin-Version: 9.0.0","type":"text"}]},{"type":"paragraph","content":[{"text":"For these values to be automatically inserted into the ","type":"text"},{"text":"jar","type":"text","marks":[{"type":"code"}]},{"text":" file, the ","type":"text"},{"text":"maven-assembly-plugin","type":"text","marks":[{"type":"code"}]},{"text":" can be configured accordingly:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n org.apache.maven.plugins\n maven-assembly-plugin\n 3.1.0\n \n \n jar-with-dependencies\n \n ${project.artifactId}-${project.version}-all\n false\n false\n \n \n true\n true\n \n \n ${plugin.id}\n ${plugin.version}\n ${plugin.provider}\n ${plugin.class}\n ${plugin.dependencies}\n \n \n \n \n \n make-assembly\n package\n \n single\n \n \n \n ","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"jar","type":"text","marks":[{"type":"code"}]},{"text":" file must contain all required libraries (","type":"text"},{"text":"except","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"},{"text":"extractionservice-plugin-interfac","type":"text","marks":[{"type":"code"}]},{"text":"e and thus also pf4j).","type":"text"},{"type":"hardBreak"},{"text":"The ","type":"text"},{"text":"MANIFEST.MF","type":"text","marks":[{"type":"code"}]},{"text":" file must have the appropriate entries.","type":"text"},{"type":"hardBreak"},{"text":"The ","type":"text"},{"text":"extensions.idx","type":"text","marks":[{"type":"code"}]},{"text":" file must be included. It is automatically generated by PF4J during build.","type":"text"}]},{"type":"paragraph","content":[{"text":"This generated ","type":"text"},{"text":"jar","type":"text","marks":[{"type":"code"}]},{"text":" file can now be placed in the appropriately configured directory of the extraction-service.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Checking the Plug-in","type":"text"}]},{"type":"paragraph","content":[{"text":"To check the new plugin, the extraction-service must be configured as described in ","type":"text"},{"text":"Including an existing plugin in the extractionservice","type":"text","marks":[{"type":"em"},{"type":"link","attrs":{"href":"https://enaiodevelop.atlassian.net/wiki/spaces/EX/pages/edit-v2/21407833#Including-an-Existing-Plug-in-in-the-Extraction-Service"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"type":"hardBreak"}]},{"type":"paragraph"}],"version":1}

Browser not supported