Eclipse Gemini Blueprint Reference Guide

Adrian M Colyer

SpringSource, division of VMware

Hal Hildebrand


Costin Leau

SpringSource, division of VMware

Andy Piper



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 and the Apache License v2.0 is available at You may elect to redistribute this code under either of these licenses.

I. Introduction
1. Spring Dynamic Modules becomes Eclipse Gemini Blueprint
2. Why Gemini Blueprint?
3. Requirements
4. Getting Started
4.1. First Steps
4.1.1. Knowing Spring
4.1.2. Knowing OSGi
4.1.3. Quick start - OSGi 5.x Blueprint Container
4.2. Need Help?
4.2.1. Community Support
4.2.2. Professional Support
4.3. Following Development
5. What is new?
5.1. Gemini Blueprint 2.1.0+
5.1.1. Java 8
5.1.2. Spring 4.3.x
5.1.3. Gemini Blueprint Extensions
5.2. Gemini Blueprint 2.0.0+
5.2.1. OSGi 5.x Blueprint Reference Implementation (RI)
5.2.2. Java 7
5.2.3. Spring 4.2.x
5.3. Gemini Blueprint 1.x
5.3.1. OSGi 4.2 Blueprint Reference Implementation (RI)
5.3.2. Java 5
5.3.3. Spring 3.x
5.3.4. Service Importer Improvements
5.3.5. Java 2 Security Integration
5.4. Spring DM 1.2.x
5.4.1. Java 2 Security Integration
5.4.2. Compendium Services Support
5.4.3. Changed Spring DM Symbolic Names
5.4.4. Usage of SpringSource Enterprise Bundle Repository (EBR)
II. Reference Documentation
6. OSGi 4.2 Blueprint Container
6.1. Blueprint Requirements
6.2. Blueprint/Gemini Blueprint Differences
6.2.1. XML Declarations
6.2.2. Container Capabilities
6.3. Using Blueprint
7. Bundles and Application Contexts
7.1. The Gemini Blueprint Extender Bundle
7.2. Application Context Creation
7.2.1. Mandatory Service Dependencies
7.2.2. Application Context Service Publication
7.3. Bundle Lifecycle
7.4. The Resource Abstraction
7.5. Bundle Scope
7.6. Accessing the BundleContext
7.7. Application Context Destruction
7.8. Stopping the Extender Bundle
8. Packaging and Deploying Spring-based OSGi applications
8.1. Bundle Format And Manifest Headers
8.2. Blueprint Manifest Configuration Comparison
8.3. Extender Configuration Options
8.3.1. Listening To Extender Events
8.4. Required Spring Framework And Gemini Blueprint Bundles
8.5. Optional Gemini Blueprint Bundles
8.6. Spring XML Authoring Support
8.7. Importing and Exporting Packages
8.8. Considerations When Using External Libraries
8.9. Diagnosing Problems
9. The Service Registry
9.1. Exporting A Spring Bean As An OSGi Service
9.1.1. Using The Service Registration
9.1.2. org.osgi.framework.ServiceFactory Support
9.1.3. Controlling The Set Of Advertised Service Interfaces For An Exported Service Detecting The Advertised Interfaces At Runtime
9.1.4. Controlling The Set Of Advertised Properties For An Exported Service
9.1.5. The depends-on Attribute
9.1.6. The context-class-loader Attribute
9.1.7. The ranking Attribute
9.1.8. The cache-target Attribute
9.1.9. service Element Attributes
9.1.10. Service Registration And Unregistration Lifecycle Using OsgiServiceRegistrationListener Interface Blueprint service Comparison
9.2. Defining References To OSGi Services
9.2.1. Referencing services via the @ServiceReference annotation
9.2.2. Imported Service Availability Mandatory Services and Application Startup Relationship Between The Service Exporter And Service Importer
9.2.3. Referencing An Individual Service Controlling The Set Of Advertised Interfaces For The Imported Service The filter Attribute The bean-name Attribute The availability Attribute The depends-on Attribute The context-class-loader Attribute The sticky Attribute reference Element Attributes reference And OSGi Service Dynamics Getting A Hold Of The Managed Service Reference
9.2.4. Referencing A Collection Of Services Greedy Proxying Member Type Collection (list And set) Element Attributes list / set And OSGi Service Dynamics Iterator Contract And Service Collections
9.2.5. Dealing With The Dynamics Of OSGi Imported Services
9.2.6. Blueprint reference Comparison
9.3. Listener And Service Proxies
9.4. Accessing The Caller BundleContext
9.5. Exporter/Importer Listener Best Practices
9.5.1. Listener And Cyclic Dependencies
9.6. Service Importer Global Defaults
10. Working With Bundles
11. Compendium Services
11.1. Configuration Admin
11.1.1. Exposing Configuration Admin Entries As Properties
11.1.2. Managed Properties Configuration Admin Runtime Updates
11.1.3. Managed Service Factories
11.1.4. Direct Access To Configuration Data
12. Testing OSGi based Applications
12.1. OSGi Mocks
12.2. Integration Testing
12.2.1. Creating A Simple OSGi Integration Test
12.2.2. Installing Test Prerequisites
12.2.3. Advanced Testing Framework Topics Customizing The Test Manifest Customizing Test Bundle Content Understanding The MANIFEST.MF Generation
12.2.4. Creating An OSGi Application Context
12.2.5. Specifying The OSGi Platform To Use
12.2.6. Waiting For The Test Dependencies
12.2.7. Testing Framework Performance
III. Other Resources
13. Useful Links
IV. Appendixes
A. Security Integration
B. Eclipse Plug-in Development integration
C. Useful OSGi tips
C.1. OSGi Fragments
D. Roadmap
D.1. Start Level Integration
E. Gemini Blueprint OSGi Repository
E.1. Gemini Blueprint Temporary OSGi Repository
E.1.1. Repository Conventions
E.1.2. Browsing The Repository Content
E.1.3. Using The Repository With Maven
E.1.4. Using The Repository With Ant/Ivy
F. Gemini Blueprint Schema
G. Acknowledgments