PageRenderTime 28ms CodeModel.GetById 22ms RepoModel.GetById 1ms app.codeStats 0ms

/content/server/framework/atlassian-sdk/bundling-extra-dependencies-in-an-obr.md

https://bitbucket.org/zchristmas/atlassian-sdk-docs
Markdown | 146 lines | 107 code | 39 blank | 0 comment | 0 complexity | b26db6cbf9f3025d70ce04cc0f7e3a0c MD5 | raw file
Possible License(s): LGPL-2.0
  1. ---
  2. aliases:
  3. - /server/framework/atlassian-sdk/bundling-extra-dependencies-in-an-obr-2818612.html
  4. - /server/framework/atlassian-sdk/bundling-extra-dependencies-in-an-obr-2818612.md
  5. category: devguide
  6. confluence_id: 2818612
  7. dac_edit_link: https://developer.atlassian.com/pages/editpage.action?cjm=wozere&pageId=2818612
  8. dac_view_link: https://developer.atlassian.com/pages/viewpage.action?cjm=wozere&pageId=2818612
  9. date: '2017-12-08'
  10. legacy_title: Bundling extra dependencies in an OBR
  11. platform: server
  12. product: atlassian-sdk
  13. subcategory: faq
  14. title: Bundling extra dependencies in an OBR
  15. ---
  16. # Bundling extra dependencies in an OBR
  17. With the ability to create dynamic dependencies on other plugins and libraries with OSGi and the Plugins 2 framework, the challenge becomes making sure that all the other required bundles are actually installed into the application along with your plugin. The Plugin Exchange lets you define 'dependent' plugins, but currently that information isn't used anywhere.
  18. A solution is to use an OSGi Bundle Repository (OBR) file, which is essentially a JAR file containing your plugin, any dependent plugins, and the information required to install them.
  19. ## Requirements
  20. ### UPM only
  21. Currently, you have to use the Universal Plugin Manager (UPM) to install OBR files. Installing via the older 'Plugins' console or the 'Plugin Repository' from Confluence 3.3 and earlier will not work. From Confluence 3.5 onwards, the UPM is the default and only option for installing plugins via the Administration Console.
  22. ### OSGi bundles only
  23. Any library/plugin you want to bundle must be an OSGi bundle in its own right, *with a valid `META-INF/MANIFEST.MF` file defining the OSGi bundle*. This is mainly an issue for any Atlassian-based plugins you might have, which do not generate a `MANIFEST.MF` by default. To do so, you need to declare the `<instructions>` section within the definition for the 'com.atlassian.maven.plugins' plugin for the application you're targeting. More information about this is available [here](/server/framework/atlassian-sdk/managing-dependencies).
  24. ## `pom.xml` Configuration
  25. The Atlassian Plugin SDK automatically builds an OBR for your plugin, but actually getting it to work as expected takes a bit more work. There are a few key things required to get your plugin building and installing correctly via the UPM.
  26. ### `<properties>`
  27. This step is not strictly required, but it will make it easier to ensure that you are building and deploying the same versions of your dependencies. Here, we simply create a property value for the version number of the bundled dependency.
  28. ``` xml
  29. <properties>
  30. <my.library.version>1.0</my.library.version>
  31. ....
  32. </properties>
  33. ```
  34. ### `<dependencies>`
  35. All libraries you want to have bundled **must** have an entry in the `<dependencies>` section of the `pom.xml`. They should also have a `scope` of 'provided' or 'test', otherwise they will get included directly into the plugin jar instead. Eg:
  36. ``` xml
  37. <dependencies>
  38. <dependency>
  39. <groupId>my.company.whatever</groupId>
  40. <artifactId>my-library</artifactId>
  41. <version>${my.library.version}</version>
  42. <scope>provided</scope>
  43. </dependency>
  44. ....
  45. </dependencies>
  46. ```
  47. ### AMPS
  48. There are two things to configure for the AMPS plugin: `<pluginDependencies>` and `<instructions>`.
  49. ### `<pluginDependencies>`
  50. Within the `<configuration>` section of your plugin's 'maven-&lt;application&gt;-plugin' definition for AMPS, you need to set the `<pluginDependencies>` details for the dependencies you want bundled.
  51. ### `<instructions>`
  52. The package for the dependent plugin **must** be listed in the `<Import-Package>` section of the `<instructions>` for the OSGi bundle. More details about that are [here](/server/framework/atlassian-sdk/managing-dependencies). Some plugins do not technically need to be included for your plugin to build, but if they're not listed here, they won't get installed, since the UPM does dependency checking to ensure it doesn't install libraries that it doesn't need to.
  53. It also seems that on some platforms a spurious 'CONF\_COMM' property is added to the `MANIFEST.MF` when building this way. The fix is to include an empty `<CONF_COMM/>` element in your `<instructions>`.
  54. ### Example
  55. In this example we're targeting Confluence, but similar values would be required for any other targeted application.
  56. ``` xml
  57. <build>
  58. <plugins>
  59. <plugin>
  60. <groupId>com.atlassian.maven.plugins</groupId>
  61. <artifactId>maven-confluence-plugin</artifactId>
  62. <!-- use the latest version of the SDK -->
  63. <version>3.2.4</version>
  64. <extensions>true</extensions>
  65. <configuration>
  66. <productVersion>${atlassian.product.version}</productVersion>
  67. <testResourcesVersion>${atlassian.product.data.version}</testResourcesVersion>
  68. <!-- Specify what to bundle in the OBR -->
  69. <pluginDependencies>
  70. <pluginDependency>
  71. <groupId>my.company.library</groupId>
  72. <artifactId>my-library</artifactId>
  73. </pluginDependency>
  74. </pluginDependencies>
  75. <instructions>
  76. <!-- Specify what package to include. Ensure that any packages from OBRs are also listed. -->
  77. <Import-Package>
  78. my.company.library;version="${my.library.version}",
  79. ....
  80. </Import-Package>
  81. <CONF_COMM/>
  82. ....
  83. </instructions>
  84. </configuration>
  85. </plugin>
  86. ....
  87. </plugins>
  88. ....
  89. </build>
  90. ```
  91. ## Build
  92. You should now be able to build your OBR successfully. To check that it is including what you expect, look into the `'/target/obr'` directory in your project after running a build.
  93. Once the `.obr` file is built, you should be able to install it via the UPM by manually uploading it from the 'Install' tab.
  94. ## Troubleshooting
  95. Actually getting your OBR to install successfully can be tricky. One issue is that the UPM doesn't always report useful error messages in the log about what is causing the problem. Here are a few tips:
  96. 1. **Ensure you can install the dependencies independently.** Install each dependency into the application individually first to ensure that there aren't any problems with specific libraries. The UPM reports more useful errors this way also. Often the problem is missing imports, either due to not being listed in the `<Import-Package>` section of the library, or being missing from the target application, or having a bad version number.
  97. 2. **Check the MANIFEST.MF.** This is for both the set of dependencies, and the plugin you're building. Take a look and make sure it's getting generated as you expect.
  98. 3. **Check the `obr.xml`.** Inside the OBR (and the `'/target/obr'` directory) is the `obr.xml` file, which defines the links between the plugin and its dependencies. Make sure the extra libraries/plugins are mentioned in the &lt;require&gt; sections for your target plugin.
  99. 4. **All dependencies must be in Maven.** You won't be able to build without this, but it's essential any plugins and libraries you use are available in your development Maven repository. However, they do not have to be available to the general public, since one the OBR is built it is self-contained.
  100. ## FAQ
  101. ### Why do I have to define all my imports manually now?
  102. The default mechanism used by Atlassian Plugins doesn't generate a MANIFEST.MF file, which is currently required for the UPM to know how to install the OBR file. As such, it needs to be defined manually.
  103. ### OBR vs. bundling internally and using `<Export-Package>`
  104. You can achieve almost the same effect as an OBR by bundling your dependent libraries in the same way you could for Plugins 1, and then adding an `<Export-Package>` entry for the common libraries. This is not a bad way to go, and allows plugins to share code and classes, but it has a couple of disadvantages.
  105. Firstly, it doesn't work for dependent *plugins*, since they have extra work that is done, as defined in the `atlassian-plugin.xml`, as well as potentially Spring configurations, etc. You can only export/import the classes, not have extra lifecycle stuff happen.
  106. Secondly, it's not upgradable independently. The versions you use are based on what's available in whatever other plugins you have installed.
  107. On the other hand, a potential disadvantage of OBRs is that the extra bundles will remain installed after the plugin is removed, thus consuming extra memory and/or resources.