| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" |
| "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> |
| <book xmlns:xi="http://www.w3.org/2001/XInclude"> |
| <bookinfo> |
| <title>Eclipse Gemini Blueprint</title> |
| |
| <subtitle>Frequently Asked Questions</subtitle> |
| <releaseinfo>&version;</releaseinfo> |
| |
| <authorgroup> |
| <author> |
| <firstname>Costin</firstname> |
| <surname>Leau</surname> |
| <affiliation>SpringSource</affiliation> |
| </author> |
| </authorgroup> |
| |
| <legalnotice> |
| <para>Documentation made available under the terms of the Eclipse Public License v1.0 |
| and Apache License v2.0 which accompanies this distribution. |
| The Eclipse Public License is available at <ulink url="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</ulink> and |
| the Apache License v2.0 is available at <ulink url="http://www.opensource.org/licenses/apache2.0.php">http://www.opensource.org/licenses/apache2.0.php</ulink>. |
| You may elect to redistribute this code under either of these licenses.</para> |
| </legalnotice> |
| |
| <copyright> |
| <year>2006 -</year> |
| <year>2011</year> |
| <holder>VMware Inc.</holder> |
| <holder>Oracle Inc.</holder> |
| </copyright> |
| |
| </bookinfo> |
| |
| <toc /> |
| |
| <chapter id="spring-osgi-faq"> |
| <title>Frequently Asked Questions</title> |
| |
| <section id="eclipse-springdm"> |
| <title>What's the relationship between Spring Dynamic Modules and Gemini Blueprint?</title> |
| |
| <para>Eclipse Gemini Blueprint is based on Spring Dynamic Modules 2.0 which has been migrated |
| to the Eclipse Foundation. While the name and the packages have changed the internals are still the same; one |
| will find both names are used interchangeably (especially by those that have used Spring DM for a while). |
| Further more, all Spring DM applications are supported by Gemini Blueprint (do pay attention to the migration guide available |
| <ulink url="http://www.eclipse.org/gemini/blueprint/documentation/migration/">here</ulink>).</para> |
| </section> |
| |
| <section id="name-change"> |
| <title>What happened to "Spring OSGi" project name?</title> |
| |
| <para>The OSGi term is a trademark belonging to <ulink |
| url="http://www.osgi.org/">The OSGi Alliance</ulink>. In order to |
| comply with their guidelines, it was decided that the project name |
| be changed to "Spring Dynamic Modules for OSGi Service Platforms" |
| (aka Spring DM). The new name is still pending final approval |
| by the OSGi Alliance. |
| The name change was the result of an amicable discussion between |
| the OSGi Alliance and Interface21. Interface21 is a member of the |
| OSGi Alliance, and the OSGi Alliance remain very supportive of |
| the project. |
| Note that Spring Dynamic Modules has moved to Eclipse Foundation to form Gemini Blueprint project (see above)</para> |
| </section> |
| |
| <section id="internal-package"> |
| <title>Why aren't there any javadocs on <literal>*.internal.*</literal>?</title> |
| |
| <para><literal>org.eclipse.gemini.blueprint.*.internal</literal> packages are |
| meant (as the name implies) to be private and non-public package. Thus, |
| there is no documentation, support or compatibility guarantee for |
| them. In fact, the Gemini Blueprint bundle does not even export |
| them to prevent accidental usage.</para> |
| |
| <para>If you find classes under this package, which you really, really |
| depend on, then consider raising an issue on <ulink type="" |
| url="http://opensource.atlassian.com/projects/spring/browse/OSGI">JIRA</ulink> |
| to have access opened up.</para> |
| </section> |
| |
| <section id="requirements"> |
| <title>What are Gemini Blueprint requirements?</title> |
| <para> |
| Gemini Blueprint requires at least Java 1.5, OSGi 4.1 and Spring 3.0. |
| It might be possible to use Gemini Blueprint on a lower <ulink |
| url="http://wiki.eclipse.org/index.php/Execution_Environments">execution environment</ulink> |
| (such <ulink url="http://java.sun.com/products/cdc/">CDC</ulink>) but |
| it is not guaranteed to work. |
| Both Spring and Gemini Blueprint rely on <ulink url="http://java.sun.com/products/javabeans/"> |
| JavaBeans</ulink> (java.beans package) which, unfortunately, is missing in most |
| restricted environments. See this <ulink url="http://java.sun.com/products/cdc/reference/cdc_packages.pdf" |
| type="application/pdf">PDF</ulink> for information on CDC profiles. |
| Note that, Spring 3.0 also requires Java 1.5. For Spring 2.5 and/or Java 1.4 see |
| <ulink url="http://www.springframework.org/osgi">Spring Dynamic Modules</ulink> 1.x releases. |
| </para> |
| <para> |
| Nevertheless, experiences and feedback on running Gemini Blueprint in restricted environments |
| is welcomed - please use our mailing list. |
| </para> |
| </section> |
| |
| <section id="other-module-frameworks"> |
| <title>Are there plans to support other dynamic module frameworks (such as the JSR 277 extensions in Java 7)?</title> |
| <para>There are no current plans to support other dynamic module frameworks.</para> |
| </section> |
| |
| <section id="restricted-environments"> |
| <title>Will Gemini Blueprint work in restricted environments (such as small/mobile devices)?</title> |
| <para>See the <link linkend="requirements">requirements</link> entry. The OSGi Service Platform is designed to run in |
| very constrained environments however, Gemini Blueprint depends on the Spring Framework v3.0 which in turn depends on |
| JDK 1.5. Thus Gemini Blueprint cannot run on more constrained environments (such as the OSGi Minimum Execution Environment) |
| unless Spring itself also runs in those environments. There are no current plans to make such a version of Spring. |
| However as existing OSGi developers adopt Gemini Blueprint to simplify creation of OSGi applications and the user |
| base expands, the target audience can cover domains much broader than <emphasis>enterprise Java applications</emphasis>. |
| In time this could create a large enough demand to justify the investment needed to allow Spring and Gemini Blueprint to run in |
| restricted environments.</para> |
| </section> |
| |
| |
| |
| <section id="supported-osgi-platforms"> |
| <title>What OSGi platforms are supported?</title> |
| <para> |
| Gemini Blueprint requires an OSGi 4.2 (though it might work on OSGi 4.0 and 4.1) platform. The framework has been tested |
| on <ulink url="http://www.eclipse.org/equinox/">Equinox</ulink>, <ulink url="http://felix.apache.org">Felix</ulink> |
| and <ulink url="http://www.knopflerfish.org/">Knopflerfish</ulink> |
| - in fact, the test suite is <ulink url="http://build.springframework.org:8085/bamboo/browse/OSGI">ran</ulink> |
| against all of them as part of our continuous integration process. |
| </para> |
| </section> |
| |
| |
| <section id="osgi-intro"> |
| <title>Where can I learn about OSGi?</title> |
| <para> |
| The best place to start is The Osgi Alliance <ulink url="http://www.osgi.org/">home</ulink> and |
| <ulink url="http://www2.osgi.org/Main/HomePage">developer</ulink> pages which |
| provide the OSGi specifications, introductions and many links and blogs on the topic. |
| Please see the reference documentation appendix for more information. |
| </para> |
| |
| <para> |
| In addition, all OSGi implementation websites host detailed, step-by-step tutorials and introduction. |
| </para> |
| |
| <para> |
| If you discover any additional materials useful for OSGi newbies, please let us know to update the list. |
| Thank you. |
| </para> |
| </section> |
| |
| <section id="building-the-sources"> |
| <title>I have problems building the sources. What can I do?</title> |
| <para>Please see the file called <literal>readme-building.txt</literal> found in the source tree. |
| </para> |
| </section> |
| <!-- |
| <section id="backport-util-concurrent"> |
| <title>I get an exception about backport-util-concurrent library being required. Why is that?</title> |
| |
| <para>This exception is thrown only when running on Java 1.4 |
| without backport-util-concurrent bundle installed. |
| </para> |
| <para> |
| OSGi platform is a concurrent environment. Beans from different |
| application contexts can interact with each other creating cycles |
| between their owning contexts. This means that the backing |
| contexts have to be able to lookup and create/retrieve bean instances, |
| all at the same time, on multiple threads. A traditional synchronised |
| collection allows proper locking and thread coordination and prevents |
| race conditions, but can cause very easily deadlocks.</para> |
| |
| <para>Consider two contexts each containing two beans: <mediaobject> |
| <imageobject role="fo"> |
| <imagedata align="center" |
| fileref="src/docbkx/resources/images/deadlock.png" |
| format="PNG"/> |
| </imageobject> |
| |
| <imageobject role="html"> |
| <imagedata align="center" fileref="images/deadlock.png" |
| format="PNG"/> |
| </imageobject> |
| |
| <caption> |
| <para>Inter-application context bean interaction</para> |
| </caption> |
| </mediaobject></para> |
| |
| <para>If both bean A and C are requested by two separate threads at |
| the same time, this scenario will deadlock since each thread waits for |
| the other one to release the "bean registry" lock even just for |
| reading. However, when using a concurrent collection, reading doesn't |
| require a lock so each thread can interact with the other context |
| without waiting for a lock. Java 1.5 and upwards provide <ulink |
| url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/package-summary.html">concurrent |
| collections</ulink> under <literal>java.util</literal> package. |
| However, since Java 1.4 does not, <ulink |
| url="http://dcl.mathcs.emory.edu/util/backport-util-concurrent/">backport-util-concurrent</ulink> |
| library is required.</para> |
| </section> |
| --> |
| |
| |
| <section id="logging"> |
| <title>How can I use logging in OSGi?</title> |
| |
| <para>OSGi platforms do not change the way libraries work, it just |
| enforces tighter classloading. Thus, you can, in most of the cases, |
| use the same logging strategy used in non-OSGi environments.</para> |
| |
| <para>Spring (and Gemini Blueprint) use internally the <ulink |
| url="http://commons.apache.org/logging/">commons-logging API</ulink> |
| which acts as an "ultra-thin bridge between different logging |
| implementations". In OSGi, just like in a non-OSGi environment, Spring |
| and Gemini Blueprint delegate all logging (including initialisation) to the |
| actual commons-logging API implementation.</para> |
| |
| <para>Out of the box, <ulink url="http://www.slf4j.org/">SLF4J</ulink> library is provided, which |
| shares the same purpose as commons-logging but without the |
| class loading discovery mechanism (that causes loading issues), using |
| static wiring (see the SLF4J site for more info). To use slf4j, make sure |
| you use: <literal>slf4j-api-XXX.jar</literal>, <literal>jcl104-overslf4j-XXX.jar</literal> |
| and <literal>slf4j-log4j-XXX.jar</literal> (where XXX stands for the slf4j version). |
| The last jar provides the static wiring between slf4j and log4j - if another implementation |
| is desired (such as jdk14), then a different jar is required (for the jdk14 that would be |
| slf4j-jdk14-XXX.jar) - see the official SLF4J site for more information. |
| Please see <link linkend="commons-logging">this |
| question</link > for more details on why commons-logging jar is not |
| used.</para> |
| |
| <para>Gemini Blueprint uses SLF4J on top of <ulink |
| url="http://logging.apache.org/log4j/">Log4J</ulink> but this can be |
| easily changed. As part of log4j initialisation, a |
| <literal>log4j.properties</literal> or <literal>log4j.xml</literal> |
| configuration fille needs to be present in the bundle classpath. This |
| means that the configuration file has to be part of your bundle or one |
| of its attached fragments. Besides SLF4J, for another OSGi-aware |
| solution, one can try <ulink |
| url="http://wiki.ops4j.org/dokuwiki/doku.php?id=pax:logging">Pax |
| Logging</ulink>.</para> |
| |
| <para>To learn more about log4j setup process, follow this <ulink |
| type="" |
| url="http://logging.apache.org/log4j/1.2/manual.html">link</ulink>.</para> |
| </section> |
| |
| <section id="commons-logging"> |
| <title>If you use the commons-logging API, why rely on SLF4J and |
| not the commons-logging jar?</title> |
| |
| <para>The commons-logging project provides the commons-logging API |
| (<literal>commons-logging-api-nn.jar</literal>) along with an |
| implementation (<literal>commons-logging-adapters-nn.jar</literal>) |
| that provides a wrapper between the API and the actual logging libraries |
| used underneath (such as log4j, java.util.logging, etc). However, in |
| order to determine what implementation should be used, commons-logging |
| library tries to do some classloading-based discovery that is fragile |
| and can fail unexpectedly. In an strict classloading environment such |
| as OSGi, this mechanism adds unnecessary complexity - that's why we |
| decided to use SFL4J which is not just simpler and actively maintained |
| but is also OSGi-friendly out of the box.</para> |
| |
| <para>For more information about commons-logging classloading |
| problems, see these links: <ulink |
| url="http://radio.weblogs.com/0122027/2003/08/15.html">#1</ulink> |
| <ulink |
| url="http://www.qos.ch/logging/thinkAgain.jsp">#2</ulink></para> |
| </section> |
| |
| <section id="getting-commons-logging-to-work"> |
| <title>I have to use commons-logging, what can I do?</title> |
| |
| <para>If you have to use commons-logging (for example the jar is required by certain bundles) |
| then try using the most recent version commons-logging version (1.1+) as it provides more options |
| on the discovery process. Below are some settings that can be used to make commons-logging work |
| inside an OSGi environment:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>1.0.x</para> |
| <para> |
| Unfortunately, commons-logging 1.0.x uses the thread context class loader (TCCL) always for <ulink |
| url="http://commons.apache.org/logging/commons-logging-1.1/tech.html#A_Short_Theory_Guide_To_JCL">loading |
| loggers</ulink> implementations. Inside an OSGi environment, the TCCL is undefined and cannot be relied upon. |
| Since managing the TCCL is almost impossible as most loggers are defined as static fields that need to |
| resolved on class loading, using a different <classname>LogFactory</classname> is advised. One can use |
| the <emphasis>org.apache.commons.logging.LogFactory</emphasis> system property to specify a different |
| log factory however, the commons-logging bundle should be able to load this class.</para> |
| </listitem> |
| <listitem> |
| <para>1.1.x</para> |
| <para>If using commons logging 1.1.x, one can turn off the tccl usage through <emphasis>use_tccl</emphasis> |
| property, part of the <emphasis>commons-logging.properties</emphasis> file. |
| <ulink url="http://commons.apache.org/logging/commons-logging-1.1/troubleshooting.html"/>. Additionally, |
| 1.1.x provides several system properties (such as <emphasis>org.apache.commons.logging.Log.allowFlawedContext</emphasis>, |
| <emphasis>org.apache.commons.logging.Log.allowFlawedDiscovery</emphasis> and |
| <emphasis>org.apache.commons.logging.Log.allowFlawedHierarchy</emphasis>) that can change the behavious of the discovery process. |
| See the <ulink url="http://commons.apache.org/logging/apidocs/org/apache/commons/logging/impl/LogFactoryImpl.html">LogFactoryImpl</ulink> |
| javadoc for more details.</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>In our tests, commons logging 1.1.x can be used with reasonable success inside OSGi. We haven't been able to find a generic |
| configuration for commons logging 1.0.x that works and that does not rely on fragile hacks dependent on the running environment.</para> |
| |
| </section> |
| |
| <section id="logging-impl-choice"> |
| <title>Why don't you use the OSGi logging service/[insert your favourite |
| logging library in here]?</title> |
| |
| <para>It is completely up to you what logging implementation you want |
| Gemini Blueprint to use. To route log messages to the OSGi logging service, |
| just use a commons-logging API implementation that delegates to the |
| OSGi logging service, such as Pax Logging.</para> |
| </section> |
| |
| |
| <section id="osgi-wrapping"> |
| <title>I have to use [insert name] library/framework inside. What can I do?</title> |
| |
| <para> |
| OSGi requires JARs to contain certain <literal>MANIFEST.MF</literal> entries which indicate what classes are |
| required and shared by each archive. This means that <emphasis>tradition</emphasis> jars cannot be used inside an OSGi environment. |
| To solve the problem one can: |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para>Use a repository of pre-wrapped libraries such as <ulink url="http://www.eclipse.org/orbit/">Orbit</ulink>, |
| <ulink url="http://felix.apache.org/site/apache-felix-commons.html">Felix Commons</ulink> or Knopflerfish <ulink |
| url="http://www.knopflerfish.org/repo/index.html">repository</ulink>. |
| Gemini Blueprint uses the SpringSource Enterprise <ulink url="http://www.springsource.com/repository/app/">Bundle Repository</ulink> |
| for its dependencies, which you might find useful. Additionally, for artifacts that have not yet made it into SpringSource Repository, |
| Gemini Blueprint provides a small, temporary (Amazon S3) |
| Maven repository (<ulink url="http://s3.amazonaws.com/maven.springframework.org/osgi">link</ulink> | |
| <ulink url="http://s3browse.com/explore/maven.springframework.org/osgi/">browser-friendly link</ulink>) for its internal usage.</para> |
| </listitem> |
| <listitem> |
| <para>Wrap the necessary jars with proper OSGi manifest. While this can be done by hand, we strongly recommend Peter Kriens |
| excellent <ulink url="http://www.aqute.biz/Code/Bnd">bnd</ulink> tool which can do this for you automatically. |
| For Maven, see Felix <ulink url="http://felix.apache.org/site/maven-bundle-plugin-bnd.html"> |
| maven-bundle-plugin</ulink>. |
| </para> |
| </listitem> |
| <listitem> |
| <para>Include the jar inside your OSGi bundle and include it in the bundle classpath through <emphasis>Bundle-ClassPath</emphasis> |
| directive. See the OSGi specification for more information.</para> |
| </listitem> |
| </itemizedlist> |
| </section> |
| |
| <section id="jdk-crippled-jta-api"> |
| <title>I keep getting <emphasis>java.lang.NoClassDefFoundError: javax/transaction/...</emphasis> when trying to do data access..</title> |
| |
| <para> |
| This problem is likely to be caused by bad class wiring. All 1.3+ JDKs include incomplete <emphasis>javax.transaction</emphasis> |
| and <emphasis>javax.transaction.xa</emphasis> packages for usage inside ORB environments. To address the problem, use a proper |
| JTA library which contains all the classes from the forementioned packages and exports them with a specific version to prevent |
| confusion. |
| </para> |
| <para> |
| Gemini Blueprint wraps JTA 1.1 library for OSGI environments which can be found at Spring snapshot repository. One can deploy this library |
| and specify version 1.1 for <emphasis>javax.transaction*</emphasis> packages inside <emphasis>Import-Package</emphasis> header. |
| By specifying the version, one can be sure that the proper package is used. |
| </para> |
| <para> |
| Note that JTA 1.1 is compatible with version 1.0.1. |
| </para> |
| </section> |
| |
| <section id="incomplete-osgi-jar"> |
| <title>When doing integration testing I receive <emphasis>java.lang.NoClassDefFoundError: org.osgi.vendor.framework property not set</emphasis>... </title> |
| |
| <para>Remove the official OSGi jars (osgi.jar or osgi-r4-core.jar) from the classpath and use only the actual OSGi platform (Equinox/Knopflerfish/Felix) |
| jars. The former provides only the public classes without an actual implementation and thus cannot be used during runtime, only during the compilation stage. |
| </para> |
| </section> |
| <!-- this should be part of an OSGi intro more likely --> |
| |
| <section id="auto-export-visibility"> |
| <title>The autoExport option doesn't work properly!</title> |
| |
| <para>autoExport flag, part of the service exporter, will discover and |
| include for exporting only the <emphasis>visible</emphasis> interfaces/classes implemented |
| by the service object. Consider class |
| <literal>GenericApplicationContext</literal> which implements among |
| others, interfaces <literal>BeanFactory</literal> (from |
| <literal>org.springframework.beans.factory</literal> package) and |
| <literal>ResourceLoader</literal> |
| (<literal>org.springframework.core.io</literal>).</para> |
| |
| <para> |
| <mediaobject> |
| <imageobject role="fo"> |
| <imagedata align="center" |
| fileref="src/docbkx/resources/images/visibility.png" |
| format="PNG"/> |
| </imageobject> |
| |
| <imageobject role="html"> |
| <imagedata align="center" fileref="images/visibility.png" |
| format="PNG"/> |
| </imageobject> |
| |
| <caption> |
| <para>Class Hierarchy</para> |
| </caption> |
| </mediaobject> |
| </para> |
| |
| <para>Depending on your OSGi imports, the exporting bundle can see |
| only one of the packages, none or both. Based on these visibility |
| settings, the exporter will only export the classes that are 'known' |
| to the exporting bundle. For example, if the exporting bundle sees |
| <literal>org.springframework.core.io</literal> but not |
| <literal>org.springframework.beans.factory</literal>, the service will |
| be exported as a <literal>ResourceLoader</literal> but not as a |
| <literal>BeanFactory</literal>. In fact, exporting the object as a |
| <literal>BeanFactory</literal> will fail since the bundle doesn't see |
| this interface and thus doesn't know how to handle its contract.</para> |
| </section> |
| |
| <section id="junit382-serialization"> |
| <title>When using Gemini Blueprint integration testing I get an exception about serialVersionUID. What is the problem?</title> |
| |
| <para> |
| This problem occurs on Spring DM versions up to 1.0 - consider upgrading to 1.0.1 or better. If you are stuck with 1.0 see below. |
| When running an integration test, Gemini Blueprint will duplicate the test instance and execute it inside OSGi. To avoid problems |
| like this one, make sure you are using the same libraries (with the same version) as Spring DM when running your test. This |
| particular problem for example is caused by a JUnit 3.8.2 vs 3.8.x serialization compatibility. Make sure that you are using |
| at least JUnit 3.8.2 for the execution of your tests. |
| </para> |
| </section> |
| |
| <section id="pde-errors"> |
| <title>I'm using Eclipse PDE and I started getting some weird exceptions/behaviour. What's the matter?</title> |
| |
| <para> |
| Eclipse PDE uses Equinox OSGi platform underneath which (like other OSGi platforms) caches the bundles between re-runs. When |
| the cache is not properly updated, one can encounter strange behaviour (such as the new services/code being picked up) |
| or errors ranging from class versioning to linkage. Consider doing a complete clean build or, in case of Eclipse, |
| creating a new workspace or deleting the bundle folder (depends on each project settings but most users should find it at: |
| <code>[workspace_dir]\.metadata\.plugins\org.eclipse.pde.core\OSGi\org.eclipse.osgi\bundles</code>). |
| </para> |
| </section> |
| |
| <section id="upgrade-to-1.1"> |
| <title>I'm upgrading to Spring DM 1.1 but now I get some ClassNotFoundExceptions. What has changed?</title> |
| |
| <para> |
| In Spring DM 1.1 M2, the proxy infrastructure has been refined to avoid <emphasis>type leaks</emphasis>, the usage of dynamic imports |
| or exposure of class loader chain delegation. If you encounter class visibility problems during the upgrade then it's likely you have |
| missing imports which were previously resolved as a side effect of Spring DM proxy weaving process. |
| </para> |
| </section> |
| |
| <section id="proxy-equality"> |
| <title>I've noticed that objects imported by Gemini Blueprint are not always equal to the raw target service. Why is that?</title> |
| |
| <para> |
| To deal with dynamics, Gemini Blueprint creates proxies around the imported services. The proxies are classes (generated at runtime), different |
| from the target but able to intercept the calls made to it. Since a proxy is different then its target, comparing objects against it can |
| yield different results then when the comparison is done against the target. In most scenarios this is not a problem but there might be |
| corner cases where this contract matters. Since 1.1, Gemini Blueprint importer proxies implement <interfacename>InfrastructureProxy</interfacename> |
| interface (from Spring framework) which allow access to the raw target. |
| </para> |
| </section> |
| <section id="static-collections"> |
| <title>My Gemini Blueprint collection doesn't change even though the number of OSGi service changes. What's wrong?</title> |
| |
| <para> |
| Make sure the Gemini Blueprint collections are injected into object of compatible types (for example <literal>list</literal> into |
| <interfacename>java.util.List</interfacename> or <interfacename>java.util.Collection</interfacename>). If the types are not compatible, |
| the container will have to perform |
| <ulink url="http://static.springframework.org/spring/docs/2.5.x/reference/validation.html#beans-beans-conversion">type conversion</ulink>, |
| transforming the Gemini Blueprint managed collection into a 'normal' one, unaware of the OSGi dynamics. |
| </para> |
| </section> |
| |
| <section id="update-to-1.2"> |
| <title>I have upgraded to Gemini Blueprint but my custom extender/web extender configuration doesn't work anymore. What has changed?</title> |
| |
| <para>Since Spring 2.5.6, the symbolic names of the artifacts have changed slightly. Spring DM/Gemini Blueprint aligned its symbolic names as well with the |
| new patter since Spring DM 1.2.0 M2. Thus the prefix <literal>org.springframework.bundle.osgi</literal> has been changed to |
| <literal>org.eclipse.gemini.blueprint</literal>; for example Gemini BLueprint extender symbolic name was changed from |
| <literal>org.springframework.bundle.osgi.extender</literal> to <literal>org.eclipse.gemini.blueprint.extender</literal> |
| (notice the missing <literal>bundle</literal> word). |
| To fix this problem, change the reference to the old symbolic name (usually inside the fragments manifests or LDAP filters) to the new one.</para> |
| </section> |
| <section id="linkage-error"> |
| <title>I get a <literal>java.lang.LinkageError: loader constraint violation</literal> if I use Gemini Blueprint. Things work fine with vanilla OSGi. |
| What's wrong?</title> |
| |
| <para>Most likely the bundle imports do not identify all the transitive packages dependencies (through the <emphasis>uses</emphasis> directive). Packages |
| imported from a bundle, can in turn, depend on other packages from other bundles - these are sometime called transitive or indirect dependencies. If |
| these are not properly identified, the OSGi platform cannot validate the wiring and allows multiple versions of the same class to be available inside the |
| same class space. This problem appears whether Gemini Blueprint is used or not. However, due to the usage of proxies inside Gemini Blueprint (which forces eager class loading |
| for the classes proxies), the class graph is evaluated at runtime causing the problem to occur early. With vanilla OSGi, the loading occurs lazy which means |
| the problem is going to occur at runtime rather then at startup. |
| To fix the problem, add the relevant transitive packages to the list of exported packages, either manually or automatically through tools such as |
| <ulink url="http://www.springsource.org/bundlor">Bundlor</ulink> or <ulink url="http://www.aqute.biz/Code/Bnd">Bnd</ulink>. |
| For more information on the <literal>uses</literal> directive please see the OSGi spec, |
| section 3.6.4 or <ulink url="http://blog.springsource.com/2008/10/20/understanding-the-osgi-uses-directive/">this</ulink> SpringSource blog entry. |
| </para> |
| </section> |
| |
| <section id="blueprint"> |
| <title>What can I use Gemini Blueprint with the Blueprint Container spec? What's the relationship between the two? Are the they compatible? |
| Are there any differences?</title> |
| |
| <para>Gemini Blueprint (Spring DM 2.0) is the Reference Implementation for OSGi 4.2 Blueprint Container specification. Simply deploy your Blueprint bundles in a platform |
| where Gemini Blueprint is already activated and you should be done. For more information about Blueprint and Gemini Blueprint, please see the |
| <emphasis>Blueprint Container</emphasis> chapter in the reference documentation.</para> |
| </section> |
| |
| <section id="kf-2.3-boot-delegation"> |
| <title>I'm using Knopflerfish 2.3.x and I have a lot of visibility exception. How can I fix this?</title> |
| |
| <para>Since 2.3.0, Knopflerfish changed the way it does bootpath delegation which causes classes to be loaded from inside and outside OSGi. Set |
| the system property <literal>org.knopflerfish.framework.strictbootclassloading</literal> to <literal>true</literal> before starting up the Knopflerfish |
| platform to prevent this from happening. See Knopflerfish 2.3.x release <ulink url="http://www.knopflerfish.org/release_notes_2.3.html">notes</ulink> for more |
| information.</para> |
| </section> |
| <section id="pde-cycles"> |
| <title>I'm using Gemini Blueprint and Spring jars inside Eclipse PDE but I get an error about cycle dependency errors. What's wrong?</title> |
| |
| <para>Some of the Spring jars (optionally) import each other packages for bootstrapping reasons. While cycles between jars are allowed and |
| supported by the OSGi platform, by default, Eclipse PDE complains about them. Since Eclipse Galileo, it is possible to enable binary cycles |
| in a target platform. allowing the build to compile. For more information, see |
| <ulink url="http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/export_wizards/export_plugins.htm">this</ulink> |
| entry from the Eclipse Reference Guide.</para> |
| </section> |
| </chapter> |
| </book> |
