IN DEPTH Alexandre de Castro Alves FOREWORD BY DAVID BOSSCHAERT MANNING www.it-ebooks.info OSGi in Depth www.it-ebooks.info www.it-ebooks.info OSGi in Depth ALEXANDRE DE CASTRO ALVES MANNING SHELTER ISLAND www.it-ebooks.info For online information and ordering of this and other Manning books, please visit www.manning.com The publisher offers discounts on this book when ordered in quantity For more information, please contact Special Sales Department Manning Publications Co 20 Baldwin Road PO Box 261 Shelter Island, NY 11964 Email: orders@manning.com ©2012 by Manning Publications Co All rights reserved No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks Where those designations appear in the book, and Manning Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps Recognizing the importance of preserving what has been written, it is Manning’s policy to have the books we publish printed on acid-free paper, and we exert our best efforts to that end Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without elemental chlorine Manning Publications Co 20 Baldwin Road PO Box 261 Shelter Island, NY 11964 Development editor: Copyeditor: Poofreader: Typesetter: Cover designer: Sebastian Stirling Linda Recktenwald Andy Carroll Marija Tudor Marija Tudor ISBN: 9781935182177 Printed in the United States of America 10 – MAL – 17 16 15 14 13 12 11 www.it-ebooks.info brief contents ■ OSGi as a new platform for application development ■ An OSGi framework primer ■ The auction application: an OSGi case study ■ In-depth look at bundles and services ■ Configuring OSGi applications ■ A world of events 161 ■ The persistence bundle ■ Transactions and containers ■ Blending OSGi and Java EE using JNDI 10 ■ Remote services and the cloud 249 11 ■ Launching OSGi using start levels 12 ■ Managing with JMX 297 13 ■ Putting it all together by extending Blueprint v www.it-ebooks.info 17 54 93 131 189 205 222 270 316 www.it-ebooks.info contents foreword xiii preface xv acknowledgments xvi about this book xviii about the cover illustration xxi OSGi as a new platform for application development 1.1 What are development platforms and application frameworks? Why use a development platform? 1.2 The OSGi technology ■ Enterprise platforms The problem domain The solution: a dynamic module system for Java The Enterprise OSGi ■ ■ 1.3 Benefits of using the OSGi platform OSGi manages the complexity of large systems OSGi provides extensibility without eroding the system 11 OSGi is lightweight and customizable 12 OSGi allows for portability 12 ■ ■ ■ 1.4 1.5 1.6 1.7 Building blocks: the essence of OSGi Players 14 Are we starting from scratch? 15 Summary 16 vii www.it-ebooks.info 13 viii CONTENTS An OSGi framework primer 17 2.1 Modules and information hiding 18 Establishing a formal import/export contract 19 bundle 21 2.2 ■ Activating a Running and testing OSGi 22 Apache Felix, the open source OSGi framework 22 Building OSGi bundles 23 Installing bundles into Felix 25 Starting the bundles in Felix 26 Can we cheat using reflection? 27 Eclipse Equinox 29 ■ ■ ■ ■ 2.3 Coping with changes to a module 29 Changing a bundle’s interface 29 Versioning bundles Changing a module’s implementation 37 ■ 2.4 Services and loose coupling 30 39 The Printer service 40 Registering a service in the OSGi service registry 41 Looking up a service from the OSGi service registry 44 Running OSGi service-oriented applications 47 ■ ■ ■ 2.5 2.6 The OSGi layered architecture Summary 53 52 The auction application: an OSGi case study 54 3.1 3.2 3.3 Establishing the requirements for an auction system Modularization and extensibility as application requirements 56 Defining the interfaces 57 Using service properties 59 Implementing the seller module 61 Avoiding temporal cohesion between bundles The registry design pattern 67 55 ■ ■ 3.4 Defining the extension points 64 68 Developing our first auction extension 70 Whiteboard design pattern 73 Keeping service properties immutable 75 Developing the auditor extension 76 ■ ■ 3.5 Putting it all together 78 Semantic versioning 83 3.6 The OSGi HTTP service Developing an HTTP buyer 3.7 3.8 84 85 ■ Testing the auction application 88 Improving the auction application to enterprise grade Summary 91 www.it-ebooks.info 91 ix CONTENTS In-depth look at bundles and services 4.1 93 Restricting a bundle’s export contract 94 Keeping packages private 94 Excluding classes from an exported package 94 Avoiding split packages 96 ■ ■ 4.2 Expanding a bundle’s export contract Dynamic imports bundles 101 4.3 4.4 99 ■ 97 Optional packages 99 ■ Fragment Packages as requirements and capabilities 103 Avoiding the dreaded class-hell problem 105 Don’t forget to import the package! 105 Keeping class space consistency 106 Package export race condition 112 ■ ■ 4.5 4.6 Understanding OSGi’s class loading 112 Decoupling bundles using services 114 Advanced service filtering 115 Prioritizing services 117 Uniquely identifying services 120 Service factories 122 ■ ■ 4.7 Improve robustness by testing your applications Unit tests 4.8 Summary 126 ■ 126 Integration tests 128 130 Configuring OSGi applications 131 5.1 The configuration problem 132 The Notification Broker service 132 the notification broker 133 5.2 The Configuration Admin service ■ Configuring the port of 135 The target service 135 The configuring bundle 138 The Configuration Admin: a mediator of configuration 140 Finding the Configuration service using bundle repositories 140 Running the Configuration Admin service 142 ■ ■ 5.3 5.4 5.5 Configuring using complex data types Deleting configuration 143 Configuring multiple services 145 142 Configuring bundle for configuration factories 145 Managed service factories 146 ■ 5.6 When configuration update fails 149 Log listener 150 ■ Application logging www.it-ebooks.info 151 357 OSGi manifest headers (continued) Header name Bundle-ContactAddress Description Specifies the contact address of the vendor Example: Bundle-ContactAddress: 123 My Road, CA, my@email.com Bundle-Copyright Specifies the copyright information of the bundle Example: Bundle-Copyright: Manning© 2011 Bundle-Description Specifies a user-friendly short description for the bundle Example: Bundle-Description: Manning’s OSGi in Depth Auction Application Bundle-DocURL Specifies a URL pointing to a bundle’s documentation Example: Bundle-DocURL: http://www.manning.com/ alves Bundle-Icon Specifies a URL within the bundle’s JAR file for an image file, useful for a pictorial representation of the bundle Example: Bundle-Icon: /images/ bundle.jpg;size=64 Bundle-License Specifies license information that can be used to validate the bundle’s usage terms This can be in some internal format or even a URL Example: Bundle-License: http:// www.manning.com/validate-license.php Bundle-Localization Specifies the location within the bundle where localization files reside Example: Bundle-Localization: OSGi-INF/l10n/ bundle Bundle-ManifestVersion Specifies the OSGi specification to be used For our purposes, it should be set to Example: Bundle-ManifestVersion: Bundle-Name Specifies a user-friendly readable name for the bundle Example: Bundle-Name: auction application Bundle-NativeCode Specifies the native code libraries contained within the bundle Example: Bundle-NativeCode: /lib/io.dll; osname = Linux Bundle-RequiredExecutionEnvironment Specifies a comma-separated list of execution environments demanded by the bundle This header has been deprecated in version 4.3 of the OSGi specification Example: Bundle-RequiredExecutionEnvironment: CDC-1.0/Foundation-1.0 www.it-ebooks.info 358 APPENDIX A OSGi manifest headers (continued) Header name Bundle-SymbolicName Description Specifies the non-localizable identity of the bundle This header together with the bundle version uniquely identify a bundle Example: Bundle-SymbolicName: com.manning.osgi.auction Bundle-UpdateLocation Specifies a URL where updates for this bundle can be retrieved An example of how this can be used is in chapter 10 Example: Bundle-UpdateLocation: http://www.manning.com/alves/auction.jar Bundle-Vendor Specifies a user-friendly description of the bundle’s vendor Example: Bundle-Vendor: manning Bundle-Version Specifies the version of the bundle This header together with the symbolic name uniquely identify a bundle Example: Bundle-Version: 1.0.0.1 DynamicImport-Package Specifies a comma-separated list of package names that are imported when needed This is explained in chapter Example: DynamicImport-Package: com.manning.osgi.* Export-Package Specifies the exported packages of the bundle Example: Export-Package: com.manning.osgi Fragment-Host Specifies the host bundle of this fragment Example: Fragment-Host: com.manning.osgi.auction; bundle-version="1.0.0.1" Import-Package Specifies the imported packages for this bundle Example: Import-Package: com.manning.osgi Provide-Capability New header in OSGi version 4.3 used to specify a generic capability Example: Provide-Capability: com.cloudprovider; web-access:Boolean=true; cpu:Long=80 Meta-Persistence Specifies the path to the persistence unit configuration of a JPA persistence bundle Chapter explains how JPA is used Example: Meta-Persistence: META-INF/auction- jpa.xml Meta-Transaction Specifies Java classes to be run in a transactional context This is part of an example explained in chapter Example: Meta-Transaction: com.manning.osgi.MyTransactionalClass Remote-Service Specifies the endpoint description of a remote service This is explained in chapter Example: Remote-Service: META-INF/endpoint.xml www.it-ebooks.info 359 OSGi manifest headers (continued) Header name Require-Bundle Description Specifies dependency to another bundle As explained in chapter 4, this should be avoided Example: Require-Bundle: com.manning.osgi.auction Require-Capability New header in OSGi version 4.3 used to specify a dependency on a provided capability Example: Require-Capability: com.cloudprovider; filter:="(&(web-access)(cpu