<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="bnd-app-ctx">
    <title>Bundles and Application Contexts</title>

    <para>The unit of deployment (and modularity) in OSGi is the <emphasis>bundle</emphasis> (see
    section 3.2 of the OSGi Service Platform Core Specification). A bundle
    known to the OSGi runtime is in one of three steady states: installed,
    resolved, or active. Bundles may export services (objects) to the OSGi
    service registry, and by so doing make these services available for other
    bundles to discover and to use. Bundles may also export Java packages,
    enabling other bundles to import the exported types.</para>

    <para>In Spring the primary unit of modularity is an <emphasis>application context</emphasis>,
    which contains some number of beans (objects managed by the Spring
    application context). Application contexts can be configured in a
    hierarchy such that a child application context can see beans defined in a
    parent, but not vice-versa. The Spring concepts of exporters and factory
    beans are used to export references to beans to clients outside of the
    application context, and to inject references to services that are defined
    outside of the application context.</para>

    <para>There is a natural affinity between an OSGi bundle and a Spring
    application context. Using Gemini Blueprint, an active bundle may
    contain a Spring application context, responsible for the instantiation,
    configuration, assembly, and decoration of the objects (beans) within the
    bundle. Some of these beans may optionally be exported as OSGi services
    and thus made available to other bundles; beans within the bundle may also
    be transparently injected with references to OSGi services.</para>
    
    <para>This chapter describes the lifecycle relationship between bundles and their 
    application contexts, as imposed by Gemini Blueprint based on the events occurring at runtime,
    inside an OSGi environment.</para>

    <section id="bnd-app-ctx:extender">
      <title>The Gemini Blueprint Extender Bundle</title>

      <sidebar id="extender-pattern">
		<title>Extender Pattern</title>
		<para>A common pattern in OSGi applications is the <emphasis>extender</emphasis>, that 
		(quoting <ulink url="http://www.aqute.biz/Blog/HomePage">Peter Kriens</ulink>, 
		OSGi Technical Director), <quote>allows other bundles to extend the functionality in a specific domain</quote>.
		See <ulink url="http://www.osgi.org/blog/2007/02/osgi-extender-model.html">this</ulink> OSGi Alliance blog
		entry for an in-depth explanation.
		</para>
      </sidebar>

      <para>The component responsible for detecting the <emphasis>Spring-powered bundles</emphasis> and instantiating 
      their application context is the Gemini Blueprint <emphasis>extender</emphasis>. It serves the same purpose as the <ulink
      url="http://static.springframework.org/spring/docs/2.5.x/reference/webintegration.html">ContextLoaderListener</ulink>
      does for Spring web applications. Once the extender bundle is installed
      and started it looks for any existing Spring-powered bundles that are
      already in the <emphasis>ACTIVE</emphasis> state and creates application contexts on their
      behalf. In addition, it listens for bundle starting events and
      automatically creates an application context for any Spring-powered
      bundle that is subsequently started. <xref linkend="app-deploy:headers"/>
      describes what the extender recognizes as a "Spring-powered bundle" while 
      <xref linkend="app-deploy:extender-configuration"/> how the extender can be configured.
      The extender monitors the lifecycle of the bundle it manages and will destroy automatically the contexts for bundles
      that are stopped. When the extender bundle itself is stopped, it will automatically close all the contexts that it manages,
      based on the service dependency between them.
      The extender bundle symbolic name is <literal>org.eclipse.gemini.blueprint.extender</literal>. </para>
      
    </section>

    <section id="bnd-app-ctx:app-creation">
      <title>Application Context Creation</title>

      <para>Once started, the extender analyses the existing started bundles and monitors any new bundle that will start. Once a
      Blueprint or Gemini Blueprint configuration is detected, the extender will create an application context for it in an asynchronous manner,
      on a different thread then the one starting the bundle (or delivering the STARTED event).
      This behaviour follows the OSGi specification recommendation and ensures that starting an OSGi Service Platform is fast and that 
      bundles with service inter-dependencies do not cause deadlock (waiting for each other) on startup, as pictured below: </para>
      
      
      <para><mediaobject>
        <imageobject role="fo">
		  <imagedata fileref="../src/docbkx/resources/images/start-diagram.png" format="PNG" align="center"/>
        </imageobject>
		<imageobject role="html">
          <imagedata fileref="images/start-diagram.png" format="PNG" align="center"/>
        </imageobject>
        
          <textobject>
            <phrase>Application Context Sequence Diagram</phrase>
          </textobject>
        
      </mediaobject></para>
      
      <para>The extender considers only bundles successfully started, that is, bundles in 
      <emphasis>ACTIVE</emphasis> state; bundles in other states are ignored.    
      Therefore a Spring-powered/Blueprint bundle will have its application context created <emphasis>after</emphasis>
      it has been fully started. It is possible to force synchronous/serialized creation of application contexts 
      for started bundles, on a bundle-by-bundle basis. See <xref linkend="app-deploy:headers"/> for information 
      on how to specify this behaviour.</para>

      <para>If application context creation fails for any reason then the
      failure cause is logged. The bundle remains in the ACTIVE state; the application context lifecycle will not influence
      the bundle lifecycle in anyway. Naturally, since the context has failed, so will the functionality associated with it;
      for example there will be no services exported to the registry from the application context in this scenario.</para>
      
      <section id="bnd-app-ctx:app-creation:mandatory-deps">
        <title>Mandatory Service Dependencies</title>

        <para>If an application context declares mandatory availability for certain
        imported OSGi services, the creation of the application context is blocked 
        until all the mandatory dependencies can be satisfied through matching services 
        available in the OSGi service registry. In practice, for most enterprise applications
        built using Gemini Blueprint services, the set of available
        services and bundles will reach a steady state once the platform and
        its installed bundles are all started. In such a world, the behaviour of
        waiting for mandatory dependencies simply ensures that bundles A and
        B, where bundle A depends on services exported by bundle B, may be
        started in any order.</para>

        <para>A timeout applies to the wait for mandatory dependencies to be
        satisfied. By default the timeout is set to 5 minutes, but this value
        can be configured using the <literal>timeout</literal> directive. See
        <xref linkend="app-deploy:headers"/> for details.</para>

		<para>Blueprint users could achieve the same result through the <literal>blueprint.timeout</literal> 
		attribute declared on the <literal>Bundle-SymbolicName</literal></para>
		
        <para>It is possible to change the application context creation
        semantics so that application context creation fails if all mandatory
        services are not immediately available upon startup (see the aforementioned 
        section for more information).
        Again, note that regardless of the configuration chosen, the failure of the
        application context will not change the bundle state.</para>
        
        <para>For more information on the <emphasis>availability</emphasis> of imported services,
        see <xref linkend="service-registry:refs:availability"/></para>
      </section>

      <section id="bnd-app-ctx:app-creation:app-ctx-publication">
        <title>Application Context Service Publication</title>

        <para>Once the application context creation for a bundle has
        completed, the application context object is automatically exported as
        a service available through the OSGi Service Registry. The context is
        published under the interface
        <interfacename>org.springframework.context.ApplicationContext</interfacename> (and
        also all of the visible super-interfaces and types implemented by the
        context). The published service has a service property named
        <literal>org.springframework.context.service.name</literal> whose
        value is set to the bundle symbolic name of the bundle hosting the
        application context. In case of a Blueprint bundle, the container will be published
        under <interfacename>org.osgi.service.blueprint.container.BlueprintContainer</interfacename>
        while the bundle symbolic name will be published under <literal>osgi.blueprint.container.symbolicname</literal>
        property. 
        </para>
        <para>It is possible to prevent publication of the
        application context as a service using a directive in the bundle's
        manifest. See <xref linkend="app-deploy:headers"/> for details.</para>

        <para>Note: the application context is published as a service
        primarily to facilitate testing, administration, and management.
        Accessing this context object at runtime and invoking
        <literal>getBean()</literal> or similar operations is discouraged. The
        preferred way to access a bean defined in another application context
        is to export that bean as an OSGi service from the defining context,
        and then to import a reference to that service in the context that
        needs access to the service. Going via the service registry in this
        way ensures that a bean only sees services with compatible versions of
        service types, and that OSGi platform dynamics are respected.</para>
      </section>
    </section>

    
    <section id="bnd-app-ctx:bnd-lifecycle">
      <title>Bundle Lifecycle</title>

      <para>OSGi is a dynamic platform: bundles may be installed, started,
      updated, stopped, and uninstalled at any time during the running of the
      framework.</para>

      <para>When an active bundle is stopped, any services it exported during
      its lifetime are automatically unregistered and the bundle returns to
      the resolved state. A stopped bundle should release any resources it has
      acquired and terminate any threads. Packages exported by a stopped
      bundle continue to be available to other bundles.</para>

      <para>A bundle in the resolved state may be uninstalled: packages that
      were exported by an uninstalled bundle continue to be available to
      bundles that imported them (but not to newly installed bundles).A bundle 
      in the resolved state may also be updated. The update
      process migrates from one version of a bundle to another version of the
      same bundle.</para>

      <para>Finally of course, a resolved bundle can be started, which
      transitions it to the active state.</para>
      
      <para>The diagram below represents the bundle states and its transitions:</para>
      
      <para><mediaobject>
        <imageobject role="fo">
		  <imagedata fileref="../src/docbkx/resources/images/bundle-states.png" format="PNG" align="center"/>
        </imageobject>
		<imageobject role="html">
          <imagedata fileref="images/bundle-states.png" format="PNG" align="center"/>
        </imageobject>
        
          <textobject>
            <phrase>Bundle States</phrase>
          </textobject>
        
      </mediaobject></para>
      

      <para>The OSGi <literal>PackageAdmin</literal>
      <literal>refreshPackages</literal> operation refreshes packages across
      the whole OSGi framework or a given subset of installed bundles. During
      the refresh, an application context in an affected bundle will be
      stopped and restarted. After a <literal>refreshPackages</literal>
      operation, packages exported by older versions of updated bundles, or
      packages exported by uninstalled bundles, are no longer available.
      Consult the OSGi specifications for full details.</para>

      <para>When a Spring-powered or Blueprint bundle is stopped, the application context
      created for it is automatically destroyed. All services exported by the
      bundle will be unregistered (removed from the service registry) and the
      normal application context tear-down life-cycle is observed
      (<interfacename>org.springframework.beans.factory.DisposableBean</interfacename> implementors 
      and <literal>destroy-method</literal>
      callbacks are invoked on beans in the context).</para>

      <para>If a Spring-powered bundle that has been stopped is subsequently
      re-started, a new application context will be created for it.</para>
    </section>

    <section id="bnd-app-ctx:osgi-resource">
      <title>The Resource Abstraction</title>

      <para>The Spring Framework defines a resource abstraction for loading
      resources within an application context (see <ulink
      url="http://static.springframework.org/spring/docs/2.5.x/reference/resources.html">Spring's
      resource abstraction</ulink>). All resource loading is done through the
      <interfacename>org.springframework.core.io.ResourceLoader</interfacename> associated with the application
      context. The <interfacename>org.springframework.core.io.ResourceLoader</interfacename> is also 
      available to beans wishing to load resources programmatically. Resource paths with
      explicit prefixes - such as <literal>classpath:</literal> - are treated uniformly
      across all application context types (for example, web application
      contexts and classpath-based application contexts). Relative resource
      paths are interpreted differently based on the type of application
      context being created. This enables easy integration testing outside
      the ultimate deployment environment.</para>

	  <para>OSGi 4.0.x specification defines three different spaces from which a
	  resource can be loaded. Gemini Blueprint supports all of them through its dedicated OSGi-specific
	  application context and dedicated prefixes:</para>
	  
	  <table id="osgi-search-strategies" pgwide="1">
          <title>OSGi resource search strategies</title>
          <tgroup cols="3">
            <thead>
              <row>
                <entry>OSGi Search Strategy</entry>
                <entry>Prefix</entry>
                <entry>Explanation</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>Class Space</entry>
                <entry><literal>classpath:</literal></entry>
                <entry>Searches the bundle classloader (the bundle, all imported packages and required bundles). Forces the bundle to be resolved.
                This method has similar semantics to 
                <ulink url="http://www2.osgi.org/javadoc/r4/org/osgi/framework/Bundle.html#getResource(java.lang.String)"><literal>Bundle#getResource(String)</literal></ulink></entry>
              </row>
              
              <row>
                <entry>Class Space</entry>
                <entry><literal>classpath*:</literal></entry>
                <entry>Searches the bundle classloader (the bundle and all imported packages and required bundles). Forces the bundle to be resolved.
                This method has similar semantics to 
                <ulink url="http://www2.osgi.org/javadoc/r4/org/osgi/framework/Bundle.html#getResources(java.lang.String)"><literal>Bundle#getResources(String)</literal></ulink>
                </entry>
              </row>
              
              <row>
                <entry>JAR File (or JarSpace)</entry>
                <entry><literal>osgibundlejar:</literal></entry>
                <entry>Searches only the bundle jar. Provides low-level access without requiring the bundle to be resolved.</entry>
              </row>
              <row>
                <entry>Bundle Space</entry>
                <entry><literal>osgibundle:</literal></entry>
                <entry>Searches the bundle jar and its attached fragments (if there are any). Does not create a class loader or force the bundle to be resolved.</entry>
              </row>
            </tbody>
          </tgroup>
      </table>

	  <para>Please consult section 4.3.12 of the OSGi specification for an in depth explanation of the differences between them.
	  </para>
	  
	  <note>If no prefix is specified, the bundle space (<literal>osgibundle:</literal>) will be used.</note>
	  
	  <note>Due to the OSGi dynamic nature, a bundle classpath can change during its life time (for example when dynamic imports are used). This might cause different
	  classpath <interfacename>Resource</interfacename>s to be returned when doing pattern matching based on the running environment or target platform.</note>
	  
      <para>All of the regular Spring resource prefixes such as <literal>file:</literal> and
      <literal>http:</literal> are also supported, as are the pattern matching wildcards.
      Resources loaded using such prefixes may come from any location, they
      are not restricted to being defined within the resource-loading bundle
      or its attached fragments.</para>

      <para>OSGi platforms may define their own unique prefixes for accessing
      bundle contents. For example, Equinox defines the <literal>bundleresource:</literal> and
      <literal>bundlentry:</literal> prefixes. These platform specific prefixes may also be
      used with Gemini Blueprint, at the cost, of course, of tying yourself to a
      particular OSGi implementation.</para>
    </section>

    <section id="bnd-app-ctx:bundle-scope">
      <title>Bundle Scope</title>
      
      <para>Gemini Blueprint introduces a new bean scope named <literal>bundle</literal>. This scope is relevant for
      beans exported as an OSGi service and can be described as <emphasis>one instance per bundle</emphasis>. 
      Beans exported as OSGi service, that have <literal>bundle</literal> scope, will result in a different instance created for 
      each unique bundle that imports the service through the OSGi service registry. Consumers of the same bundle (whether defined
      through Gemini Blueprint or not) will see the same bean instance. When a bundle has stopped importing the bundle (for whatever reason),
      the bean instance is disposed.
	  To the declaring bundle, a <literal>bundle</literal>-scoped bean behaves just like a singleton (i.e. there is only
	  one instance per bundle, including the declaring one).This contract lifecycle is similar to that of the 
	  <interfacename>org.osgi.framework.ServiceFactory</interfacename> interface.</para>
	  <para>For more information regarding service publication and consumption, see <xref linkend="service-registry"/>.</para>
	  
	  <important>The bundle scope is relevant, only if the declaring bean is consumed through the OSGi service registry. That is,
	  instances are created and destroyed (tracked) only when the bean exported as a service, is requested or released as an OSGi service
	  by other bundles.</important>
	</section>
	
    <section id="bnd-app-ctx:access-bnd-ctx">
      <title>Accessing the BundleContext</title>

      <para>In general there is no need to depend on any OSGi APIs when using
      the Gemini Blueprint support. If you <emphasis>do</emphasis> need
      access to the OSGi <interfacename>BundleContext</interfacename> object for your
      bundle, then Spring makes this easy to do.</para>

      <para>The OSGi application context created by the Spring extender will
      automatically contain a bean of type <interfacename>BundleContext</interfacename>
      and with name <literal>bundleContext</literal>. You can inject a
      reference to this bean into any bean in the application context either
      by-name or by-type. In addition, Gemini Blueprint defines the
      interface
      <interfacename>org.eclipse.gemini.blueprint.context.BundleContextAware</interfacename>:</para>

      <programlisting language="java">public interface BundleContextAware {
  public void setBundleContext(BundleContext context);
}</programlisting>
	
      <para>Any bean implementing this interface will be injected with a
      reference to the bundle context when it is configured by Spring. If you
      wish to use this facility within a bundle, remember to import the
      package <literal>org.eclipse.gemini.blueprint.context</literal> in your
      bundle manifest since otherwise the interface will not be visible to your bundle.</para>
	</section>

    <section id="bnd-app-ctx:app-destruction">
      <title>Application Context Destruction</title>
      
      <para>The application context is bound to the bundle in which it lives. Thus, if the declaring 
      bundle is being shutdown (for whatever reasons), the application context will be destroyed as well,
      all exported services being unregistered and all service imported dispose of.
      </para>
      
      <para>As opposed to the application creation, the application context is destroyed in a synchronized manner,
      on the same thread that stops the bundle. This is required since once stopped, a bundle can not longer be used
      (even for class loading) preventing the application context shutdown from executing correctly.
      </para>
      
      <para><mediaobject>
        <imageobject role="fo">
		  <imagedata fileref="../src/docbkx/resources/images/stop-diagram.png" format="PNG" align="center"/>
        </imageobject>
		<imageobject role="html">
          <imagedata fileref="images/stop-diagram.png" format="PNG" align="center"/>
        </imageobject>
        
          <textobject>
            <phrase>Application Context Sequence Diagram</phrase>
          </textobject>
        
      </mediaobject></para>
      
      
      <para>Note that a bundle can be closed individually or as part of a bigger
      event such as shutting down the entire OSGi platform. In this case or when the extender
      bundle is being closed down, the application contexts will be closed in a managed
      manner, based on the service dependencies between them. Please see the next section for more
      details.</para>
    </section>
    
    <section id="bnd-app-ctx:access-bnd-ctx:stop-extender">
      <title>Stopping the Extender Bundle</title>

      <sidebar id="shutdown-2.x">
		<title>Shutdown algorithm change in 2.x</title>
		<para>The shutdown algorithm implementation in Gemini Blueprint 1.0 has been revised to be better
		aligned with the Blueprint Container spec. Namely, the previous implementation performed ordering
		in only one pass while the latter performs multiple steps to accommodate the service changes in
		the OSGi space. Users should not discover any differences at runtime however, if that's not the case,
		please let us know.
		</para>
      </sidebar>

      <para>If the extender bundle is stopped, then all the application
      contexts created by the extender will be destroyed. The algorithm described here is identical
      to that used by the Blueprint specification (section 121.3.11). Application contexts
      are shutdown in the following order:</para>

      <orderedlist>
        <listitem id="bnd-app-ctx:access-bnd-ctx:stop-extender:shutdown.step.1">
          <para>Application contexts that do not export any services, or that
          export services that are not currently referenced, are shutdown in
          reverse order of bundle id. (Most recently installed bundles have
          their application contexts shutdown first).</para>
        </listitem>

        <listitem>
          <para>Shutting down the application contexts in step 1 may have
          released references these contexts were holding such that there are
          now additional application contexts that can be shutdown. If so,
          repeat <link linkend="bnd-app-ctx:access-bnd-ctx:stop-extender:shutdown.step.1">step 1</link> again.</para>
        </listitem>

        <listitem>
          <para>If there are no more active application contexts, we have
          finished. If there <emphasis>are</emphasis> active application
          contexts then there must be a cyclic dependency of references. The
          circle is broken by determining the highest ranking service exported
          by each context: the bundle with the lowest ranking service in this
          set (or in the event of a tie, the highest service id), is shut
          down. Repeat from <link linkend="bnd-app-ctx:access-bnd-ctx:stop-extender:shutdown.step.1">step 1</link>.</para>
        </listitem>
      </orderedlist>
    </section>
</chapter>