The document discusses OSGi and plugins, providing an overview of OSGi concepts and best practices for developing OSGi bundles. It recommends developers carefully manage bundle manifests to control dependencies and classloading, leverage the Felix web console for debugging, and understand what capabilities host applications provide.

1. 1

2. Plugins 2 and OSGi Gotchas
Or: How I learned to stop worrying and love Apache Felix
John Kodumal
Atlassian Developer
2
2

3. Agenda
• Background
• OSGi Primer
• Protips
1. Be the master of your manifest
2. Manage your dependencies
3. Earn a brown belt in OSGi classloading
4. Buddy up with the Felix web console
5. Know what the applications provide
3
3

4. OSGi from 10,000 feet
Services
Bundles
Lifecycle
Modules
Execution Environment
4
4

5. OSGi Benefits
5
5

6. Migrate to Plugins 2.0
• Convert plugin to plugins 2
• http://confluence.atlassian.com/x/bwLvCw
• Convert plugin project to SDK
• http://confluence.atlassian.com/x/wRyyCg
6
6

7. OSGi as a black box?
The Atlassian Plugin Framework 2 tries to hide the complexity of OSGi as
much as possible...
If you are familiar with OSGi and want to provide an OSGi bundle directly in
order to leverage all its features, you are free to do so.
http://confluence.atlassian.com/x/DIBiCg
7
7

8. OSGi as a black box?
OSGi
Knowledge
crazy plugins
(dashboards)
simple plugins
(gadgets)
sweet spot
Plugin
Complexity
8
8

9. Agenda
• Background
• OSGi Primer
• Protips
1. Be the master of your manifest
2. Manage your dependencies
3. Earn a brown belt in OSGi classloading
4. Buddy up with the Felix web console
5. Know what the applications provide
9
9

10. OSGi Concepts
10
10

11. Anatomy of an OSGi Bundle
Package Exports
OSGi Bundle
Manifest
Activator
Services
Private Classloader
Private Packages
Package Imports
11
11

12. How Bundles Interact
your plugin google collections 1.0
com.google.collect v1.0
Wire
12
12

13. Agenda
• Background
• Overview of OSGi
• Protips
1. Be the master of your manifest
2. Manage your dependencies
3. Earn a brown belt in OSGi classloading
4. Buddy up with the Felix web console
5. Know what the applications provide
13
13

14. #1 Be the master of your manifest
Manifest-Version: 1.0
Created-By: 1.5.0_19 (Apple Inc.)
Bundle-Name: gdata-service-plugin
Bundle-SymbolicName: com.atlassian.agmp.gdata-service-plugin
Bundle-Description: This is the com.atlassian.agmp:gdata-service-plugin plugin for Atlassian Refapp.
Bundle-ClassPath: .,META-INF/lib/commons-lang-2.4.jar,META-INF/lib/joda-time-1.6.jar
Import-Package: com.atlassian.agmp.integration.common;version="0.0.0",
com.atlassian.templaterenderer.annotations;version="0.0.0",com.atlassian.templaterenderer.velocity.one.six;version="0.0.0",c
om.google.common.base;version="0.0.0",com.google.gdata.client;version="1.40.1",com.google.gdata.client.authn.oauth;versi
on="1.40.1",com.google.gdata.client.calendar;version="1.40.1",com.google.gdata.client.docs;version="1.40.1",com.google.gd
Bundle-Name: gdata-service-plugin
ata.client.media;version="1.40.1",com.google.gdata.data;version="1.40.1",com.google.gdata.data.calendar;version="1.40.1",c
Bundle-SymbolicName: com.atlassian.agmp.gdata-service-plugin
om.google.gdata.data.docs;version="1.40.1",com.google.gdata.data.media;version="1.40.1",com.google.gdata.util;version="1
.40.1",com.google.gdata.util.common.base;version="1.40.1",com.google.gdata.util.common.xml;version="1.40.1",javax.servlet
Bundle-Description: This is the com.atlassian.agmp:gdata-service-plugin plugin for Atlassian Refapp.
;version="0.0.0",javax.servlet.http;version="0.0.0",org.apache.commons.io;version="1.3",org.apache.log4j;version="0.0.0",org.
springframework.beans.factory.annotation;version="0.0.0"
Export-Package: com.atlassian.agmp.gdata;uses:="com.google.gdata.util";version="1.1.4.SNAPSHOT"
Bundle-Version: 1.1.4.SNAPSHOT
Bundle-DocURL: http://www.atlassian.com/
Bundle-Vendor: Atlassian
Bundle-ManifestVersion: 2
Tool: Bnd-0.0.311
14
14

15. #1 Be the master of your manifest
Manifest-Version: 1.0
Created-By: 1.5.0_19 (Apple Inc.)
Bundle-Name: gdata-service-plugin
Bundle-SymbolicName: com.atlassian.agmp.gdata-service-plugin
Bundle-Description: This is the com.atlassian.agmp:gdata-service-plugin plugin for Atlassian Refapp.
Bundle-ClassPath: .,META-INF/lib/commons-lang-2.4.jar,META-INF/lib/joda-time-1.6.jar
Import-Package: com.atlassian.agmp.integration.common;version="0.0.0",
com.atlassian.templaterenderer.annotations;version="0.0.0",com.atlassian.templaterenderer.velocity.one.six;version="0.0.0",c
om.google.common.base;version="0.0.0",com.google.gdata.client;version="1.40.1",com.google.gdata.client.authn.oauth;versi
on="1.40.1",com.google.gdata.client.calendar;version="1.40.1",com.google.gdata.client.docs;version="1.40.1",com.google.gd
Bundle-ClassPath: .,META-INF/lib/commons-lang-2.4.jar,META-INF/lib/joda-time-1.6.jar
ata.client.media;version="1.40.1",com.google.gdata.data;version="1.40.1",com.google.gdata.data.calendar;version="1.40.1",c
om.google.gdata.data.docs;version="1.40.1",com.google.gdata.data.media;version="1.40.1",com.google.gdata.util;version="1
.40.1",com.google.gdata.util.common.base;version="1.40.1",com.google.gdata.util.common.xml;version="1.40.1",javax.servlet
;version="0.0.0",javax.servlet.http;version="0.0.0",org.apache.commons.io;version="1.3",org.apache.log4j;version="0.0.0",org.
springframework.beans.factory.annotation;version="0.0.0"
Export-Package: com.atlassian.agmp.gdata;uses:="com.google.gdata.util";version="1.1.4.SNAPSHOT"
Bundle-Version: 1.1.4.SNAPSHOT
Bundle-DocURL: http://www.atlassian.com/
Bundle-Vendor: Atlassian
Bundle-ManifestVersion: 2
Tool: Bnd-0.0.311
15
15

16. #1 Be the master of your manifest
Manifest-Version: 1.0
Created-By: 1.5.0_19 (Apple Inc.)
Bundle-Name: gdata-service-plugin
Bundle-SymbolicName: com.atlassian.agmp.gdata-service-plugin
Import-Package: Bundle-Description: This is the com.atlassian.agmp:gdata-service-plugin plugin for Atlassian Refapp.
com.atlassian.agmp.integration.common;version="0.0.0",
Bundle-ClassPath: .,META-INF/lib/commons-lang-2.4.jar,META-INF/lib/joda-time-1.6.jar
com.atlassian.templaterenderer.annotations;version="0.0.0",com.atlassian.templaterenderer.velocity.
Import-Package: com.atlassian.agmp.integration.common;version="0.0.0",
one.six;version="0.0.0",com.google.common.base;version="0.0.0",com.google.gdata.client;version="
com.atlassian.templaterenderer.annotations;version="0.0.0",com.atlassian.templaterenderer.velocity.one.six;version="0.0.0",c
om.google.common.base;version="0.0.0",com.google.gdata.client;version="1.40.1",com.google.gdata.client.authn.oauth;versi
1.40.1",com.google.gdata.client.authn.oauth;version="1.40.1",com.google.gdata.client.calendar;versi
on="1.40.1",com.google.gdata.client.calendar;version="1.40.1",com.google.gdata.client.docs;version="1.40.1",com.google.gd
ata.client.media;version="1.40.1",com.google.gdata.data;version="1.40.1",com.google.gdata.data.calendar;version="1.40.1",c
on="1.40.1",com.google.gdata.client.docs;version="1.40.1",com.google.gdata.client.media;version="
om.google.gdata.data.docs;version="1.40.1",com.google.gdata.data.media;version="1.40.1",com.google.gdata.util;version="1
1.40.1",com.google.gdata.data;version="1.40.1",com.google.gdata.data.calendar;version="1.40.1",co
.40.1",com.google.gdata.util.common.base;version="1.40.1",com.google.gdata.util.common.xml;version="1.40.1",javax.servlet
;version="0.0.0",javax.servlet.http;version="0.0.0",org.apache.commons.io;version="1.3",org.apache.log4j;version="0.0.0",org.
m.google.gdata.data.docs;version="1.40.1",com.google.gdata.data.media;version="1.40.1",com.goo
springframework.beans.factory.annotation;version="0.0.0"
Export-Package: com.atlassian.agmp.gdata;uses:="com.google.gdata.util";version="1.1.4.SNAPSHOT"
gle.gdata.util;version="1.40.1",com.google.gdata.util.common.base;version="1.40.1",com.google.gda
Bundle-Version: 1.1.4.SNAPSHOT
ta.util.common.xml;version="1.40.1",javax.servlet;version="0.0.0",javax.servlet.http;version="0.0.0",o
Bundle-DocURL: http://www.atlassian.com/
Bundle-Vendor: Atlassian
rg.apache.commons.io;version="1.3",org.apache.log4j;version="0.0.0",org.springframework.beans.fa
Bundle-ManifestVersion: 2
Tool: Bnd-0.0.311
ctory.annotation;version="0.0.0"
16
16

17. #1 Be the master of your manifest
Manifest-Version: 1.0
Created-By: 1.5.0_19 (Apple Inc.)
Bundle-Name: gdata-service-plugin
Bundle-SymbolicName: com.atlassian.agmp.gdata-service-plugin
Bundle-Description: This is the com.atlassian.agmp:gdata-service-plugin plugin for Atlassian Refapp.
Bundle-ClassPath: .,META-INF/lib/commons-lang-2.4.jar,META-INF/lib/joda-time-1.6.jar
Import-Package: com.atlassian.agmp.integration.common;version="0.0.0",
com.atlassian.templaterenderer.annotations;version="0.0.0",com.atlassian.templaterenderer.velocity.one.six;version="0.0.0",c
om.google.common.base;version="0.0.0",com.google.gdata.client;version="1.40.1",com.google.gdata.client.authn.oauth;versi
on="1.40.1",com.google.gdata.client.calendar;version="1.40.1",com.google.gdata.client.docs;version="1.40.1",com.google.gd
Export-Package: com.atlassian.agmp.gdata;uses:="com.google.gdata.util";version="1.1.4.SNAPSHOT"
ata.client.media;version="1.40.1",com.google.gdata.data;version="1.40.1",com.google.gdata.data.calendar;version="1.40.1",c
om.google.gdata.data.docs;version="1.40.1",com.google.gdata.data.media;version="1.40.1",com.google.gdata.util;version="1
.40.1",com.google.gdata.util.common.base;version="1.40.1",com.google.gdata.util.common.xml;version="1.40.1",javax.servlet
;version="0.0.0",javax.servlet.http;version="0.0.0",org.apache.commons.io;version="1.3",org.apache.log4j;version="0.0.0",org.
springframework.beans.factory.annotation;version="0.0.0"
Export-Package: com.atlassian.agmp.gdata;uses:="com.google.gdata.util";version="1.1.4.SNAPSHOT"
Bundle-Version: 1.1.4.SNAPSHOT
Bundle-DocURL: http://www.atlassian.com/
Bundle-Vendor: Atlassian
Bundle-ManifestVersion: 2
Tool: Bnd-0.0.311
17
17

18. #1 Be the master of your manifest
<build>
<plugins>
<plugin>
<groupId>com.atlassian.maven.plugins</groupId>
<instructions> <artifactId>maven-refapp-plugin</artifactId>
<Import-Package> <version>3.0.2</version>
<extensions>true</extensions>
javax.servlet*;version="0.0.0",
<configuration>
org.apache.commons.io;version="1.3",
<productVersion>${refapp.version}</productVersion>
com.atlassian.agmp.integration.common*;version="0.0.0",
<instructions>
<Import-Package>
com.google.gdata*;version="1.40.1",
javax.servlet*;version="0.0.0",
com.google.common*;version="0.0.0",
org.apache.commons.io;version="1.3",
org.springframework.beans*;version="0.0.0",
com.atlassian.agmp.integration.common*;version="0.0.0",
com.google.gdata*;version="1.40.1",
com.atlassian.templaterenderer.*;version="0.0.0",
com.google.common*;version="0.0.0",
org.apache.log4j*;version="0.0.0"
org.springframework.beans*;version="0.0.0",
</Import-Package> com.atlassian.templaterenderer.*;version="0.0.0",
<Export-Package> org.apache.log4j*;version="0.0.0"
</Import-Package>
com.atlassian.agmp.gdata
<Export-Package>
</Export-Package> com.atlassian.agmp.gdata
<instructions> </Export-Package>
</instructions>
</plugin>
…
</build>
18
18

19. #2 Manage your dependencies
• Prefer Import-Package dependencies over Require-Bundle
vs.
Import-Package Require-Bundle
19
19

20. #2 Manage your dependencies
• Prefer Import-Package dependencies over Bundle-Classpath
vs.
Import-Package Bundle-Classpath
20
20

21. #2 Manage your dependencies
• Always specify package versions for imports and exports
• Versions are specified in <major>.<minor>.<micro>.<qualifier> form
• Bundle constraints use interval range notation
• e.g. “[1.0.0, 2.0.0 )”
• A missing upper bound denotes infinity
• So version=“1.0.0” really means version >= “1.0.0”
• version=“0.0.0” means “any version”
• Thatʼs right! OSGi has redefined equals to mean greater than. Top notch!
• Put version constraints in quotes
21
21

22. #2 Manage your dependencies
• Run mvn:dependency-tree and scan your dependencies manually
• Use the maven dependency tracker plugin if youʼre paranoid
• https://labs.atlassian.com/browse/MAP
•
22
22

23. #3 Earn a brown belt in OSGi classloading
Start
Delegate to parent found?
java.*?
classloader
boot Delegate to parent found?
classloader
package- found?
import? Delegate to wire exporter
bundle found?
classpath?
23
23

24. #3 Earn a brown belt in OSGi classloading
• Boot delegated packages cannot be overridden
• Even with packages in your bundle classpath!
• Plugins 2.x boot delegates several packages
• Packages for profiling tools (e.g. com.yourkit)
• And xerces
24
24

25. #4 Buddy up with the Felix web console
• http://${baseURL}/plugins/servlet/system/console
• username : admin
• password : admin
25
25

26. #4 Or try the OSGi Explorer plugin
https://plugins.atlassian.com/plugin/details/23455
26
26

27. #5 Know what the applications provide
ion
aseURL}/admin/p luginexports.act
http://${b
27
27

28. #5 Know what the applications provide
• http://${ baseURL}/plugins/servlet/system/console
• username : admin
• password : admin
28
28

29. Recap
• Background
• OSGi Primer
• Protips
1. Be the master of your manifest
2. Manage your dependencies
3. Earn a brown belt in OSGi classloading
4. Buddy up with the Felix web console
5. Know what the applications provide
29
29

30. Resources
• Convert plugin to plugins 2
• http://confluence.atlassian.com/x/bwLvCw
• Convert plugin project to SDK
• http://confluence.atlassian.com/x/wRyyCg
• Felix web console
• http://${baseURL}/plugins/servlet/system/console
• Confluence exported beans
• http://${baseURL}/admin/pluginexports.action
30
30