osgi and equinox creating highly modular java™ systems
TRANSCRIPT
OSGi and Equinox
Creating Highly Modular Java™ Systems
Jeff McAffer Paul VanderLei Simon Archer
rAYAddison-Wesley T T
Upper Saddle River, NJ • Boston • Indianapolis • San Francisco
New York • Toronto • Montreal • London • Munich • Paris • Madrid Capetown • Sydney • Tokyo • Singapore • Mexico City
Contents
Foreword xxi Preface xxv Acknowledgments xxix About the Authors xxxiii
Port / О Introduction
Chapter 1
Chapter 2
OSG, Equinox, and Eclipse 1.1 A Bit of History 1.2 Collaboration 1.3 Modularity and Freedom of Action 1.4 Platforms 1.5 Ecosystems 1.6 OSGi in Context
1.6.1 The Java Lie 1.6.2 Reality Check 1.6.3 OSGi Longevity
1.7 OSGi and Equinox in Practice 1.7.1 NASA 's Maestro and Ensemble
1.8 Summary
OSG Concepts 2.1 A Community of Bundles 2.2 Why OSGi? 2.3 The Anatomy of a Bundle
3 3 4 5 7 7 8 8 8 9
10 10 11
13 13 15 18
VIII Contents
2.4 Modularity 19 2.4.1 Exporting a Package 19 2.4.2 Importing a Package 20 2.4.3 Requiring a Bundle 20 2.4.4 Enforcing Modularity 21
2.5 Modular Design Concepts 21 2.6 Lifecycle 22 2.7 Collaboration 24
2.7.1 Services 24 2.7.2 Extensions and Extension Points 25
2.8 The OSGi Framework 26 2.9 Security 27 2.10 OSGi Framework Implementations 27 2.11 Summary 28
Part И О OSGi by Example 29
Chapter 3 Tutorial Introduction 31 3.1 What Is Toast? 31 3.2 The Evolution of Toast 34 3.3 Development Environment Installation 36 3.4 Sample Code 36
3.4.1 Moving from Chapter to Chapter 37 3.4.2 Comparing 38
3.5 Target Platform Setup 39 3.5.1 The Predefined Target 40 3.5.2 Defining Target Platforms 42
3.6 Learning by Example 46 3.7 Summary 48
Chapter 4 Hello, Toast 49 4.1 A Simple Scenario 49
4.1.1 The Project 50 4.1.2 Gps 51
Contents IX
4.2
4.3
4.1.3 Ai rbag and iAi rbagListener
4.1.4 EmergencyMonitor
4.1.5 Main
4.1.6 Running
4.1.7 Checkpoint
Slicing Toast into Bundles
4.2 J GPS Bundle
4.2.2 Airbag Bundle
4.2.3 Emergency Monitor Bundle
4.2.4 Launching
Summary
Chapter 5 Services 5.1 Moving to Services
5.2
5.3
5.4
5.5
Registering the GPS Service
Registering the Airbag Service
Acquiring Services
Launching
5.6 Troubleshooting
5.7 Summary
Chapter 6 Dynamic Services 6.1 Introduction to Dynamic Services
6.1
6.3
Using Service Trackers
6.2.1 Modifying the Bundle Activator
6.2.2 Launching
6.2.3 Service Tracker Summary
Using the Service Activator Toolkit
6.3.1 Installing SAT into the Target Platform
6.3.2 Modifying the GPS Bundle Activator
6.3.3 Modifying the Airbag Bundle Activator
6.3.4 Modifying the Emergency Monitor Bundle Activator
6.3.5 Launching
6.3.6 SAT Summary
52
54
55
56
56
56
58
60
61
63
65
67 67
69
75
79
81
82
83
85 85
87
87
90
92
93
93
94
94
95
96
96
X Contents
6.4 Using Declarative Services 97
6.4.1 Modifying the GPS Bundle 98
6.4.2 Modifying the Air bag Bundle 101
6.4.3 Modifying the Emergency Bundle 102
6.4.4 Launching 104
6.4.5 Declarative Services Summary 105
6.5 Summary 105
Chapter 7 Client/Server Interaction 107 7.1 The Back End 108
7.1.1 The Core Bundles 108
7.1.2 The Back End Emergency Bundle 109
7.2 The Client Side 111
7.2.1 The Channel Bundle 112
7.2.2 The Emergency Monitor Bundle 116
7.3 Utility Classes 119
7.3.1 Constants 119
7.3.2 Properties 119
7.3.3 Logging 120
7.4 Running Toast 121
7.4.1 Running the Back End 121
7.4.2 Running the Client 122
7.5 Summary 123
Chapter 8 Testing 125 8.1 Making Toast Testable 126
8.2 Unit-Testing Toast 126
8.2.1 Test Strategy 126
8.2.2 Writing the Test Case 127
8.2.3 Running the Unit Test 130
8.3 System-Testing Toast 131
8.3.1 Test Strategy 131
8.3.2 Creating the Test Harness 132
8.3.3 Writing the Test Case 135
Contents XI
8.3.4 Running the System Test 137
8.4 Summary 139
Chapter 9 Packaging I41 9.1 Defining a Toast Product 141
9.1.1 Creating a Product Configuration 142
9.1.2 The Overview Page 143
9.1.3 The Dependencies Page 144
9.1.4 The Configuration Page 146
9.1.5 The Launching Page 147
9.1.6 Running the Product 148
9.1.7 Productizing the Client 149
9.2 Exporting Toast 149
9.3 Packaging for Other Platforms 152
9.4 Getting Serious about Component Definition 154
9.4.1 Versions and Version Ranges 155
9.4.2 Exporting Packages and Friendship 156
9.5 Summary 158
Chapter 10 Pluggable Services 161 10.1 Separating Interface from Implementation 162
10.1.1 Separating the Fake Airbag from Its Interface 163
10.1.2 Separating the Fake GPS from Its Interface 164
10.1.3 Regression Testing 164
10.2 Device Simulation 165
10.2.1 Concepts 165
10.2.2 The Device Simulator Framework 166
10.3 Simulated Devices as Pluggable Services 167
10.3.1 The Simulated Airbag 167
10.3.2 The Simulated GPS 169
10.4 Running with Simulated Devices 169
10.5 Summary 171
X» Contents
Chapter 11 Extensible User Interface 173 11.1 Crust 173
11.1.1 Crust Shell 174
11.1.2 Crust Widgets 175
11.2 Emergency 175
11.2.1 Making the User Interface Pluggable 176
11.2.2 Refactoring the Emergency Domain Logic 176
11.2.3 The Emergency User Interface 178
11.2.4 Running the User Interface 179
11.3 Climate and Audio 181
11.3.1 Climate and Audio Devices 181
11.3.2 Climate and Audio Screens 183
11.3.3 Running the User Interface 183
IIA The OSGi Application Model 184
11.5 Navigation and Mapping 187
11.5.1 Google Earth Integration 187
11.5.2 Mapping Support 191
11.5.3 Application Extensibility and
Navigation Support 191
11.5.4 Running the User Interface 192
11.6 Summary 195
Chapter 12 Dynamic Configuration /97 12.1 The Tracking Scenario 197
12.2 Installing the Tracking Code 198
12.2.1 The Core Tracking Bundle 198
12.2.2 The Back End Tracking Bundle 199
12.2.3 The Client Tracking Bundle 199
12.3 Running the Basic Tracking Scenario 201
12.4 Configuration 201
12.4.1 OSGi's Configuration Admin 201
12.4.2 The Client Tracking Bundle 201
Contents хш
12.4.3 Running Configurable Toast 204 12.4.4 Running with Persistent Configuration 205
12.5 Summary 205
Chapter 13 Web Portal 207 13.1 Portal 207 13.2 The por ta lserv le t 208 13.3 Action Lookup Using Services 210 13.4 Declaring a Portal Action 213 13.5 Whiteboard Pros and Cons 215 13.6 Summary 216
Chapter 14 System Deployment with p2 217 14.1 Introduction to Equinox p2 217
14.1.1 Architecture 218 14.1.2 p2 Metadata—Installable Units 219 14.1.3 Artifacts 220 14.1.4 Repositories 220 14.1.5 Profiles 220 14.1.6 Director 221 14.1.7 Engine 221
14.2 Refining the Toast Structure 221 14.2.1 Defining Products Using Features 222 14.2.2 Back End Features 222 14.2.3 Client Features 225 14.2.4 Restructuring Summary 228
14.3 Writing a Provisioner 229 14.3.1 The Provisioner 229 14.3.2 Configuring the Back End 233 14.3.3 Back End Summary 233
14.4 Adding a Deployment Web UI 233 14.4.1 The Create Action 234 14.4.2 The Manage Action 235
XIV Contents
14.4.3 The Install and Uninstall Actions 235 14.4.4 Installing the Provisioning UI 235
14.5 Exporting, Running, and Provisioning 235 14.5.1 Populating a p2 Repository 236 14.5.2 Running the Toast Back End 238 14.5.3 Creating and Provisioning Vehicles 240
14.6 Client-Side Dynamic Deployment 241 14.7 Summary 242
Part III О Deep Dives 245
Chapter 15 Declarative Services 247 15.1 The Declarative Services Model 247 15.2 Common Scenarios 248
15.2.1 The Simplest Component 249 15.2.2 Referencing Services 250 15.2.3 Providing Services 253 15.2.4 Referencing and Providing Services 254 15.2.5 Immediate Components 255 15.2.6 The Whiteboard Pattern 256 15.2.7 Factory Components 262
15.3 Launching and Debugging DS Applications 269 15.4 PDE Tooling 270 15.5 Summary 273
Chapter 16 Extensions 275 16.1 The Extension Registry 275 16.2 Extension Points 278 16.3 Extensions 280 16.4 Advanced Extension Topics 281
16.4.1 Contribution IDs 281 16.4.2 Named and Anonymous Extensions 282 16.4.3 Extension Factories 282
Contents xv
16.5 Extension Registry Lifecycle 283
16.6 Dynamic Extension Scenarios 284
16.6.1 Scenario 1: No Caching 285
16.6.2 Scenario 2: Extension Caching 285
16.6.3 Scenario 3: Object Caching 287
16.7 Services and Extensions 290
16.7.1 Integrating Services and Extensions 291
16.8 Extension Registry Myths 293
16.9 Summary 293
Chapter 17 Logging 295 17.1 The Log Service Specification 295
17.1.1 Logging Levels 296
17.1.2 Writing to the Log 296
17.1.3 Reading the Log 297
17.1.4 Listening to the Log 298
17.2 Using the Logservice in Toast 298
17.3 Using the LogReaderservice 301
17.4 Toast's Logutili ty Class 303
17.5 Equinox's Logservice Implementations 304
17.6 Summary 306
Chapter 18 HTTP Support 307 18.1 The Httpservice 308
18.1.1 Concepts 308
18.2 Registering and Unregistering a Servlet 309
18.3 Declarative HTTP Content Registrations 312
18.4 Using Jetty 313
18.5 HTTP Contexts and JAAS Integration 314
18.5.1 Basic HTTP Authentication and Login 314
18.5.2 Running the Secured Client 317
18.6 Troubleshooting 318
18.6.1 BindException 319
xv/ Contents
18.6.2 On Which Port Is the H t tpServ i ce
Listening? 319
18.7 Summary 320
Chapter 19 Server Side 321 19.1 Servers and OSGi 322
19.2 Embedding the Back End in a Web Application 323
29.2.1 Updating the Product 324
19.2.2 The Web Application Root Files 326
19.2.3 Building the Web Application 329
19.2.4 Running the Web Application 330
19.2.5 Troubleshooting 332
19.2.6 <init-param>s 333
19.3 Remote Services in OSGi 333
19.3.1 The Eclipse Communication Framework 334
19.3.2 Remote Services 335
19.3.3 Distributed Toast 335
19.3.4 Remote Service Host 336
19.3.5 Remote Service Client 338
19.3.6 Service Discovery 339
19.3.7 Running the Distributed System 340
19.4 Summary 341
Chapter 20 Release Engineering 343 20.1 What Is PDE Build? 344
20.2 Bundle bu i ld .proper t ies 345
20.2.1 Control Properties 346
20.2.2 Using Custom Build Scripts 347
20.3 Setting Up a Builder 347
20.3.1 Tweaking the Target for PDE Build 348
20.3.2 bu i ld .proper t ies 348
20.4 Running the Builder 353
20.5 Tweaking the Build 356
20.5.1 Customizing the Build Scripts 356
Contents XVII
20.5.2 Repositories and Additional Dependencies 357 20.5.3 Fetching from an SCM System 358 20.5.4 Fetching the Maps 360 20.5.5 Auto-substitution of Version Numbers 360 20.5.6 Qualifying Version Numbers 361 20.5.7 Identifying and Placing Root Files 362
20.6 Building Add-on Features 363 20.6.1 Setting Up a Feature Builder 364 20.6.2 bu i ld .proper t ies 364 20.6.3 Running the Feature Build 365
20.7 Building WARs 367 20.8 Summary 367
Part IV О Reference 369
Chapter 21 Dynamic Best Practices 371 21.1 Dynamism and You 371 21.2 Dynamic Aspects of Toast 372 21.3 Dynamic Challenges 374 21.4 Dynamic Awareness 374
21.4.1 Object Handling 376 21.4.2 Bundle Listeners 377
21.5 The Extender Pattern and Bund!етгаскег 378 21.6 Dynamic Enablement 379
21.6.1 Cleaning Up after Yourself 380 21.7 The Dynamics of Startup and Shutdown 382
21.7.1 Start Levels 382 21.7.2 Proper Use of Services 383 21.7.3 Shutting Down Is Not Always Easy 384
21.8 Summary 385
Chapter 22 Integrating Code Libraries 387 22.1 JARs as Bundles 388 22.2 Bundling by Injection 388
XVIII Contents
22.3 Bundling by Wrapping 390
22.4 Bundling by Reference 392
22.5 Bundling Using bnd 394
22.6 Troubleshooting Class Loading Problems 394
22.6.1 Issues with class.forNameO 395
22.6.2 Issues with Context Class Loaders 399
22.6.3 Managing J RE Classes 401
22.6.4 Serialization 402
22.7 Summary 403
Chapter 23 Advanced Topics 405 23.1 The Equinox Console 406
23.1.1 Extending the Equinox Console 407
23.2 Roles in OSGi 409
23.3 The Shape of Bundles 411
23.4 Fragments 413
23.5 Singletons 415
23.6 Bundle Lifecycle 416
23.6.1 Lifecycle States 416
23.6.2 BundleActivator 418
23.6.3 The Downside of Activators 418
23.6.4 Uses for Activators 419
23.7 Bundle Activation Policy 419
23.8 Controlling Bundle Start 421
23.8.1 Persistent Starting 422
23.8.2 Enabling the Activation Policy 422
23.8.3 osgi.bundles 422
23.9 Class Loading 423
23.9.1 Class Lookup Algorithm 424
23.9.2 Declaring Imports and Exports 424
23.9.3 Importing versus Requiring 426
23.9.4 Optionality 426
23.9.5 The uses Directive 426
23.9.6 Re-exporting 427
Contents XIX
23.9.7 x-internal and x-friends 428 23.9.8 Boot Delegation 428
23.10 Configuring and Running Equinox 428
23.10.1 config. ini 429
23.10.2 The Executable 430
23.11 Data Areas 432
23.12 Summary 434
Chapter 24 Declarative Services Reference 435 24.1 Component XML Schema vl . 1.0 435
24.1.1 Declaring the XML Namespace and Schema 435
24.1.2 The <component> Element 437
24.1.3 The <implementation> Element 439
24.1.4 The <property> Element 439
24.1.5 The <properties> Element 440
24.1.6 The <service> Element 441
24.1.7 The <provide> Element 442
24.1.8 The <reference> Element 442
24.2 The Component Lifecycle 444
24.2.1 Satisfying a Component's Configuration 445
24.2.2 Component Activation, Deactivation,
and Modification 447
24.2.3 Accessing Referenced Services 450
24.2.4 Component Immediacy 453
24.2.5 Component Properties 454
24.3 Summary 457
Index 459