PART 5. SUPPLEMENTARY DOCUMENTATION
ESF Startup Process

 

ESF Startup Process

·            Core Components

·            ESF Startup Mechanisms

·            config.ini structure

·            services.xml and the bootstrap service

·            Bootstrap Service API

ESF Startup Process

 

Core Components

ESF is powered by Equinox.  Before ESF components can start, the base Equinox runtime must start.  It can start in one of two ways.  For development purposes, an ESF start script called /opt/jvm/esf/start_equinox.sh invokes the JVM with the core Equinox OSGi bundle.  However, once a unit is deployed in the field it is most likely going to auto start.  To auto start, there is a script called /opt/jvm/esf/auto_start.sh script.  It is meant to be tied to the Wind River Linux (WRL) init process to auto start when the OS boots.

 

Once the core OSGi runtime is going, it looks by default in a file called /opt/jvm/esf/configuration/config.ini to bootstrap the runtime.  Typically, there is a small number of bundles in this list, but there is no technical reason that config.ini can’t be used to start up all bundles in the system.  However, we added an ESF Bootstrap layer on top of this to add some additional control to how bundles are started.

 

The ESF bootstrap service uses another file called /opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/services.xml to get the list of all ESF components to start.  It is an XML file that allows for specifying the ESF log level for each bundle to start at.  The ESF logger allows granular control of each bundle.  This is one of the ways that log level can be set.

 

There are two final layers of bundle loading that are automated in ESF.  After the ESF bootstrap service starts all of the bundles in the services.xml file, it will search the directory /opt/jvm/esf/dropins/ for any bundles present.  If there are bundles present and not already loaded, the bootstrap service will load them.  The last layer is identical to the dropins mechanism except that the directory it searches is called /opt/jvm/esf/junit_bundlefiles/.  If there are bundles here, they will be loaded automatically and started.  This layer of bundle loading is really designed for putting test case code into so it can be easily removed before deployment.

 

ESF Startup Mechanisms

ESF provides two default startup scripts.  One is manually run, while the other is a reference script to start and maintain ESF running.  The following is the manual script (/opt/jvm/esf/start_equinox.sh).

 

########################################################################

#!/bin/sh

 

export PATH=$PATH:/opt/jvm/bin

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/jvm/bin

 

j9 -Dorg.eclipse.soda.sat.core.util.logLevel=WARNING \

                -Declipse.ignoreApp=true \

                -jar org.eclipse.osgi_3.4.0.v20080605-1900.jar \

                -console -clean

########################################################################

 

The PATH and LD_LIBRARY_PATH environment variables need to be changed to tell the OS where the JRE binary runtime components and shared object libraries can be found.

 

The j9 command like argument looks a bit intimidating but is rather simple.  The -Dorg.eclipse.soda.sat.core.util.logLevel=WARNING specifies the log level of the Service Activator Toolkit (SAT) logger.  This logger is used by the bootstrap services itself.  Because the bootstrap service runs before the ESF logger service, it could not be dependent on it (circular dependency).  So, the boostrap service itself uses the SAT logger.  If you are having trouble with the bootstrap service, it can be helpful to turn this log level up to INFO or DEBUG.

 

The –Declipse.ignoreApp=true argument tells Equinox that it will not be running Eclipse, which is how it is configured by default.  Instead, Equinox will be running in standalone mode.

 

The –jar org.eclipse.osgi_3.4.0.v20080605-1900.jar argument specifies the jar to start with the VM.  This is the same as you would start a JVM with any standalone jar file.

 

The –console and –clean arguments tell Equinox to run in console mode and to not use the old runtime metadata.  Equinox saves a notion of state from run to run.  The –clean argument forces the old state information to not be used.

 

The /opt/jvm/esf/auto_start.sh script is a bit more complex.  The basic idea is to start Equinox and to restart it in the event of a crash.  This example is purely for reference and likely needs to be modified on a project by project basis.  For example, some filesystem components and/or process might need to be cleaned up in the event of a VM crash.  Those project specific issues need to be dealt with here.

 

There is a significant change in the auto_start.sh script to the j9 command line.  The following is the auto_start.sh script.

 

########################################################################

        j9 -Dorg.eclipse.soda.sat.core.util.logLevel=WARNING \

                -Declipse.ignoreApp=true \

                -jar org.eclipse.osgi_3.4.0.v20080605-1900.jar \

                -console 5002 –clean \

                >> /tmp/equinox.log 2>> /tmp/equinox.log &

########################################################################

 

Notice the ‘-console 5002’ rather than ‘-console’.  This difference causes the console to come out on a TCP socket rather than the local console.  So, you can connect to port 5002 using telnet or netcat.  The other change is the stdout and stderr are redirected to a /tmp/equinox.log so they are captured.

 

config.ini structure

With Equinox now started via the startup script, we can look at config.ini.  The following is an example config.ini file.

 

########################################################################

osgi.bundles=bundlefiles/javax.servlet.jsp_2.0.0.v200806031607.jar@2:start, \

        bundlefiles/javax.servlet_2.4.0.v200806031604.jar@2:start, \

        bundlefiles/org.apache.felix.ipojo-1.2.0.jar@2:start, \

        bundlefiles/org.apache.felix.ipojo.arch.equinox-1.0.0.jar@2:start, \

        bundlefiles/org.apache.felix.ipojo.handler.extender-1.2.0.jar@2:start, \

        bundlefiles/org.apache.felix.ipojo.junit4osgi-1.0.0.jar@2:start, \

        bundlefiles/org.apache.felix.ipojo.junit4osgi.equinox-command-1.1.0-SNAPSHOT.jar@2:start, \

        bundlefiles/org.eclipse.equinox.cm_1.0.0.v20080509-1800.jar@2:start, \

        bundlefiles/org.eclipse.equinox.common_3.4.0.v20080421-2006.jar@2:start, \

        bundlefiles/org.eclipse.equinox.ds_1.0.0.v20080427-0830.jar@2:start, \

        bundlefiles/org.eclipse.equinox.event_1.1.0.v20080225.jar@2:start, \

        bundlefiles/org.eclipse.equinox.http.registry_1.0.100.v20080427-0830.jar@2:start, \

        bundlefiles/org.eclipse.equinox.http.servlet_1.0.100.v20080427-0830.jar@2:start, \

        bundlefiles/org.eclipse.equinox.http_1.0.200.v20080421-2006.jar@2:start, \

        bundlefiles/org.eclipse.equinox.preferences_3.2.200.v20080421-2006.jar@2:start, \

        bundlefiles/org.eclipse.equinox.registry_3.4.0.v20080516-0950.jar@2:start, \

        bundlefiles/org.eclipse.equinox.util_1.0.0.v20080414.jar@2:start, \

        bundlefiles/org.eclipse.osgi.services_3.1.200.v20071203.jar@2:start, \

        bundlefiles/org.eclipse.osgi.util_3.1.300.v20080303.jar@2:start, \

        bundlefiles/org.eclipse.soda.sat.core_1.1.0.200803122135.jar@2:start, \

        bundlefiles/org.soda.stepstone.core_1.0.0.200705211340.jar@2:start, \

        bundlefiles/com.esf.core.system.bootstrap.service@2:start, \

        bundlefiles/com.esf.core.system.bootstrap@2:start

########################################################################

 

This config.ini simply starts some core bundles.  In this case, it is the default Helios ESF Base config.ini.  It starts everything in the target platform definition and the bootstrap service.  The bootstrap service then takes over by loading the services.xml files.

 

The config.ini can also be used to pass additional configuration arguments to OSGi components.  For example, the following can be added to the config.ini to change the default port that the OSGi HTTP service runs on.

 

org.osgi.service.http.port=8080

 

It is the same as adding the following to the start_equinox.sh j9 command line string.

 

-Dorg.osgi.service.http.port=8080

 

services.xml and the bootstrap service

The services.xml and bootstrap service are fairly straight forward.  The following is an example services.xml file that starts two bundles.

 

<services>

  <bundle>

    <name>com.esf.core.system.manager.service</name>

    <log_level>LOG_LEVEL_WARNING</log_level>

  </bundle>

  <bundle>

    <name>com.esf.core.system.manager</name>

    <log_level>LOG_LEVEL_WARNING</log_level>

  </bundle>

</services>

 

The name of the bundles to start must be their symbolic bundle names.  The following log levels are shown from least verbose to most verbose.

 

LOG_LEVEL_ERROR

LOG_LEVEL_WARNING

LOG_LEVEL_INFO

LOG_LEVEL_DEBUG

LOG_LEVEL_DUMP

 

All bundles that are listed in services.xml and exist in the /opt/jvm/esf/bundlefiles directory are loaded and started at the specified log level.  If the bundle cannot be found in the bundlefiles directory, an error will be displayed.

 

The following are also two special directories that are used to autoload bundles.

 

/opt/jvm/esf/dropins/

/opt/jvm/esf/junit_bundlefiles/

 

The bundles placed in these directories are loaded without any reference to them in services.xml.  The order of loading is as follows.

 

·            services.xml bundles

·            dropins bundles

·            junit_bundlefiles bundles

 

The service.xml is meant to be used for deployed systems and stable bundles.  The dropins directory is there for development and quick addition on new bundles to the system.  It prevents the need of editing services.xml to get your bundle to load.  The junit_bundlefiles directory is there to place test bundles into so they can easily be removed for deployment.  There is no technical difference between the dropins directory and the junit_bundlefiles directory other than the order in which bundles are loaded.

 

It is also important to note which bundles will be loaded based on each of these mechanisms.  In services.xml if the symbolic name is specified for the name (i.e. com.esf.core.system.manager.service), the newest revision of that bundle in the bundlefiles directory will be loaded.

 

For example, let’s say there are two versions of the bundle in the bundlefiles directory.

 

com.esf.core.system.manager.service_201007210800.jar

com.esf.core.system.manager.service_201007210900.jar

 

Note that the second bundle is an hour newer than the first.  The newer bundle will be loaded by the bootstrap service, and a warning will be displayed denoting the two versions found and stating which version was loaded.  To extend the example, let’s say that we had the following third revision of the same bundle in the dropins directory.

 

com.esf.core.system.manager.service_201007211000.jar

 

This bundle is an hour newer than what was loaded via the services.xml file.  However, because the services.xml bundle in the bundlefiles directory has already been loaded this newer one in the dropins directory will not be loaded.  An error will be displayed to note the bundle in the dropins directory could not be loaded.  So, you should not ‘mix’ loading mechanisms.  If you are loading a bundle via services.xml you should only load it that way.  Also, if loading via dropins you should only load it that way.  If loading via the dropins for development, once the bundle becomes stable you can then switch to using the service.xml mechanism.

 

Bootstrap Service API

After all of the bundles in the three bundlefiles directory are loaded, the bootstrap service sits idle and can provide information about what happened during the startup to other bundles via its service API.  See the ESF API Documentation for additional information.