Understanding OSGI Bundle states

Eclipse runs on top of the OSGi runtime, which manages the bundles (components) that make up an application. At any time, each bundle has one of these lifecycle states:

Bundle States:

• Not in the list - If your bundle isn't in the list, then OSGi doesn't know anything about it. See the next section for debugging this problem.
• INSTALLED - This means that OSGi knows about your bundle but there is something wrong and it couldn't resolve. Problems may include thing from missing dependencies to requiring a higher Java VM version than you are running with. To get more information on why your bundle is not resolved try running the diag <bundle id> command, where <bundle id> is your bundle id or bundle symbolic name.
• RESOLVED - If your bundle is resolved but you expected it to be started, then try starting your bundle from the command-line with the start 123 command. If it won't start, then you should get some feedback as to what the problem is.
• <<lazy>> - This means your bundle is resolved and is marked to be lazy started. Everything should be ok.
• ACTIVE - your bundle is resolved and has been started, everything should be working as planned.

(source: OSGi Service Platform – Core Specification)

For example: I want to check the bundle states for my company plugins so I will use the below command.

osgi> ss com.espressif

"Framework is launched."

id State       Bundle

6 RESOLVED    com.espressif.idf.branding_1.2.0.qualifier

7 ACTIVE      com.espressif.idf.core_1.0.0.qualifier

8 STARTING    com.espressif.idf.help_1.0.0.qualifier

9 ACTIVE      com.espressif.idf.launch.serial.core_1.0.0.qualifier

10 ACTIVE      com.espressif.idf.launch.serial.ui_1.0.0.qualifier

11 STARTING    com.espressif.idf.sdk.config.core_1.0.1.qualifier

12 STARTING    com.espressif.idf.sdk.config.ui_1.0.0.qualifier

13 STARTING    com.espressif.idf.terminal.connector_1.0.0.qualifier

14 STARTING    com.espressif.idf.terminal.connector.serial_1.0.0.qualifier

15 ACTIVE      com.espressif.idf.ui_1.0.0.qualifier

721 ACTIVE      com.espressif.idf.debug.gdbjtag.openocd_1.0.0.qualifier

References:

https://wiki.eclipse.org/Where_Is_My_Bundle

Debugging options for org.eclipse.osgi

#### Debugging options for org.eclipse.osgi

# Turn on general debugging for org.eclipse.osgi
org.eclipse.osgi/debug=false
# Prints out class loading debug information
org.eclipse.osgi/debug/loader=false
# Prints out event (FrameworkEvent/BundleEvent/ServiceEvent) and listener debug information
org.eclipse.osgi/debug/events=false
# Prints out OSGi service debug information (registration/getting/ungetting etc.)
org.eclipse.osgi/debug/services=false
# Prints out bundle manifest parsing debug information
org.eclipse.osgi/debug/manifest=false
# Prints out LDAP filter debug information
org.eclipse.osgi/debug/filter=false
# Prints out security (PermissionAdmin service) debug information
org.eclipse.osgi/debug/security=false
# Prints out start level service debug information
org.eclipse.osgi/debug/startlevel=false
# Prints out package admin service debug information
org.eclipse.osgi/debug/packageadmin=false
# Prints out timing information for bundle activation
org.eclipse.osgi/debug/bundleTime=false
# Debug the loading of message bundles
org.eclipse.osgi/debug/messageBundles=false
# Debug the object pool additions
org.eclipse.osgi/debug/objectPool/adds=false
# Debug the object pool duplications
org.eclipse.osgi/debug/objectPool/dups=false

# Eclipse adaptor options
org.eclipse.osgi/eclipseadaptor/debug = false
org.eclipse.osgi/eclipseadaptor/debug/location = false
org.eclipse.osgi/eclipseadaptor/debug/cachedmanifest = false
org.eclipse.osgi/eclipseadaptor/debug/platformadmin=false
org.eclipse.osgi/eclipseadaptor/debug/platformadmin/resolver=false
org.eclipse.osgi/eclipseadaptor/converter/debug = false

### OSGi resolver options
# Turns on debugging for the resolver
org.eclipse.osgi/resolver/debug = false
# Prints out wiring information after the resolver has completed the resolve process
org.eclipse.osgi/resolver/wiring = false
# Prints out Import-Package information
org.eclipse.osgi/resolver/imports = false
# Prints out Require-Bundle information
org.eclipse.osgi/resolver/requires = false
# Prints out debug information form the "uses" clause
org.eclipse.osgi/resolver/uses = false
# Prints out cycle information
org.eclipse.osgi/resolver/cycles = false
# Prints out Eclipse-GenericRequire information
org.eclipse.osgi/resolver/generics = false

#### Profile settings
org.eclipse.osgi/profile/startup = false
org.eclipse.osgi/profile/benchmark = false
org.eclipse.osgi/profile/debug = false

# Override the default implemenation 
org.eclipse.osgi/profile/impl = org.eclipse.osgi.internal.profile.DefaultProfileLogger

# Append all profile messages to the filename specified
org.eclipse.osgi/defaultprofile/logfilename = 

# Output all profile log messages synchronously to the jvm console.
# By default, all log messages are cached until the log buffer is
# requested.
org.eclipse.osgi/defaultprofile/logsynchronously = false

# Specify the size of the default profile implementation log buffer.
org.eclipse.osgi/defaultprofile/buffersize = 256

#### Monitoring settings
# monitor class loading
org.eclipse.osgi/monitor/classes=false

# monitor bundle activation
org.eclipse.osgi/monitor/activation=false

# monitor resource bundle (*.properties) loading
org.eclipse.osgi/monitor/resources=false


#### Trace settings
# trace class loading - snapshot the execution stack when a class is loaded
org.eclipse.osgi/trace/classLoading=false

# trace location - file in which execution traces are written
org.eclipse.osgi/trace/filename=runtime.traces

# trace filters - Java properties file defining which classes should 
# be traced (if trace/classLoading is true)
# File format:
# plugins=<comma separated list of plugins whose classes to trace>
# packages=<comma separated list of package prefixes of classes to trace>
# Note that there may be many 'plugins' and 'packages' lines in one file.
org.eclipse.osgi/trace/filters=trace.properties

# trace bundle activation - snapshot the execution stack when a bundle is activated
org.eclipse.osgi/trace/activation=false

Eclipse based products - version numbering

Eclipse Versioning
https://wiki.eclipse.org/Version_Numbering#When_to_change_the_major_segment

Understand more about semantic versioning for eclipse and OSGI products:
http://www.osgi.org/wp-content/uploads/SemanticVersioning1.pdf


Difference between Eclipse versioning and Semantic Versioning(http://semver.org)
http://eclipsesource.com/blogs/2013/06/28/semantic-versioning-for-eclipse-developers/

Fragments in OSGI - Eclipse

A Bundle fragment, or simply a fragment, is a bundle whose contents are made available to another bundle (the fragment host). Importantly, fragments share the classloader of their parent bundle. One notable difference is that fragments do not participate in the lifecycle of the bundle, and therefore cannot have an Bundle-Activator.

http://wiki.osgi.org/wiki/Fragment-Host

http://wiki.osgi.org/wiki/Fragment

http://www.vogella.com/tutorials/EclipseFragmentProject/article.html#fragement_usage

Example:

These are 2 plugins which does not have any activator classes.

org.eclipse.epp.logging.aeri.ui

org.eclipse.epp.logging.aeri.ide - Host Plugin

And, In org.eclipse.epp.logging.aeri.ide plugin MANIFEST.MF file, you can find below section:

Fragment-Host: org.eclipse.epp.logging.aeri.ui;bundle-version="1.0.0"

At runtime the fragment is merged with its host plug-in and for the runtime both projects are just one. Fragments are always optional for their host plug-in and the host plug-in doesn't even know that it exists.

Packaging *.dll files with in a eclipse plug-in

Understand more about OSGI class loaders:
http://www.eclipsezone.com/articles/eclipse-vms/

Understand more about how OSGI loads DLL files and how to package with a plug-in:
http://blog.vogella.com/2010/07/27/osgi/

Eclipse bundles.info

What is bundles.info file in eclipse ?

The file bundles.info contains a list of all the plug-ins installed in the current system. On startup, all the plug-ins listed in this file are given to OSGi as the exact set of plug-ins to run with.

Where can i find this file in eclipse ?

You can find in eclipse/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info

eclipse/
   configuration/
     config.ini
     org.eclipse.equinox.simpleconfigurator/
       bundles.info
   dropins/
   features/
   p2/
   plugins/
   eclipse.exe
   eclipse.ini
   ...

Resources:
https://wiki.eclipse.org/Equinox/p2/Getting_Started

Lazy eclipse plugin/bundle state

Plug-ins that are resolved and that have a bundle activation policy of lazy will enter the Starting state. The console window may show bundle state as <<LAZY>>. This indicates a bundle in the Starting state waiting for a class access to transition to active.

If any plug-in that remains in a starting state is indicating of a plugin that is failing to use best practices of eclipse bundlee activator class.

http://wiki.eclipse.org/Lazy_Start_Bundles
http://wiki.eclipse.org/Where_Is_My_Bundle

OSGI and start levels

Eclipse Plug-in start levels are there to simply determine the start order of bundles.
But as a developer or end user, we should never treat or code based on the order of OSGI start levels, it's completely managed by OSGI framework.

At least as of now, I have never come across the situation where I need to modify the plugin start level to launch an eclipse or develop Eclipse RCP Applications.

References:
http://eclipsesource.com/blogs/2009/06/10/osgi-and-start-levels/

http://aaronz-sakai.blogspot.in/2009/05/osgi-system-and-bundle-start-levels.html

http://www.osgi.org/download/r4v41/r4.core.pdf

http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html

From eclipse run time options:
The start-level indicates the OSGi start level at which the bundle should run. If the start-level (>0 integer) is omitted then the framework will use the default start level for the bundle.

If they do not specify a startlevel then they default to the value of osgi.bundles.defaultStartLevel. The default value of osgi.bundles.defaultStartLevel is 4

Understanding how Eclipse plug-ins work with OSGi

Eclipse OSGI plugins
http://www.ibm.com/developerworks/opensource/library/os-ecl-osgi/

OSGI Console options
http://www.ibm.com/developerworks/opensource/library/os-ecl-osgiconsole/

Install the plug-in bundle in the Equinox console

1. Install the plug-in bundle in the Equinox console.

   osgi> install file:///<path to bundle>

   Equinox lists the bundle ID for the newly installed bundle:

   Bundle id is 17

2. Enter the following line to start the bundle in the Equinox console, where <id> is the bundle ID assigned when the bundle was installed:

   osgi>  start <id>

3. Retrieve the service status in the Equinox console to verify that the bundle started:

   osgi> ss

   When the bundle starts, the bundle lists the ACTIVE state, for example:

   17      ACTIVE      com.mycompany.plugin.bundle_xx

Eclipse Equinox and OSGI

Go through this article to get the understanding on Eclipse Equinox
http://www.theserverside.com/news/1365049/Eclipse-Equinox-and-OSGi

Loading a file from OSGI bundle

Bundle bundle = Activator.getDefault().getBundle();
Path path = new Path("path/to/your/file.extension"); //$NON-NLS-1$
URL url = FileLocator.find(bundle, path, Collections.EMPTY_MAP);
URL fileUrl = null;
try {
fileUrl = FileLocator.toFileURL(url);
}
catch (IOException e) {
// Will happen if the file cannot be read for some reason
e.printStackTrace();
}
File file = new File(fileUrl.getPath());


http://codeache.blogspot.in/2007/05/loading-files-with-rcp.html

org.osgi.framework.BundleException: State change in progress for bundle

Have you every come across this kind of issue with your eclipse plugin start () ???

!MESSAGE While loading class "org.scribe.model.Verb", thread "Thread[ModalContext,6,main]" timed out waiting (5000ms) for thread "Thread[main,6,main]" to finish starting bundle "com.xx_3.0.0.qualifier [812]". To avoid deadlock, thread "Thread[ModalContext,6,main]" is proceeding but "org.scribe.model.Verb" may not be fully initialized.
!STACK 0
org.osgi.framework.BundleException: State change in progress for bundle "reference:file:/D:/Work/KKIDE/devtools/trunk/guieditor/" by thread "main".
at org.eclipse.osgi.framework.internal.core.AbstractBundle.beginStateChange(AbstractBundle.java:1077)
at org.eclipse.osgi.framework.internal.core.AbstractBundle.start(AbstractBundle.java:282)
at org.eclipse.osgi.framework.util.SecureAction.start(SecureAction.java:417)
at org.eclipse.osgi.internal.loader.BundleLoader.setLazyTrigger(BundleLoader.java:265)
at org.eclipse.core.runtime.internal.adaptor.EclipseLazyStarter.postFindLocalClass(EclipseLazyStarter.java:106)
at org.eclipse.osgi.baseadaptor.loader.ClasspathManager.findLocalClass(ClasspathManager.java:453)
at org.eclipse.osgi.internal.baseadaptor.DefaultClassLoader.findLocalClass(DefaultClassLoader.java:216)
at org.eclipse.osgi.internal.loader.BundleLoader.findLocalClass(BundleLoader.java:393)
at org.eclipse.osgi.internal.loader.BundleLoader.findClassInternal(BundleLoader.java:469)
at org.eclipse.osgi.internal.loader.BundleLoader.findClass(BundleLoader.java:422)
at org.eclipse.osgi.internal.loader.BundleLoader.findClass(BundleLoader.java:410)
at org.eclipse.osgi.internal.baseadaptor.DefaultClassLoader.loadClass(DefaultClassLoader.java:107)
at java.lang.ClassLoader.loadClass(Unknown Source)
at org.scribe.builder.api.DefaultApi10a.getRequestTokenVerb(DefaultApi10a.java:103)
at org.scribe.oauth.OAuth10aServiceImpl.getRequestToken(OAuth10aServiceImpl.java:50)
at org.scribe.oauth.OAuth10aServiceImpl.getRequestToken(OAuth10aServiceImpl.java:39)
at org.scribe.oauth.OAuth10aServiceImpl.getRequestToken(OAuth10aServiceImpl.java:44)
at ..
at ..
org.eclipse.jface.operation.ModalContext$ModalContextThread.run(ModalContext.java:121)
Caused by: org.eclipse.osgi.framework.internal.core.AbstractBundle$BundleStatusException
... 22 more




Will try to understand the issue first, by looking at the statement below.
While loading class "org.scribe.model.Verb", thread "Thread[ModalContext,6,main]" timed out waiting (5000ms) for thread "Thread[main,6,main]" to finish starting bundle "com.xx_3.0.0.qualifier [812]". To avoid deadlock, thread "Thread[ModalContext,6,main]" is proceeding but "org.scribe.model.Verb" may not be fully initialized.


This indicates that one thread is attempting to load from the org.scribe.model. bundle while another thread is in the process of activating it.  On the Sun VM a deadlock can occur because the VM locks the classloader way too early.  I'm guessing that you are calling Display.asyncExec()/Display.syncExec in your bundle activation code.  What can happen in this case is you post a Runnable for SWT to run on the main UI dispatch thread.  Then the dispatch thread wakes up and decides to execute your runnable, this causes the UI thread to attempt to load more classes from your bundle (on the Sun VM the classloader is locked here) but the thread blocks because another thread is currently activating the bundle.  Meanwhile the thread which is activating the bundle continues to run more code which causes more classes to be loaded from your bundle, unfortunately the UI thread has a lock on the bundle classloader (now we are deadlocked).
In Equinox it detects this situation and break out of the deadlock after 5 seconds(5000ms).

One way to avoid the situation is to put all your async posts at the very end of your activation code so that you exit very quickly without loading additional classes.

It better to use aysnc execution, since bundle activation thread will return immediate and will go to active state, otherwise bundle activation thread will be blocked until your service gets over. But anyway this will vary based on call what we wanted to do it in start method.