[
https://issues.apache.org/jira/browse/METRON-777?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16117964#comment-16117964
]
ASF GitHub Bot commented on METRON-777:
---------------------------------------
Github user mattf-horton commented on a diff in the pull request:
https://github.com/apache/metron/pull/530#discussion_r131765763
--- Diff: bundles-lib/README.md ---
@@ -0,0 +1,79 @@
+# Apache Metron Bundles
+
+Apache Metron Bundles and this documentation are a derivitave of the
[Apache Nifi](http://www.nifi.apache.org)
[NARs](http://nifi.apache.org/developer-guide.html).
+
+When software from many different organizations is all hosted within
+the same environment, Java ClassLoaders quickly
+become a concern. If multiple components have a dependency on the same
+library but each depends on a different
+version, many problems arise, typically resulting in unexpected
+behavior or `NoClassDefFoundError` errors occurring.
+In order to prevent these issues from becoming problematic, Apache NiFi
+introduces the notion of a NiFi Archive, or NAR. The Apache Metron
project has adapted and extended the NAR system as
+Apache Metron Bundles.
+
+A BUNDLE allows several components and their dependencies to be packaged
+together into a single package.
+The BUNDLE package is then provided ClassLoader isolation from other
BUNDLES
+packages. Developers should always deploy their Apache Metron Extensions
as BUNDLE packages.
+
+To achieve this, a developer creates a new Maven Artifact, which we
+refer to as the BUNDLE artifact. The packaging is
+set to `bundle`. The `dependencies` section of the POM is then created so
+that the BUNDLE has a dependency on all Extension Components that are to
be included within the BUNDLE.
+
+In order to use a packaging of `bundle`, we must use the
`bundles-maven-plugin` module.
+This is included by adding the following snippet to the bundle's pom.xml:
+
+
+```xml
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.metron</groupId>
+ <artifactId>bundles-maven-plugin</artifactId>
+ <version>0.4.0</version>
+ <extensions>true</extensions>
+ </plugin>
+ </plugins>
+</build>
+```
+
+The bundles-maven-plugin is included in the projects created by Apache
Metron Extension maven archetypes.
+
+
+The BUNDLE is able to have one dependency that is of type `bundle`. If more
+than one dependency is specified that is of type
+`bundle`, then the bundles-maven-plugin will error. If BUNDLE A adds a
+dependency on BUNDLE B, this will *not* result in
+BUNDLE B packaging all of the components of BUNDLE A. Rather, this will add
+a `Bundle-Dependency-Id` element to the `MANIFEST.MF`
+file of BUNDLE A. This will result in setting the ClassLoader of BUNDLE B
as
+the Parent ClassLoader of BUNDLE A. In this case,
+we refer to BUNDLE B as the _Parent_ of BUNDLE A.
+
+## Per-Instance ClassLoading
+
+The bundles-lib provides the `@RequiresInstanceClassLoading` annotation to
further expand and isolate the libraries
+available on a component’s classpath. You can annotate a extension class
with `@RequiresInstanceClassLoading`
+to indicate that the instance ClassLoader for the component requires a
copy of all the resources in the
+component's BUNDLE ClassLoader. When `@RequiresInstanceClassLoading` is
not present, the
+instance ClassLoader simply has it's parent ClassLoader set to the BUNDLE
ClassLoader, rather than
+copying resources.
+
+Because @RequiresInstanceClassLoading copies resources from the BUNDLE
ClassLoader for each instance of the
+extension, use this capability judiciously in an environment where many
extensions may be present. If ten instances of one extension are created, all
classes
+from the component's BUNDLE ClassLoader are loaded into memory ten times.
This could eventually increase the
+memory footprint significantly when enough instances of the component are
created.
+
+
+## Apache VFS
+
+The bundles-lib utilizes the Apache VFS library to for loading bundles.
Bundles, what are zip files of a known structure, containing
+jars of dependencies may be loaded by VFS as File Systems *themselves*,
and in tern each jar in the bundle can be loaded by VFS as a File System.
--- End diff --
editorial nits: "to for loading", "what are zip files", "in tern"
> Create a plugin system for Metron based on 'NAR'
> ------------------------------------------------
>
> Key: METRON-777
> URL: https://issues.apache.org/jira/browse/METRON-777
> Project: Metron
> Issue Type: New Feature
> Reporter: Otto Fowler
> Assignee: Otto Fowler
>
> The success of the Metron project will be greatly dependent on community
> participation, and with that the ability to adapt and extend Metron without
> having to maintain a fork of the project.
> As organizations and individuals look to extend the Metron system with custom
> parsers, enrichments, and stellar functions that may be proprietary in
> nature, the ability to develop and deploy these extensions outside the Metron
> code base is critically important.
> To that end, and after community discussion and proposal we create or
> formalize the 'plugin' development story in Metron.
> The proposal is to adapt the Apache Nifi NAR system for use in Metron. This
> will provide the system with:
> * archetype(s) for developer projects and independent development
> * defined packaging and metadata for 'plugin' products
> * loading and instantiation with classloader isolation capabilities
> * removing the necessity for shading plugin jars
> These capabilities will also enable other features, such as plugin lifecycle,
> plugin configuration+redeployment, and other things.
> The plugin archetypes and their installation will be a followon
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
