Github user ottobackwards commented on a diff in the pull request: https://github.com/apache/metron/pull/774#discussion_r150106587 --- Diff: bundles-maven-plugin/README.md --- @@ -0,0 +1,230 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +# Apache Metron Bundle Maven Plugin + +Apache Metron Bundles Maven Plugin helps to build Bundles Archives to support the classloader isolation model. + +## Table of Contents + +- [Requirements](#requirements) +- [Building](#building) +- [Getting Stared](#getting_started) +- [Getting Help](#getting-help) +- [License](#license) + +## Requirements +* JDK 1.7 or higher +* Apache Maven 3.1.0 or higher + +## Building + +Building the bundles-maven-plugin module should be rare since it will be released infrequently compared to +the main 'metron' code tree. + +- Build with `mvn clean install` +- Presuming you need to make use of changes to the bundles-maven-plugin module, you should next + go to the [metron](../metron) directory and follow its instructions. + +## Getting Started + +While it is most likely +that a maven archetype is being utilized to create bundles, as part of a toolkit etc, you may want to create on manually, or may need to create a project for use in an archetype. + +The plugin is utilized by setting the packaging of a maven module to 'bundle'. + +```xml +<packaging>bundle</packaging> +``` + +This means that when you package this module, any of it's non-provided dependencies will be packaged into the produced bundle ( and all of their non-provided dependencies as well). +Since a library may not always be distributed as part of a bundle with all it's dependencies, the bundle module +shall be a separate module from the actual classes and dependencies to be bundled. + +A very simple example layout for a project that utilizes bundles would be: + +```bash +âââ README.md +âââ pom.xml +âââ testapp +â  âââ pom.xml +â  âââ src +â  â  âââ main +â  â  â  âââ java +â  â  â  âââ org +â  â  â  âââ apache +â  â  â  âââ test +â  â  â  âââ App.java +â  â  âââ test +â  â  âââ java +â  â  âââ org +â  â  âââ apache +â  â  âââ test +â  â  âââ AppTest.java +âââ testappbundle + âââ pom.xml +``` +Where testappbundle is the bundle module that creates a bundle of testapp, and contains the following pom.xml: +```xml +<?xml version="1.0" encoding="UTF-8"?> +<project xmlns="http://maven.apache.org/POM/4.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + <parent> + <artifactId>test.bundles.plugin</artifactId> + <groupId>org.apache.test</groupId> + <version>1.0-SNAPSHOT</version> + </parent> + <modelVersion>4.0.0</modelVersion> + + <artifactId>test.app.bundle</artifactId> + + <!-- Packaging is bundle --> + <packaging>bundle</packaging> + + <!-- All dependencies of this module, and all the dependencies of THAT dependency will + be included in the produced bundle --> + <dependencies> + <dependency> + <groupId>org.apache.test</groupId> + <artifactId>test.app</artifactId> + <version>1.0-SNAPSHOT</version> + </dependency> + </dependencies> + + <build> + <!-- OUR PLUGIN REFERENCES --> + <pluginManagement> + <plugins> + <plugin> + <groupId>org.apache.metron</groupId> + <artifactId>bundles-maven-plugin</artifactId> + <version>0.4.2</version> + <extensions>true</extensions> + <configuration> + </configuration> + </plugin> + </plugins> + </pluginManagement> + <plugins> + <plugin> + <groupId>org.apache.metron</groupId> + <artifactId>bundles-maven-plugin</artifactId> + <version>0.4.2</version> + <extensions>true</extensions> + </plugin> + </plugins> + </build> +</project> +``` +When the module is packaged, it packages all of it's non-provided dependencies into the bundles /bundled-dependencies directory. +Thus, to create a bundle of a module's jar and that jar's non-provided dependencies, you add that module to your +bundle modules dependencies. You can unzip and examine the bundle in the target directory, and verify +it's contents, which should be similar to : + +```bash +-> % tree . +. +âââ META-INF + âââ MANIFEST.MF + âââ bundled-dependencies + â  âââ log4j-1.2.17.jar + â  âââ metron-common-0.4.1.jar + â  âââ slf4j-api-1.7.7.jar + â  âââ slf4j-log4j12-1.7.7.jar + â  âââ test.app-1.0-SNAPSHOT.jar + âââ maven + âââ org.apache.test + âââ test.app.bundle + âââ pom.properties + âââ pom.xml +``` + +This reflects the testapp project, which has these dependencies : + +```xml +<dependencies> + <dependency> + <groupId>org.apache.metron</groupId> + <artifactId>metron-common</artifactId> + <version>0.4.1</version> + </dependency> + <dependency> + <groupId>junit</groupId> + <artifactId>junit</artifactId> + <version>3.8.1</version> + <scope>test</scope> + </dependency> + </dependencies> +``` +metron-common itself is a shaded jar, but it depends on log4j and slf4j, so those libraries are pulled in.. + +## Quickstart + +* Create a new multi module maven project (if you do not have one already) +* Add a new module for your bundle, it needs only to have a pom.xml +* Create the pom.xml as above, with the correct plugin and packaging entries, and add dependencies +for the module you want to bundle. +* `mvn package` --- End diff -- I wish you would have stated your disagreement during the community meeting, or in the email list on the 26th when you gave a +1 to this. It is unfortunate that we again have gone months on a PR in this now year long effort to no effect, especially since as stated this was supposed to be the 'lighter' review of all the pr's. That being said, we should not be discouraging reviews under any circumstances, and your review certainly matters. So please. Can you explain what would would like to do based on your current understanding now that I have attempted to clarify things, and tried to describe the projects that are present?
---