The OSGi Alliance OSGi Core Release 5 March 2012 Copyright © OSGi Alliance (2000,2012). All Rights Reserved. OSGi Specification License, Version 2.00 License Grant OSGi Alliance (“OSGi”) hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide, limited license (without the right to sublicense), under OSGi’s applicable intellectual property rights to view, download, and reproduce this OSGi Specification (“Specification”) which follows this License Agreement (“Agreement”). You are not authorized to create any derivative work of the Specification. However, to the extent that an implementation of the Specification would necessarily be a derivative work of the Specification, OSGi also grants you a perpetual, non-exclusive, worldwide, fully paid-up, royalty free, limited license (without the right to sublicense) under any applicable copyrights, to create and/or distribute an implementation of the Specification that: (i) fully implements the Specification including all its required interfaces and functionality; (ii) does not modify, subset, superset or otherwise extend the OSGi Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the OSGi Name Space other than those required and authorized by the Specification. An implementation that does not satisfy limitations (i)-(ii) is not considered an implementation of the Specification, does not receive the benefits of this license, and must not be described as an implementation of the Specification. An implementation of the Specification must not claim to be a compliant implementation of the Specification unless it passes the OSGi Compliance Tests for the Specification in accordance with OSGi processes. “OSGi Name Space” shall mean the public class or interface declarations whose names begin with “org.osgi" or any recognized successors or replacements thereof. OSGi Participants (as such term is defined in the OSGi Intellectual Property Rights Policy) have made non-assert and licensing commitments regarding patent claims necessary to implement the Specification, if any, under the OSGi Intellectual Property Rights Policy which is available for examination on the OSGi public web site (www.osgi.org). No Warranties and Limitation of Liability THE SPECIFICATION IS PROVIDED "AS IS," AND OSGi AND ANY OTHER AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. OSGi AND ANY OTHER AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SPECIFICATION OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF. Covenant Not to Assert As a material condition to this license you hereby agree, to the extent that you have any patent claims which are necessarily infringed by an implementation of the Specification, not to assert any such patent claims against the creation, distribution or use of an implementation of the Specification. General The name and trademarks of OSGi or any other Authors may NOT be used in any manner, including advertising or publicity pertaining to the Specification or its contents without specific, written prior permission. Title to copyright in the Specification will at all times remain with OSGi. No other rights are granted by implication, estoppel or otherwise. Page i OSGi Core Release 5 Trademarks OSGi™ is a trademark, registered trademark, or service mark of the OSGi Alliance in the US and other countries. Java is a trademark, registered trademark, or service mark of Oracle Corporation in the US and other countries. All other trademarks, registered trademarks, or service marks used in this docu- ment are the property of their respective owners and are hereby recognized. Feedback This specification can be downloaded from the OSGi Alliance web site: http://www.osgi.org Comments about this specification can be raised at: http://www.osgi.org/bugzilla/ OSGi Core Release 5 Page ii Page iii OSGi Core Release 5 Table Of Contents 1 Introduction 1 1.1 OSGi Framework Overview...........................................................................................................................1 1.2 Reader Level..................................................................................................................................................3 1.3 Conventions and Terms................................................................................................................................3 1.4 Version Information......................................................................................................................................7 1.5 Changes.........................................................................................................................................................8 1.6 References.....................................................................................................................................................8 2 Security Layer 9 2.1 Introduction...................................................................................................................................................9 2.2 Security Overview.........................................................................................................................................9 2.3 Digitally Signed JAR Files.............................................................................................................................10 2.4 Permissions..................................................................................................................................................19 2.5 Changes.......................................................................................................................................................20 2.6 References...................................................................................................................................................20 3 Module Layer 23 3.1 Introduction.................................................................................................................................................23 3.2 Bundles........................................................................................................................................................23 3.3 Dependencies..............................................................................................................................................30 3.4 Execution Environment...............................................................................................................................35 3.5 Class Loading Architecture.........................................................................................................................37 3.6 Resolving Metadata.....................................................................................................................................39 3.7 Constraint Solving.......................................................................................................................................44 3.8 Resolving Process.........................................................................................................................................51 3.9 Runtime Class Loading................................................................................................................................52 3.10 Loading Native Code Libraries....................................................................................................................60 3.11 Localization.................................................................................................................................................64 3.12 Bundle Validity............................................................................................................................................66 3.13 Requiring Bundles........................................................................................................................................66 3.14 Fragment Bundles........................................................................................................................................69 3.15 Extension Bundles.......................................................................................................................................72 3.16 Security.......................................................................................................................................................74 3.17 Changes.......................................................................................................................................................77 3.18 References...................................................................................................................................................77 4 Life Cycle Layer 79 4.1 Introduction.................................................................................................................................................79 4.2 Frameworks.................................................................................................................................................80 OSGi Core Release 5 Page iv 4.3 Bundles........................................................................................................................................................89 4.4 The Bundle Object......................................................................................................................................89 4.5 The Bundle Context..................................................................................................................................100 4.6 The System Bundle...................................................................................................................................104 4.7 Events.........................................................................................................................................................105 4.8 Security.....................................................................................................................................................108 4.9 Changes......................................................................................................................................................110 4.10 References..................................................................................................................................................110 5 Service Layer 113 5.1 Introduction...............................................................................................................................................113 5.2 Services......................................................................................................................................................114 5.3 Service Events............................................................................................................................................120 5.4 Stale References........................................................................................................................................121 5.5 Filters.........................................................................................................................................................121 5.6 Service Factory...........................................................................................................................................122 5.7 Releasing Services......................................................................................................................................123 5.8 Unregistering Services...............................................................................................................................124 5.9 Multiple Version Export Considerations....................................................................................................124 5.10 Security......................................................................................................................................................125 5.11 Changes......................................................................................................................................................126 6 Resource API Specification 127 6.1 Introduction...............................................................................................................................................127 6.2 Resources...................................................................................................................................................128 6.3 Namespaces...............................................................................................................................................128 6.4 Resolution..................................................................................................................................................129 6.5 Wiring.........................................................................................................................................................130 7 Bundle Wiring API Specification 133 7.1 Introduction...............................................................................................................................................133 7.2 Using the Wiring API..................................................................................................................................134 7.3 Bundle Wiring.............................................................................................................................................137 7.4 Fragments..................................................................................................................................................140 7.5 Framework Actions....................................................................................................................................142 7.6 Container Scanning....................................................................................................................................143 7.7 Security......................................................................................................................................................144 7.8 Changes......................................................................................................................................................144 8 Framework Namespaces Specification 145 8.1 Introduction...............................................................................................................................................145 8.2 osgi.ee Namespace....................................................................................................................................146 8.3 osgi.wiring.package Namespace................................................................................................................147 8.4 osgi.wiring.bundle Namespace..................................................................................................................148 Page v OSGi Core Release 5 8.5 osgi.wiring.host Namespace.....................................................................................................................149 8.6 osgi.identity Namespace...........................................................................................................................150 8.7 References..................................................................................................................................................151 9 Start Level API Specification 153 9.1 Introduction...............................................................................................................................................153 9.2 Start Level API...........................................................................................................................................153 9.3 The Concept of a Start Level....................................................................................................................154 9.4 Example Applications................................................................................................................................157 9.5 Security......................................................................................................................................................158 10 Framework API 159 10.1 org.osgi.framework...................................................................................................................................159 10.2 org.osgi.framework.launch........................................................................................................................241 10.3 org.osgi.resource.......................................................................................................................................246 10.4 org.osgi.framework.wiring........................................................................................................................252 10.5 org.osgi.framework.startlevel...................................................................................................................265 10.6 org.osgi.framework.namespace................................................................................................................268 50 Conditional Permission Admin Service Specification 277 50.1 Introduction...............................................................................................................................................277 50.2 Permission Management Model................................................................................................................279 50.3 Effective Permissions.................................................................................................................................284 50.4 Conditional Permissions............................................................................................................................285 50.5 Conditions.................................................................................................................................................286 50.6 The Permission Check...............................................................................................................................287 50.7 Permission Management...........................................................................................................................294 50.8 Implementing Conditions..........................................................................................................................295 50.9 Standard Conditions..................................................................................................................................297 50.10 Bundle Permission Resource......................................................................................................................298 50.11 Relation to Permission Admin...................................................................................................................299 50.12 Implementation Issues..............................................................................................................................299 50.13 Security......................................................................................................................................................301 50.14 org.osgi.service.condpermadmin..............................................................................................................302 50.15 References..................................................................................................................................................311 51 Permission Admin Service Specification 313 51.1 Introduction...............................................................................................................................................313 51.2 Permission Admin service..........................................................................................................................314 51.3 Security......................................................................................................................................................315 51.4 org.osgi.service.permissionadmin.............................................................................................................315 52 URL Handlers Service Specification 319 52.1 Introduction...............................................................................................................................................319 52.2 Factories in java.net..................................................................................................................................322 OSGi Core Release 5 Page vi 52.3 Framework Procedures.............................................................................................................................322 52.4 Providing a New Scheme..........................................................................................................................326 52.5 Providing a Content Handler.....................................................................................................................327 52.6 Security Considerations.............................................................................................................................327 52.7 org.osgi.service.url....................................................................................................................................328 52.8 References..................................................................................................................................................331 53 Resolver Hook Service Specification 333 53.1 Introduction...............................................................................................................................................333 53.2 Resolve Operation.....................................................................................................................................334 53.3 The Resolve Operation.............................................................................................................................338 53.4 Security.....................................................................................................................................................340 53.5 org.osgi.framework.hooks.resolver..........................................................................................................340 54 Bundle Hook Service Specification 345 54.1 Introduction...............................................................................................................................................345 54.2 About the Hooks.......................................................................................................................................346 54.3 Bundle Event Hook....................................................................................................................................346 54.4 Bundle Find Hook.......................................................................................................................................347 54.5 Bundle Collision Hook................................................................................................................................347 54.6 Security.....................................................................................................................................................348 54.7 Changes.....................................................................................................................................................349 54.8 org.osgi.framework.hooks.bundle............................................................................................................349 55 Service Hook Service Specification 353 55.1 Introduction...............................................................................................................................................353 55.2 Service Hooks............................................................................................................................................354 55.3 Usage Scenarios.........................................................................................................................................355 55.4 Event Listener Hook...................................................................................................................................359 55.5 Find Hook..................................................................................................................................................360 55.6 Listener Hook............................................................................................................................................360 55.7 Architectural Notes...................................................................................................................................362 55.8 Security.....................................................................................................................................................363 55.9 org.osgi.framework.hooks.service............................................................................................................363 56 Weaving Hook Service Specification 367 56.1 Introduction...............................................................................................................................................367 56.2 Usage.........................................................................................................................................................368 56.3 The Weaving Service.................................................................................................................................369 56.4 Security......................................................................................................................................................371 56.5 org.osgi.framework.hooks.weaving...........................................................................................................371 701 Tracker Specification 375 701.1 Introduction...............................................................................................................................................375 Page vii OSGi Core Release 5 701.2 Tracking.....................................................................................................................................................376 701.3 Service Tracker..........................................................................................................................................378 701.4 Bundle Tracker...........................................................................................................................................380 701.5 Security......................................................................................................................................................384 701.6 Changes.....................................................................................................................................................384 701.7 org.osgi.util.tracker...................................................................................................................................384 OSGi Core Release 5 Page viii Page ix OSGi Core Release 5