Space: Apache Tuscany Docs 2.x (http://cwiki.apache.org/confluence/display/TUSCANYxDOCx2x) Page: OSGi Enablement for Tuscany Runtime (http://cwiki.apache.org/confluence/display/TUSCANYxDOCx2x/OSGi+Enablement+for+Tuscany+Runtime)
Edited by Luciano Resende: --------------------------------------------------------------------- h1. OSGi Enablement for Tuscany Runtime [OSGi Enablement for Tuscany.ppt|^OSGi Enablement for Tuscany.ppt] h2. Movtivations to enable OSGi for Tuscany: * Provide modularity for Tuscany to formalize the SPI contracts and enforce the package dependencies across modules * Enable Tuscany to work with OSGi environment such as JEE application servers, Eclipse RCP or Spring DM (see [http://www.infoq.com/news/2008/11/osgi-in-the-enterprise] ) * Provide versioning and isolation so that Tuscany extensions can depend on different versions of the same library * Provide dynamic lifecycle for extensions, install/uninstall/start/stop a module h2. Objectives * Tuscany runtime will be able to run in both non-OSGi and OSGi environment * A consistent OSGi story across development, build, runtime and testing h2. Steps to make Tuscany work with OSGi (Basic enablement) * Add OSGi MANIFEST.MF for each module to make it an OSGi bundle ** The generated MANIFEST.MF from maven-bundle-plugin is a good starting point. The result may not be accurate and it doesn't help to reduce the coupling ** It should be developers' reponsibility to maintain it for the optimal dependencies * Convert each non-OSGi 3rd-party jar into an OSGi bundle ** Exception: Aggregate a group of 3rd-party jars if they have split packages * Add an OSGi-based service discoverer to discover tuscany extension points and extensions from the installed bundles ** Use the same JDK service provider pattern (META-INF/services) as JSE ** The discoverer is configured based on the running environment (JSE or OSGi) * Change how JDK factories such as XMLInputFactory, XPathFactory, and DocumentBuilderFactory, are discovered and instantiated ** XMLInputFactory.newInstance() used the JSE service provider pattern which doesn't work with OSGi ** We need to use Tuscany's service discovery mechanism to discover and instantiate the factories * Adjust the code that assumes there is a flat thread context classloader that can access all the classes in the Tuscany runtime ** With OSGi, there is a network of classloaders (one classloader per module) and the class visibility is constrained by the OSGi headers such as Import-Package and Export-Package ** The classloader for the current class is a good starting point for Class.forName() with OSGi * Provide a SCA node launcher to start an OSGi runtime and run SCA application with the OSGi-enabled Tuscany runtime * Produce distributions that are compatible with the OSGi bundle structure in an efficient way (in one-two minutes) * Bring samples and itests to use the Tuscany SCA OSGi node launcher or run with the Eclipse Equinox profile {note}To learn from the excerises we went through, please see the slides: [^tuscany-osgi.pdf]{note} h2. Use OSGi to help Tuscany maintain and enforce good modularity with clean SPIs following the OSGi best practices * Identify the absolutely necessary SPI packages that need to be exported ** Don't try to export everything ** For model modules, try to only export the package that contains the interfaces ** Try not to export any package from the xxx-runtime moudles ** Any classes that can be accessed via the ExtensionPointRegistry using interfaces should not be exported * Only import other packages when it's needed ** For example, we used to have a lot of modules pull in assembly for just a constant for the SCA namespace ** Avoid DynamicImport-Package=\* * Do not export "private" packages as a workaround or hack which can fail the "clean SPI". Refactor things into SPIs if necessary ** For example, tuscany-core has quite a few packages that are exported. We need to define a SPI layer if these exports are required. ** implementation-java: extract out the annotation processing so that they can be reused for introspecting other java-based implementation technologies such as Spring or EJB ** implementation-java-runtime: extract out the IoC ** add common modules such as common-java and common-xml to host java or XML related utilities * Split modules into model/runtime to promote modularity * Fix some of the unit testcases that pull in too many dependencies and they should be itests To help developers to develop Tuscany modules as OSGi bundles and receive errors if OSGI constraints are violated, we integrated with a set of tools (help for improvement is welcome): * A maven plugin to generate .classpath and .project files and target definition file to produce Eclipse PDE plugin projects for Tuscany modules so that we can leverage the nice OSGi development tooling ** Compile dependencies are now pulled in by the PDE requiredPlugins classpath container ** Runtime dependencies are now generated as an explict classpath entry ** Test dependencies can be optional Import-Package or an explicit classpath entry * A maven compiler to use Eclipse JDT and OSGi bundle resolver ** The JDT compiler is much faster that javac ** The OSGi resolution reports unsatisfied OSGi constraints * A maven plugin to generate OSGi-compatible distribution structure which hosts 3rd-party jars that can be used a bundle for OSGi as well as a plain jar for JSE classpath ** Copy OSGi bundles as jars ** Create a folder structure to hold the MANIFEST.MF which keep the 3rd-party jar as-is {note}For more details, please see: [OSGi Aware Programming in Tuscany|TUSCANYxDOCx2x:OSGi Aware Programming in Tuscany]?{note} h2. Developing Tuscany modules as OSGi bundles h3. Design of an OSGi bundle * Modularity/Granularity ** Not just a simple packaging scheme such as all jars are consolidated into one big bundle, export/import everything * Maven is designed to manage build dependency ** Visibility at module level (too high) ** Transitive dependency ** Classloading is flat ** No runtime control h3. Creating an OSGi bundle * Converting Tuscany modules into OSGi bundles ** META-INF/MANIFEST.MF * Converting 3rd-party jars into OSGi bundles ** Plain Jars ** Patching existing bundles * Distribution Structure * Eclipse PDE integration ** Target platform ** Classpath setting ** PDE tools **** Build path **** PDE dependency view **** MANIFEST.MF editor **** Equinox run/debug profile h3. Maven plugins to help OSGi development * Maven Eclipse Compiler ** Use Eclipse JDT as the compiler ** Validate the MANIFEST.MF * Tuscany Maven Bundle Plugin ** Generating modules ** Generating PDE target ** Generating Equinox Configuration h3. Runtime concerns * Equinox OSGi launcher * META-INF/services Service Provider discovery * Avoid XMLInputFactory.newInstance(), DocumentBuilderFactory.newInstance()... * Classloading (TCCL is evil) ** Equinox ContextFinder h3. Test Tuscany code with OSGi * How to run maven surefire plugin with OSGi? * Eclipse run as JUnit plugin test h3. Troubleshoot the OSGi constraint violations * OSGi console ** \-Dosgi.console=<port #> * Eclipse PDE state view * Traps ** Split Packages ** System packages ** Version mismatch [^OSGi Enablement for Tuscany.ppt] Change your notification preferences: http://cwiki.apache.org/confluence/users/viewnotifications.action
