Merge pull request #29 from dotCMS/issue-13482-Updating-examples

Issue 13482 updating examples

OSGi/com.dotcms.3rd.party/README.md

@@ -0,0 +1,71 @@
+# README
+
+This bundle plugin is an example of how to add 3rd party jars to a bundle plugin.
+
+## How to build this example
+
+To install all you need to do is build the JAR. to do this run
+`./gradlew jar`
+
+This will build two jars in the `build/libs` directory: a bundle fragment (in order to expose needed 3rd party libraries from dotCMS) and the plugin jar 
+
+* **To install this bundle:**
+
+    Copy the bundle jar files inside the Felix OSGI container (*dotCMS/felix/load*).
+
+    OR
+
+    Upload the bundle jars files using the dotCMS UI (*CMS Admin->Dynamic Plugins->Upload Plugin*).
+
+* **To uninstall this bundle:**
+
+    Remove the bundle jars files from the Felix OSGI container (*dotCMS/felix/load*).
+
+    OR
+
+    Undeploy the bundle jars using the dotCMS UI (*CMS Admin->Dynamic Plugins->Undeploy*).
+
+## How to create a bundle plugin with external jars
+
+In order to create this OSGI plugin, you must create a `META-INF/MANIFEST` to be inserted into OSGI jar.
+This file is being created for you by Gradle. If you need you can alter our config for this but in general our out of the box config should work.
+The Gradle plugin uses BND to generate the Manifest. The main reason you need to alter the config is when you need to exclude a package you are including on your Bundle-ClassPath
+
+If you are building the MANIFEST on your own or desire more info on it below is a description of what is required in this MANIFEST you must specify (see template plugin):
+
+```
+    Bundle-Name: The name of your bundle
+    Bundle-SymbolicName: A short an unique name for the bundle
+    Bundle-Activator: Package and name of your Activator class (example: com.dotmarketing.osgi.override.Activator)
+    Export-Package: Declares the packages that are visible outside the plugin. Any package not declared here has visibility only within the bundle.
+    Import-Package: This is a comma separated list of the names of packages to import. In this list there must be the packages that you are using inside your osgi bundle plugin and are exported and exposed by the dotCMS runtime.
+```
+
+## Beware (!)
+
+In order to work inside the Apache Felix OSGI runtime, the import and export directive must be bidirectional, there are two ways to accomplish this:
+
+* **Exported Packages**
+
+    The dotCMS must declare the set of packages that will be available to the OSGI plugins by changing the file: *dotCMS/WEB-INF/felix/osgi-extra.conf*.
+This is possible also using the dotCMS UI (*CMS Admin->Dynamic Plugins->Exported Packages*).
+
+    Only after that exported packages are defined in this list, a plugin can Import the packages to use them inside the OSGI blundle.
+
+* **Fragment**
+
+    A Bundle fragment, is a bundle whose contents are made available to another bundles exporting 3rd party libraries from dotCMS.
+One notable difference is that fragments do not participate in the lifecycle of the bundle, and therefore cannot have an Bundle-Activator.
+As it not contain a Bundle-Activator a fragment cannot be started so after deploy it will have its state as Resolved and NOT as Active as a normal bundle plugin.
+
+---
+## Components
+
+### com.dotmarketing.osgi.external.Examples
+
+Example class that will run simple examples using the 3rd party library that was added to the lib folder of the bundle (lib/date4j.jar).
+
+### Activator
+
+This bundle activator extends from com.dotmarketing.osgi.GenericBundleActivator and implements BundleActivator.start().
+Calls the Examples class static methods to run simple tests that use the 3rd party library date4j.jar

OSGi/com.dotcms.3rd.party/build.gradle

@@ -3,34 +3,101 @@ plugins {
 }
 
 sourceCompatibility = '1.8'
-version = '0.1'
+version = '0.2'
 
 repositories {
     maven { url "http://repo.dotcms.com/artifactory/libs-release" }
 }
 
-configurations {
-    osgiLibs
-}
-
 dependencies {
     compile fileTree(dir: 'src/main/resources/libs', include: '*.jar')
     compile('com.dotcms:dotcms:4.3.2') { transitive = true }
 }
 
+import java.util.jar.*
+
+/////////////////////////
+//Plugin jar
+/////////////////////////
 jar {
     manifest {
         attributes (
                 'Bundle-Vendor': 'dotCMS',
-                'Bundle-Description': 'dotCMS - dotCMS OSGI Party library example',
+                'Bundle-Description': 'dotCMS - OSGI 3rd Party library example',
                 'Bundle-DocURL': 'https://dotcms.com/',
                 'Bundle-Activator': 'com.dotmarketing.osgi.external.Activator',
                 'Bundle-ClassPath': '.,libs/date4j.jar',
-                'DynamicImport-Package': '*',
                 'Import-Package': '!hirondelle.date4j.*,*;version=0'
         )
     }
 }
+jar.finalizedBy 'fragmentJar'
+
+/////////////////////////
+//Fragment jar
+/////////////////////////
+
+ext {
+    bundleName = "OSGI 3rd Party library fragment"
+    bundleDescription = "dotCMS - OSGI 3rd Party library fragment"
+    fragmentHost = "system.bundle; extension:=framework"
+    bundleSymbolicName = "" //Auto generated based on the plugin jar
+    bundleVersion = "" //Auto generated based on the plugin jar
+    importPackage = "" //Auto generated based on the plugin jar
+    bundleManifestVersion = "" //Auto generated based on the plugin jar
+    bundleDocURL = "" //Auto generated based on the plugin jar
+    bundleVendor = "" //Auto generated based on the plugin jar
+}
+/**
+ * The import generates versions like this: version="[1.8,2)"
+ * That format does not work for the export, so we need to replace it
+ * to: version=0
+ */
+ext.fixVersionNumber = {importValue ->
+    return importValue.replaceAll("\"\\[[0-9.,]+\\)\"", "0")
+}
+
+/**
+ * Reads the Manifest file of the just created plugin jar in order to get the required info
+ * to automatically create the fragment jar.
+ */
+task readManifesttAttributes {
+    doFirst {
+        File file = configurations.baseline.singleFile
+        JarFile jar = new JarFile(file)
+        Attributes manifest = jar.getManifest().getMainAttributes()
+        bundleSymbolicName = "${manifest.getValue('Bundle-SymbolicName')}"
+        bundleVersion = "${manifest.getValue('Bundle-Version')}"
+        importPackage = "${manifest.getValue('Import-Package')}"
+        bundleManifestVersion = "${manifest.getValue('Bundle-ManifestVersion')}"
+        bundleDocURL = "${manifest.getValue('Bundle-DocURL')}"
+        bundleVendor = "${manifest.getValue('Bundle-Vendor')}"
+    }
+}
+task fragmentJar(type: Jar) {
+
+    doFirst {
+        //Setting the fragment jar name
+        baseName = project.name
+        archiveName = "${baseName}.fragment-${version}.jar"
+        importPackage = fixVersionNumber(importPackage)
+
+        manifest {
+            attributes (
+                    'Bundle-Name': "${bundleName}",
+                    'Bundle-Description': "${bundleDescription}",
+                    'Bundle-Vendor': "${bundleVendor}",
+                    'Bundle-Version': "${version}",
+                    'Bundle-SymbolicName': "${baseName}.fragment",
+                    'Bundle-ManifestVersion': "${bundleManifestVersion}",
+                    'Bundle-DocURL': "${bundleDocURL}",
+                    'Fragment-Host': "${fragmentHost}",
+                    'Export-Package': "${importPackage}"
+            )
+        }
+    }
+}
+fragmentJar.dependsOn 'readManifesttAttributes'
 
 task wrapper(type: Wrapper) {
     gradleVersion = '4.2'

OSGi/com.dotcms.actionlet/README.md

@@ -0,0 +1,71 @@
+# README
+
+This bundle plugin is an example of how to add dotcms WorkFlowActionlet classes with our bundle plugin.
+
+## How to build this example
+
+To install all you need to do is build the JAR. to do this run
+`./gradlew jar`
+
+This will build two jars in the `build/libs` directory: a bundle fragment (in order to expose needed 3rd party libraries from dotCMS) and the plugin jar 
+
+* **To install this bundle:**
+
+    Copy the bundle jar files inside the Felix OSGI container (*dotCMS/felix/load*).
+
+    OR
+
+    Upload the bundle jars files using the dotCMS UI (*CMS Admin->Dynamic Plugins->Upload Plugin*).
+
+* **To uninstall this bundle:**
+
+    Remove the bundle jars files from the Felix OSGI container (*dotCMS/felix/load*).
+
+    OR
+
+    Undeploy the bundle jars using the dotCMS UI (*CMS Admin->Dynamic Plugins->Undeploy*).
+
+## How to add a Actionlet OSGI plugin
+
+In order to create this OSGI plugin, you must create a `META-INF/MANIFEST` to be inserted into OSGI jar.
+This file is being created for you by Gradle. If you need you can alter our config for this but in general our out of the box config should work.
+The Gradle plugin uses BND to generate the Manifest. The main reason you need to alter the config is when you need to exclude a package you are including on your Bundle-ClassPath
+
+If you are building the MANIFEST on your own or desire more info on it below is a description of what is required in this MANIFEST you must specify (see template plugin):
+
+```
+    Bundle-Name: The name of your bundle
+    Bundle-SymbolicName: A short an unique name for the bundle
+    Bundle-Activator: Package and name of your Activator class (example: com.dotmarketing.osgi.override.Activator)
+    Export-Package: Declares the packages that are visible outside the plugin. Any package not declared here has visibility only within the bundle.
+    Import-Package: This is a comma separated list of the names of packages to import. In this list there must be the packages that you are using inside your osgi bundle plugin and are exported and exposed by the dotCMS runtime.
+```
+
+## Beware (!)
+
+In order to work inside the Apache Felix OSGI runtime, the import and export directive must be bidirectional, there are two ways to accomplish this:
+
+* **Exported Packages**
+
+    The dotCMS must declare the set of packages that will be available to the OSGI plugins by changing the file: *dotCMS/WEB-INF/felix/osgi-extra.conf*.
+This is possible also using the dotCMS UI (*CMS Admin->Dynamic Plugins->Exported Packages*).
+
+    Only after that exported packages are defined in this list, a plugin can Import the packages to use them inside the OSGI blundle.
+
+* **Fragment**
+
+    A Bundle fragment, is a bundle whose contents are made available to another bundles exporting 3rd party libraries from dotCMS.
+One notable difference is that fragments do not participate in the lifecycle of the bundle, and therefore cannot have an Bundle-Activator.
+As it not contain a Bundle-Activator a fragment cannot be started so after deploy it will have its state as Resolved and NOT as Active as a normal bundle plugin.
+
+---
+## Components
+
+### com.dotmarketing.osgi.actionlet.MyActionlet
+
+Implementation of a WorkFlowActionlet object.
+
+### Activator
+
+This bundle activator extends from com.dotmarketing.osgi.GenericBundleActivator and implements BundleActivator.start().
+This activator will allow you to register the WorkFlowActionlet object using the GenericBundleActivator.registerActionlet method