sanel commented on a change in pull request #2074: URL: https://github.com/apache/drill/pull/2074#discussion_r431070735
########## File path: common/src/main/java/org/apache/drill/extn/README.md ########## @@ -0,0 +1,125 @@ +# Drill Service Provider Interface (SPI) + +The Drill SPI allows extensions (AKA plugins, providers) to extend Drill. +This package provides the core extension mechanism and is a minor refinement +of the standard Java +[`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) +mechanism. + +## Layout + +A _service provider_ provides one or more _services_. The provider implements a +provider interface, defined in the Drill SPI package. That interface provides factory +methods to implement services. + +The provider developer creates a jar file with the properties described below. The jar +file is then placed in Drill's extension directory which is either: + +* `$DRILL_HOME/ext` if using the "classic" approach, or +* `$DRILL_SITE/ext` if usign a separate "site" directory. + +### Simple Jars + +The simplest service is one with no dependencies other than the JDK and Drill. +These reside in a single jar file placed in the `ext` directory. A UDF is a typical +example: + +``` +$DRILL_SITE +|- ext + |- coolUdfs.jar + |- fancyUdfs.jar +``` + +The name of the jar can be anything, though Drill recommends Maven-style naming: + +``` +collUdfs-1.3.0.jar +``` + +### Extension Packages + +More complex extensions (such as storage pugins) have dependencies in the form +of additional jars. In this case, the provider developer provides a directory +which contains any number of jars and other files: + +``` +$DRILL_SITE +|- ext + |- coolUdfs-1.3.0.jar + |- fancyUdfs-2.1.0.jar + |- megaDbPlugin-0.7.0 + |- metadbplugin-0.7.0.jar + |- dependency1.jar + |- dependency2.jar + |- README.md +``` + +The directory should also have Maven-format name, though this is not required. +The directory contains the provider jar which *must* have the same name as the +extension directory (this is how Drill knows which jar is the main one.) + +## Provider Configuration File + +Each extension jar must contain a _provider-configuration file_ as defined +by the Java `ServiceLoader`. The file has the name of the Drill-defined +provider interface, and contains a single line which is the fully-qualified +name of the provider class which implements the interface. + +``` +coolUdfs-1.3.0.jar +|- META-INF +| |- services +| | |- org.apache.drill.spi +|- com/foo/drill/udfs + |- SpiImpl.class + |- class files +``` + +The contents of `org.apache.drill.spi` would be: + +``` +com.foo.drill.uds.SpiImpl +``` + +### Drill Clusters + +The provider must be installed on each node in the Drill cluster. To avoid Review comment: Maybe add the case what will happen if provider is present on some nodes and on some not. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
