Spring Dynamic Modules Reference Guide
1.0.2
Adrian M Colyer (SpringSource), Hal Hildebrand (Oracle), Costin Leau (SpringSource), Andy
Piper (BEA)
Copyright © 2006-2008
Copies of this document may be made for your own use and for distribution to others, provided that you do not
charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether
distributed in print or electronically.
Preface ............................................................................................................................................iv
I. Introduction ..................................................................................................................................1
1. Why Spring Dynamic Modules? ............................................................................................2
2. Requirements ........................................................................................................................3
II. Reference Documentation .............................................................................................................4
3. Bundles and Application Contexts ..........................................................................................5
3.1. The Spring Dynamic Modules Extender bundle ............................................................5
3.2. Application Context Creation ......................................................................................5
3.2.1. Mandatory Service Dependencies .....................................................................5
3.2.2. Application Context Service Publication ...........................................................6
3.3. Bundle Lifecycle ........................................................................................................6
3.4. The Resource abstraction ............................................................................................ 7
3.5. Accessing the BundleContext ...................................................................................... 8
3.6. Application Context Destruction .................................................................................8
3.7. Stopping the extender bundle ......................................................................................8
4. Packaging and Deploying Spring-based OSGi applications ...................................................... 9
4.1. Bundle format and Manifest headers .......................................................................... 10
4.2. Required Spring Framework and Spring Dynamic Modules Bundles ........................... 12
4.3. Spring XML authoring support ................................................................................. 13
4.4. Importing and Exporting packages ............................................................................ 13
4.5. Considerations when using external libraries .............................................................. 13
4.6. Diagnosing problems ................................................................................................ 14
5. The Service Registry ........................................................................................................... 15
5.1. Exporting a Spring bean as an OSGi service ............................................................... 16
5.1.1. Controlling the set of advertised service interfaces for an exported service ........ 16
5.1.2. Controlling the set of advertised properties for an exported service ................... 18
5.1.3. The depends-on attribute ................................................................................ 18
5.1.4. The context-class-loader attribute ................................................................... 18
5.1.5. The ranking attribute ..................................................................................... 19
5.1.6. service element attribute .............................................................................. 19
5.1.7. Service registration and unregistration lifecycle ............................................... 20
5.2. Defining references to OSGi services ........................................................................ 21
5.2.1. Referencing an individual service ................................................................... 21
5.2.2. Referencing a collection of services ................................................................ 25
5.2.3. Dealing with the dynamics of OSGi imported services ..................................... 29
5.2.4. Listener and service proxies ........................................................................... 31
5.2.5. Accessing the caller BundleContext ............................................................... 31
5.3. Exporter/Importer listener best practices .................................................................... 31
5.3.1. Listener and cyclic dependencies .................................................................... 32
5.4. Service importer global defaults ................................................................................ 33
5.5. Relationship between the service exporter and service importer ................................... 34
6. Working with Bundles ......................................................................................................... 36
7. Testing OSGi based Applications ......................................................................................... 38
7.1. OSGi Mocks ............................................................................................................ 38
7.2. Integration Testing ................................................................................................... 39
7.2.1. Creating a simple OSGi integration test .......................................................... 39
7.2.2. Installing test prerequisites ............................................................................. 40
7.2.3. Advanced testing framework topics ................................................................ 41
7.2.4. Creating an OSGi application context ............................................................. 43
7.2.5. Specifying the OSGi platform to use ............................................................... 43
7.2.6. Waiting for the test dependencies ................................................................... 44
7.2.7. Testing framework performance ..................................................................... 44
Spring Dynamic Modules(1.0.2) ii
III. Appendixes ............................................................................................................................... 45
A. Compendium Services ........................................................................................................ 46
A.1. Configuration Admin ............................................................................................... 46
A.1.1. Property placeholder support ......................................................................... 46
A.1.2. Configuration Dictionaries ............................................................................ 47
B. Extensions ......................................................................................................................... 48
B.1. Annotation-based injection ....................................................................................... 48
C. Eclipse Plug-in Development integration ............................................................................. 49
D. Spring Dynamic Modules Maven Archetype ........................................................................ 53
D.1. Generated Project Features at-a-glance ..................................................................... 53
E. Roadmap ........................................................................................................................... 55
E.1. Enhanced Configuration Admin Support ................................................................... 55
E.1.1. Managed Services ......................................................................................... 55
E.1.2. Managed Service Factories ............................................................................ 56
E.1.3. Direct access to configuration data ................................................................. 56
E.1.4. Publishing configuration administration properties with exported services ........ 56
E.2. Access to Service References for Collections ............................................................. 57
E.3. Start level integration ............................................................................................... 57
E.4. Web application support ........................................................................................... 57
E.5. ORM/Persistence support ......................................................................................... 57
E.6. OSGi standards ........................................................................................................ 58
F. Spring Dynamic Modules Schema ....................................................................................... 59
G. Acknowledgments .............................................................................................................. 67
IV. Other Resources ........................................................................................................................ 68
8. Useful links ........................................................................................................................ 69
Spring Dynamic Modules Reference Guide
Spring Dynamic Modules(1.0.2) iii
Preface
Application development has seen significant changes in the last years, moving towards a simpler, more agile,
POJO-based programming model in order to keep a fast pace. Dependency injection and Aspect Oriented
Programming, which were once bleeding edge ideas, are used on a daily basis by most developers to manage
and simplify the complexity of their applications.
However, in terms of deployment, things have remained mainly unchanged. Even though code bases are
divided into modules, whether logical, conceptual or physical, at runtime they are seen as one monolithic
application in which, making a change (be it large or small), requires a restart. OSGi aims to change this by
allowing applications to be divided into modules that can have different life cycles, dependencies and still exist
as a whole.
Spring Dynamic Modules focuses on integrating Spring Framework powerful, non-invasive programming
model and concepts with the dynamics and modularity of OSGi platform. It allows transparent exporting and
importing of OSGi services, life cycle management and control.
While every effort has been made to ensure that this documentation is comprehensive and there are no errors,
nevertheless some topics might require more explanation and some typos might have crept in. If you do spot
any mistakes or even more serious errors and you can spare a few cycles during lunch, please do bring the error
to the attention of the Spring Dynamic Modules team by raising an issue. Thank you.
Spring Dynamic Modules(1.0.2) iv
Part I. Introduction
This document is the reference guide for Spring Dynamic Modules. It defines Spring Dynamic Modules
concepts and semantics, the syntax for the OSGi Service Platform based namespaces, the Dynamic Modules
extender bundle and the OSGi manifest header entries defined by Dynamic Modules. For a tutorial introduction
to building OSGi-based applications with Spring Dynamic Modules see our online page.
OSGi developers looking for an introduction to Spring should review the introductory articles on the
springframework.org site.
Note: OSGi is a trademark of the OSGi Alliance. Project name is pending final approval from the Alliance.
Note: Please see the known issues page for Spring Dynamic Modules release.
Spring Dynamic Modules(1.0.2) 1
