Enterprise OSGi In Action

Copyright

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: 

[email protected]

©2013 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 the use of elemental chlorine.

ISBN: 9781617290138

Printed in the United States of America

1 2 3 4 5 6 7 8 9 10 – MAL – 18 17 16 15 14 13

Brief Table of Contents

Copyright

Brief Table of Contents

Table of Contents

Preface

Acknowledgments

About this Book

About the Authors

About the Cover Illustration

1. Programming beyond Hello World

Chapter 1. OSGi and the enterprise—why now?

Chapter 2. Developing a simple OSGi-based web application

Chapter 3. Persistence pays off

Chapter 4. Packaging your enterprise OSGi applications

2. Building better enterprise OSGi applications

Chapter 5. Best practices for enterprise applications

Chapter 6. Building dynamic applications with OSGi services

Chapter 7. Provisioning and resolution

Chapter 8. Tools for building and testing

Chapter 9. IDE development tools

3. Integrating enterprise OSGi with everything else

Chapter 10. Hooking up remote systems with distributed OSGi

Chapter 11. Migration and integration

Chapter 12. Coping with the non-OSGi world

Chapter 13. Choosing a stack

Appendix A. OSGi—the basics

Appendix B. The OSGi ecosystem

Index

List of Figures

List of Tables

List of Listings

Table of Contents

Copyright

Brief Table of Contents

Table of Contents

Preface

Acknowledgments

About this Book

About the Authors

About the Cover Illustration

1. Programming beyond Hello World

Chapter 1. OSGi and the enterprise—why now?

1.1. Java’s missing modularity

1.1.1. Thinking about modularity

1.1.2. Enterprise Java and modularity—even worse!

1.2. OSGi to the rescue

1.2.1. Modularity, versioning, and compatibility

1.2.2. Dynamism and lifecycle management

1.2.3. Why isn’t everyone using OSGi?

1.2.4. Why OSGi and Java EE don’t work together

1.3. Programming with enterprise OSGi

1.3.1. Enterprise OSGi and OSGi in the enterprise

1.3.2. Dependency injection

1.3.3. Java EE integration

1.4. Summary

Chapter 2. Developing a simple OSGi-based web application

2.1. The development sandbox

2.1.1. Introducing Apache Aries

2.1.2. My first enterprise OSGi runtime

2.2. Writing an OSGi web application

2.2.1. Building a simple OSGi web application bundle

2.2.2. Deploying and testing

2.2.3. A familiar feeling—and important differences

2.2.4. Spicing things up with fragments

2.3. Decoupling with dependency injection

2.3.1. Inversion of control

2.3.2. Introducing the Blueprint service

2.3.3. Coupling two components with Blueprint

2.4. Bridging JNDI and OSGi

2.5. Summary

Chapter 3. Persistence pays off

3.1. Java and persistence

3.1.1. Making persistence easy

3.1.2. The problems with traditional persistence in OSGi

3.2. Building a persistent application

3.2.1. Setting up a datasource

3.2.2. Creating a persistence bundle

3.2.3. Making use of the data

3.3. Transactions—the secret ingredient

3.3.1. What is a transaction?

3.3.2. Handling multipart transactions

3.4. Summary

Chapter 4. Packaging your enterprise OSGi applications

4.1. The need for more than modules

4.1.1. Java EE applications

4.1.2. Enterprise OSGi applications

4.2. Enterprise OSGi subsystems

4.2.1. ESA structure

4.2.2. Subsystem metadata

4.2.3. Provisioning and resolution

4.3. The Enterprise Bundle Archive (EBA)

4.3.1. Sharing and isolation

4.4. Alternative approaches

4.4.1. Spring plan and PAR files

4.4.2. Apache Karaf features

4.5. Developing an enterprise OSGi application

4.5.1. Building your metadata

4.6. Summary

2. Building better enterprise OSGi applications

Chapter 5. Best practices for enterprise applications

5.1. The benefits of sharing—and how to achieve them in your bundles

5.1.1. Versioning bundles and packages

5.1.2. Scoping your bundles

5.1.3. Why isolation is important to sharing

5.2. Structuring for flexibility

5.2.1. Separate interfaces from implementation

5.2.2. If you can’t separate out your API

5.2.3. Avoid static factory classes

5.2.4. Building a better listener with the whiteboard pattern

5.3. A better enterprise application architecture

5.3.1. Use small WABs

5.3.2. Make a persistence bundle

5.3.3. The rewards of well-written bundles

5.4. Summary

Chapter 6. Building dynamic applications with OSGi services

6.1. OSGi dynamism

6.2. Using OSGi services

6.2.1. Registering and looking up services the old-fashioned way

6.2.2. Blueprint

6.2.3. Declarative Services

6.2.4. iPojo

6.2.5. Google Guice and Peaberry

6.3. Getting the most out of Blueprint

6.3.1. Using Blueprint for things other than services

6.3.2. Values

6.3.3. Understanding bean scopes

6.3.4. Constructing beans

6.3.5. Lifecycle callbacks

6.3.6. Service ranking

6.3.7. Registering services under multiple interfaces

6.4. Blueprint and service dynamism

6.4.1. The remarkable appearing and disappearing services

6.4.2. Multiplicity and optionality

6.4.3. Monitoring the lifecycle

6.5. Summary

Chapter 7. Provisioning and resolution

7.1. Describing OSGi bundles

7.1.1. Describing bundles as resources

7.1.2. Requirements and capabilities

7.1.3. Directives affecting the resolver

7.1.4. Repositories

7.2. Provisioning bundles

7.2.1. Package-based provisioning

7.2.2. Service-based provisioning

7.3. Provisioning technologies

7.3.1. Apache Felix OBR

7.3.2. Equinox p2

7.3.3. Apache ACE

7.3.4. Standard OSGi repositories

7.4. Bundle repositories

7.4.1. Public bundle repositories

7.4.2. Building your own repository

7.4.3. Generating your repository

7.5. Summary

Chapter 8. Tools for building and testing

8.1. Manifest-first or code-first?

8.2. Building OSGi applications

8.2.1. Bnd

8.2.2. The Maven bundle plug-in

8.2.3. Ant and Eclipse PDE

8.2.4. Maven Tycho

8.2.5. The Maven EBA plug-in

8.3. Testing OSGi applications

8.3.1. Unit testing OSGi

8.3.2. Pax Exam

8.3.3. Tycho test

8.3.4. Rolling your own test framework

8.4. Collecting coverage data

8.4.1. Getting coverage tools onto the classpath

8.5. Summary

Chapter 9. IDE development tools

9.1. Eclipse-based OSGi development

9.1.1. Eclipse Plug-in Development Environment

9.1.2. Extending bnd into the GUI world with bndtools

9.2. OSGi support in other IDEs

9.2.1. NetBeans

9.2.2. Osmorc and IntelliJ IDEA

9.2.3. Do you need OSGi support in your IDE?

9.3. Tools for the enterprise OSGi extensions

9.3.1. IBM Rational Development Tools for OSGi Applications

9.3.2. Eclipse Libra

9.4. Testing OSGi applications inside IDEs

9.4.1. Testing with Eclipse PDE

9.4.2. Testing with bndtools

9.4.3. Pax Exam

9.5. Summary

3. Integrating enterprise OSGi with everything else

Chapter 10. Hooking up remote systems with distributed OSGi

10.1. The principles of remoting

10.1.1. The benefits of remoting

10.1.2. The drawbacks of remoting

10.1.3. Good practices and the fallacies of remoting

10.2. The Remote Services Specification

10.2.1. Exposing endpoints

10.2.2. Discovering endpoints

10.3. Writing a remotable service

10.3.1. Coding a special offer service

10.4. Adding in your remote service using Apache CXF

10.4.1. Making your service available

10.4.2. Discovering remote services from your superstore

10.5. Using your remote application

10.5.1. Setting up your remote database connections

10.6. Using SCA for remoting

10.6.1. Apache Tuscany

10.6.2. Importing a remote service

10.6.3. Exporting remote services

10.6.4. Interfaces and services

10.7. Summary

Chapter 11. Migration and integration

11.1. Managing heterogeneous applications

11.1.1. Using SCA to integrate heterogeneous systems

11.1.2. Integrating using an ESB

11.2. Migrating from Java EE

11.2.1. Moving from WARs to WABs

11.2.2. Using persistence bundles

11.2.3. EJBs in OSGi

11.2.4. Moving to Blueprint from the Spring Framework

11.3. Summary

Chapter 12. Coping with the non-OSGi world

12.1. Turning normal JARs into OSGi bundles

12.1.1. Finding bundled libraries

12.1.2. Building your own bundles

12.1.3. Generating bundles automatically

12.2. Common problems for OSGi-unaware libraries

12.2.1. Reflection in OSGi

12.2.2. Using and abusing the thread context ClassLoader

12.2.3. META-INF services

12.2.4. Serialization and deserialization

12.3. An example library conversion—logging frameworks in OSGi

12.3.1. Common problems with loggers in OSGi

12.3.2. Avoiding problems in OSGi

12.3.3. DynamicImport-Package—a saving grace?

12.3.4. Other problems that are more difficult to fix

12.4. Summary

Chapter 13. Choosing a stack

13.1. What’s in what server?

13.2. Apache Karaf

13.2.1. Karaf features

13.2.2. Installing Aries into Karaf

13.2.3. Handling non-OSGi bundles

13.2.4. Blueprint-aware console

13.3. Apache Geronimo

13.4. WebSphere Application Server

13.4.1. Provisioning and bundle repositories

13.4.2. Module granularity

13.4.3. Managed application update and extension

13.4.4. SCA

13.5. Eclipse Virgo and Gemini

13.5.1. Debug support

13.5.2. Application isolation

13.6. GlassFish

13.6.1. Dependency injection

13.6.2. EJBs

13.6.3. Administration

13.7. JBoss

13.8. Paremus Nimble and Paremus Service Fabric

13.8.1. Provisioning and deployment

13.8.2. Remote services

13.8.3. Console

13.8.4. Installing Aries

13.9. Summary

Appendix A. OSGi—the basics

A.1. Where did OSGi come from, and where is it going?

A.2. Versions

A.2.1. The semantic versioning scheme

A.2.2. Guarantees of compatibility

A.2.3. Coexistence of implementations

A.2.4. Why everything has a version

A.2.5. Consumers and providers, not clients and implementors

A.2.6. Semantic versions and marketing versions

A.3. Bundles

A.3.1. Manifest headers

A.3.2. The bundle context

A.3.3. Dependency management

A.3.4. Classloading

A.3.5. Fragments

A.4. Bundle lifecycles

A.4.1. Activation policies

A.4.2. Bundle activators

A.4.3. Installation and resolution

A.4.4. Starting and stopping bundles

A.4.5. Uninstalling and updating bundles

A.4.6. Managing dependencies in a dynamic system

A.5. Services

A.5.1. The Service Registry

A.5.2. Accessing services

A.5.3. Filters

A.6. OSGi frameworks

A.7. The OSGi console

A.8. Summary

Appendix B. The OSGi ecosystem

B.1. The OSGi Alliance

The Core Platform Expert Group

The Enterprise Expert Group

B.2. OSGi specifications

B.2.1. The Core Specification

B.2.2. The Compendium Specification

B.2.3. The Enterprise Specification

B.2.4. Other specifications

B.3. OSGi—future frontiers

B.3.1. OSGi and Jigsaw

Index

List of Figures

List of Tables

List of Listings

Preface

I first used Java EE many years ago, in 2002. (Yes, Stateless Session Beans and Passivated Entity Beans, stop hiding at the back—I’m talking to you.) I can’t remember when I started using OSGi, but it was also a long time ago. Nonetheless, until recently, I’d never used the two technologies at the same time. If I was writing a desktop application or an application server (as one does), I used OSGi. If I was writing a web application, I used Java EE.

But OSGi seemed the most natural way to develop a working system. When I was writing Java EE applications, the thought of leaving my dependencies to chance or exposing all the internals of my JARs made me pretty uneasy. It felt downright icky. What if classes I needed weren’t on the classpath when my application was deployed? What if the classes I needed were there, but the version was incompatible with the one I used when I was developing? What if a colleague coded against one of my internal classes, and then I refactored and deleted it? What if I accidentally coded against the internals of a library I was using? And wasn’t there a cleaner way to get hold of interface implementations than the reflective factory pattern? Applications might work in the short term, but it felt like an accident waiting to happen.

For a long time, Java EE developers didn’t have much choice except to close their eyes, hold tight, and wait for the accident. It’s not that they didn’t want to use OSGi—they couldn’t. OSGi didn’t play well with the Java EE programming model. OSGi’s tightly modularized classpath wasn’t compatible with the discovery mechanism for Java EE services, which assumed global visibility. Similarly, many of the Java EE implementations relied on classloading tricks to do their work, and these tricks failed miserably in the more controlled OSGi environment.

In 2009, I heard Zoe Slattery give a talk on a new Apache incubator, Apache Aries. Aries promised to allow Java EE technologies to work in an OSGi environment. It wasn’t reinventing the Java EE wheel, just allowing Java EE developers to take advantage of OSGi. I thought it was cool—and desperately needed. A few months later, I was signed up to help develop Aries and the IBM WebSphere feature pack built on top of it.

As well as developing Aries itself, I was speaking at conferences about enterprise OSGi. Manning contacted me and asked me if I’d be interested in writing a book on the subject. I was excited by the idea, but scared—after all, there were lots of people who’d been working with enterprise OSGi for much longer than I had. What I did have was insight into what people learning enterprise OSGi needed to know. After all, I’d had lots of the same questions and made lots of the same mistakes myself pretty recently.

But it was clear that reinforcements would be required. This is where Tim Ward came in. Tim is one of the brightest guys I know, and I was delighted when he said he was interested in the book. Tim was one of the first developers to prototype the early implementations of the OSGi Enterprise Specifications, and he’s been working with enterprise OSGi ever since. Even better, he’s coauthored some of the specifications. There isn’t much about enterprise OSGi that Tim doesn’t know. Although my name is first on the cover (thank you, alphabet!) this book is authored by both of us equally.

Writing this book has been a great adventure. We hope you enjoy it and find it useful, and we’d love to hear from you on the Manning Author Online forum.

HOLLY CUMMINS

Acknowledgments

Where do we even start in thanking all the people who made this book possible? You fed us, encouraged us, and taught us. Going back to the beginning, this project wouldn’t even have gotten off the ground without the good folks at Manning. Thanks to Marjan Bace, our publisher, Michael Stephens, our editor, and Sebastian Stirling and Frank Pohlmann, our development editors. You helped us figure out what makes a good book and guided, coaxed, and nudged us in the right direction. Thanks also to Christina Rudloff and Nick Chase.

The quality of this book has been hugely improved by the detailed comments we received from our reviewers. We really appreciate you taking the time to read our efforts and tell us what we got right and wrong. Thanks to Alasdair Nottingham, Andrew Johnson, Charles Moulliard, David Bosschaert, Felix Meschberger, John W. Ross, Kevin Sheehan, Kin Chuen, Tang, Marcel Offermans, Mirko Jahn, Paul Flory, Pierre De Rop, Teemu Kanstrén, and Tim Diekmann.

Thanks also to everyone who participated in the Manning Early Access Program. Special thanks to our technical proofer, Mark Nuttall, who went over the book several times with an eagle eye, and was patient with silly mistakes and last-minute improvements.

We couldn’t have written this book without the help of our colleagues at IBM. Thank you, Ian Robinson. Without your vision and commitment, it’s likely that neither of us would have had the opportunity to work so closely with enterprise OSGi. Thanks to Andy Gatford and Nickie Hills for supporting us. We’d like to thank Jeremy Hughes, Alasdair Nottingham, Graham Charters, Zoe Slattery, Valentin Mahrwald, Emily Jiang, Tim Mitchell, Chris Wilkinson, Richard Ellis, Duane Appleby, and Erin Schnabel for the many valuable discussions we shared with them.

We borrowed the phrase bundle flake from Alex Mulholland, who deserves credit for bringing the fun back into debugging OSGi fragments. We’d also like to give special mention to Sarah Burwood, who possibly didn’t realize what she’d signed up for when she offered to review the book as an OSGi beginner! We’ve learned loads from all of you, so thank you.

In addition to our IBM colleagues, we thank the members of the OSGi Alliance Expert Groups and Apache Aries. You put up with our ideas and questions and built the enterprise OSGi programming model with us, many of you donating your time to do so. There are too many names to even begin to list here, but particular thanks are deserved by Peter Kriens and David Bosschaert, both for direct help with the book and for their years of support building the OSGi Enterprise Specifications.

On a personal level, we’re indebted to our partners, Paul and Ruth, who picked up a great deal of domestic slack, as well as provided apparently limitless encouragement and support. At the times when this book didn’t seem possible, you persuaded us it was (and then fed us a snack). Holly would like to apologize to Paul for the six application servers and four IDEs now installed on his laptop; everyone knows not to let software engineers touch one’s computer! Tim would like to apologize to Ruth for all the times that I just need to finish this paragraph took rather longer than the implied five minutes; it turns out that writing prose is more like writing code than you might think...

Tim would like to thank the rest of his immediate family, Pauline, Gareth, Ron, Eve, Sarah, and Maurice, for their interest and their unwavering belief that not only would the book eventually be finished, but that it would also be worth reading. He also thanks them for helping him remember to bring the funny. He’s sure many of the readers will want to thank them for that, too.

Holly would also like to thank her mom, dad, John, Ioana, Heather, and Phil for helping her find the time and space for writing. Acknowledgment is also owed to Laurie Hodkinson, who has spent many hours helping write this book, and occasionally throwing up on the keyboard. Holly has every expectation that his first word will be OSGi.

As with many books, some of the people and things that helped make it possible probably aren’t even aware of their contribution. The writing of this book was fueled by coffee—lots of coffee—and cheese. Holly would like to thank the makers of her Beco Gemini baby carrier, which is essentially a concurrency framework for infants. Tim would like to thank the makers of his Vi-Spring mattress, which is essentially the cure to hunching over a laptop all day.

Finally, our thanks wouldn’t be complete without thanking you, the readers, for buying our book. We hope that you enjoy it, and that maybe you’ll end up liking OSGi just as much as we do.

About this Book

This is a book about the enterprise OSGi programming model, and it’s also a book about using OSGi in the enterprise. It shows you how to combine OSGi’s elegant, modular, service-oriented approach with Java EE’s well-established persistence, transaction, and web technologies. It guides you through the cases when your project has lots of bits spread all over the network, some new, some old, some that you don’t even recognize, and many that you didn’t write yourself. It’s packed with tips on how to use OSGi in the messy real world, with guidance on tools, building, testing, and integrating with non-OSGi systems and libraries.

Audience

Three groups of developers should find this book interesting. The first is developers who know Java EE, but who want to bring more modularity to their applications by learning OSGi. The second is those who know OSGi, but want to learn how to take advantage of some of Java EE’s higher-level programming models. The last is developers who are familiar with both Java EE and OSGi, but who never knew the two could be combined! We don’t assume knowledge of either Java EE or OSGi, but familiarity with at least one of them will help.

Roadmap

This book is divided into three parts. Part 1 introduces the most important enterprise OSGi technologies: web applications, JNDI lookups of OSGi services, Blueprint dependency injection, JPA persistence, declarative transactions, and application packaging. Part 2 explains how to use these building blocks most effectively with best practices, tools, and a deeper understanding of some subtle areas. Part 3 considers how enterprise OSGi fits in with your existing applications and systems. It covers distribution technologies, migration tips and traps, and server options.

The appendixes provide important OSGi background. If you’re new to OSGi, you may want to skip to the appendixes after reading chapter 1.

Chapter 1 explains what OSGi is, why it’s such an exciting technology, and why it’s so relevant to the enterprise.

Chapter 2 lets you get your hands dirty with real code. It introduces the OSGi sandbox you’ll use to run the samples. You’ll write an OSGi web application and hook it up to backend OSGi services. You’ll use JNDI to connect OSGi services to legacy code, and Blueprint dependency injection to wire together the services.

Chapter 3 introduces JPA persistence and JTA transactions, and shows how to use them in an OSGi environment.

Chapter 4 shows how to group OSGi bundles together into coarser-grained applications.

In part 2, chapter 5 steps back from new technologies and discusses best practices for writing enterprise OSGi applications. It explains how to structure your applications, introduces some new OSGi-centric patterns, and discusses which familiar patterns may not be such a great idea in an OSGi environment.

Chapter 6 investigates OSGi dynamism and Blueprint dependency injection in more depth.

Chapter 7 discusses how to use OBR to dynamically provision application dependencies.

Chapter 8 introduces a range of command-line tools for generating OSGi manifests and building bundles. It also considers how to test OSGi bundles.

Chapter 9 continues the discussion of useful tools by comparing several IDEs that support OSGi.

In part 3, chapter 10 explains how to use distributed OSGi to allow OSGi services to be published and consumed across remote systems.

Chapter 11 discusses your options for migrating non-OSGi legacy code to OSGi. It also discusses technologies for integrating OSGi applications with the non-OSGi legacy code you haven’t yet migrated!

Chapter 12 sets out strategies for handling non-OSGi libraries. It shows how to turn ordinary JARs into bundles and explains how to deal with common problems, such as classloading and logging issues.

Finally, chapter 13 compares the various commercial and open source OSGi runtimes and gives guidance on how you should choose a stack that’s right for you.

Appendix A covers the basics of OSGi. It explains why OSGi is such a necessary technology, and provides grounding in versioning, bundles, bundle lifecycles, and OSGi services. It includes some practical hints on OSGi frameworks and consoles.

Appendix B describes the broader OSGi ecosystem. It explains how the OSGi alliance works and what’s in the various OSGi specifications.

Code downloads

You can download the sample code for this book via a link found on the book’s homepage on the Manning website, www.manning.com/EnterpriseOSGiinAction. The SourceCodeEnterpriseOSGiinAction.zip archive includes source code for an application with a web frontend and a JPA backend, as well as distributed variations. There’s a Maven build that produces bundles and a .eba application that can be installed into an OSGi framework. See section 2.1.2 for instructions on how to assemble a runtime environment in which to run the application.

Author Online

The purchase of Enterprise OSGi in Action includes free access to a forum run by Manning Publications where you can make comments about the book, ask technical questions, and receive help from the authors and other users. You can access and subscribe to the forum at www.manning.com/EnterpriseOSGiinAction. This page provides information on how to get on the forum once you’ve registered, what kind of help is available, and the rules of conduct in the forum.

Manning’s commitment to our readers is to provide a venue where a meaningful dialog between individual readers, and between readers and the authors, can take place. It isn’t a commitment to any specific amount of participation on the part of the authors, whose contributions to the book’s forum remain voluntary (and unpaid). We suggest you try asking the authors some challenging questions, lest their interest stray!

The Author Online forum and the archives of previous discussions will be accessible from the publisher’s website as long as the book is in print.

About the Authors

HOLLY CUMMINS has been developing Java applications for a decade. She is an advisory software engineer with IBM, where she has worked on the development of the WebSphere Application Server and on Java performance. She is also a committer on the Apache Aries project and speaks widely at conferences.

TIM WARD is a senior software engineer at Zühlke Engineering. Previously, he was a design and development lead for IBM’s OSGi Applications support in WebSphere. He’s on the OSGi Alliance Core Platform and Enterprise Expert Groups and is a member of the Project Management Committee for the Apache Aries project.

About the Cover Illustration

The figure on the cover of Enterprise OSGi in Action is captioned a Man from Slovania. This illustration is taken from a recent reprint of Balthasar Hacquet’s Images and Descriptions of Southwestern and Eastern Wenda, Illyrians, and Slavs, published by the Ethnographic Museum in Split, Croatia, in 2008. Hacquet (1739–1815) was an Austrian physician and scientist who spent many years studying the botany, geology, and ethnography of many parts of the Austrian Empire, as well as the Veneto, the Julian Alps, and the western Balkans, inhabited in the past by peoples of many different tribes and nationalities. Hand-drawn illustrations accompany the many scientific papers and books that Hacquet published.

Slavonia is a historical region in eastern Croatia. Part of the Roman Empire until the fifth century, then part of Pannonian Croatia, subsequently ruled by Hungary, the Ottomans, and the Hapsburgs, Slavonia was briefly an independent entity until it became a part of Yugoslavia after World War II. Today Slavonia encompasses five counties in inland Croatia with a population of almost one million inhabitants.

The rich diversity of the drawings in Hacquet’s publications speaks vividly of the uniqueness and individuality of Alpine and Balkan regions just 200 years ago. This was a time when the dress codes of two villages separated by a few miles identified people uniquely as belonging to one or the other, and when members of an ethnic tribe, social class, or trade could be easily distinguished by what they were wearing. Dress codes have changed since then and the diversity by region, so rich at the time, has faded away. It is now often hard to tell the inhabitant of one continent from another and the residents of the picturesque towns and villages in the Balkans are not readily distinguishable from people who live in other parts of the world.

We at Manning celebrate the inventiveness, the initiative, and the fun of the computer business with book covers based on costumes from two centuries ago brought back to life by illustrations such as this one.

Part 1. Programming beyond Hello World

Welcome to enterprise OSGi! In this first part, you’ll get a feel for the modularity of OSGi bundles, programming web applications, accessing data in a database, controlling the flow of transactions, and packaging bundles into a single unit.

Chapter 1 starts off gently by introducing OSGi and explaining why modularity—which is what OSGi provides—is so important.

If you’re itching to get coding, don’t worry. Chapter 2 shows you how to develop your first enterprise OSGi application. You’ll write a modular web application and connect it to OSGi services using JNDI and Blueprint dependency injection.

Having mastered the frontend, what about the backend? Chapter 3 shows you how to use JPA persistence and JTA transactions in an OSGi environment.

Chapter 4 discusses how to package OSGi bundles together into OSGi applications.

By the time you’ve finished reading this part, you’ll be able to write your own enterprise OSGi application, with a web frontend and a transactional database backend. It will be loosely coupled and nicely modularized. And best of all—writing it will be easy!

Chapter 1. OSGi and the enterprise—why now?

This chapter covers

Why modularity is important, and how Java stacks up

How OSGi enforces some simple rules to make Java better at modularity

Why enterprise Java and OSGi traditionally don’t play well together

How enterprise OSGi fixes this, and what the enterprise OSGi programming model looks like

Enterprise OSGi combines two of Java’s most enduringly popular programming models: enterprise Java and OSGi. Enterprise Java is a loosely defined set of libraries, APIs, and frameworks built on top of core Java that turn it into a powerful platform for distributed, transactional, interactive, and persistent applications. Enterprise Java has been hugely successful, but as the scale and complexity of enterprise Java applications have grown, they’ve started to look creaky, bloated, and monolithic. OSGi applications, on the other hand, tend to be compact, modular, and maintainable. But the OSGi programming model is pretty low-level. It doesn’t have much to say about transactions, persistence, or web pages, all of which are essential underpinnings for many modern Java programs. What about a combination, something with the best features of both enterprise Java and OSGi? Such a programming model would enable applications that are modular, maintainable, and take advantage of industry standard enterprise Java libraries. Until recently, this combination was almost impossible, because enterprise Java and OSGi didn’t work together. Now they do, and we hope you’ll agree with us that the merger is pretty exciting.

We’ll start by taking a look at what modularity is, and why it’s so important in software engineering.

1.1. Java’s missing modularity

When it was first introduced, in 1995, Java technology represented an enormous leap forward in software engineering. Compared to what had gone before, Java allowed more encapsulation, more abstraction, more modularity, and more dynamism.

A decade later, some gaps were beginning to show. In particular, the development community was desperate for more encapsulation, more abstraction, more modularity, and more dynamism. Java’s flat classpath structure wasn’t scaling well for the massive applications it was now being used for. Developers found that, when deployed, their applications picked up a bunch of classes from the classpath that they didn’t want, but were missing some classes that they needed. In figure 1.1, you can see an example of a typical Java classpath.

Figure 1.1. Conventional Java has a flat classpath which is searched in a linear order. For large applications, this classpath can be long, and searches can be time consuming. If a class occurs more than once on the classpath, only the first instance is used—even if the second copy is better.

It was impossible to keep component internals private, which led to constant arguments between developers (angry that the function they relied on had been changed) and their counterparts, who were annoyed that developers had been coding against things that were intended to be private. After 10 years of continuous development, there was an urgent need to be able to label the many iterations of Java code that were out there with some sort of versioning scheme. Core Java was starting to feel pretty tightly coupled and undynamic.

Doesn’t Java’s object orientation enable modularity? Well, yes and no. Java does a great job of providing modularity at the class and package level. Methods and class variables can be declared public, or access can be restricted to the owning class, its descendants, or members of its package. Beyond this, there’s little facility for modularity. Classes may be packaged together in a Java Archive (JAR), but the JAR provides no encapsulation. Every class inside the JAR is externally accessible, no matter how internal its intended use.

One of the reasons modularity has become increasingly necessary is the scale of modern computer programs. They’re developed by globally dispersed teams and can occupy several gigabytes of disk space. In this kind of environment, it’s critical that code can be grouped into distinct modules, with clearly delineated areas of responsibility and well-defined interfaces between modules.

Another significant change to software engineering within the last decade is the emergence of open source. Almost every software need can now be satisfied by open source. There are large-scale products, such as application servers, IDEs, databases, and messaging engines. A bewildering range of open source projects that address particular development needs, from Java bytecode generation to web presentation layers, is also available. Because the projects are open source, they can easily be reused by other software. As a result, most programs now rely on some open source libraries. Even commercial software often uses open source componentry; numerous GUI applications, for example, are based on the Eclipse Rich Client Platform, and many application servers incorporate the Apache Web Server.

The increasing scale of software engineering projects and the increasing availability of tempting open source libraries have made modularization essential. Stepping back, what exactly do we mean by modularity, and what problems does it fix?

1.1.1. Thinking about modularity

Modularity is one of the most important design goals in modern software engineering. It reduces effort spent duplicating function and improves the stability of software over time.

Spaghetti Code

We’ve all heard code that’s too coupled and interdependent described as spaghetti code (figure 1.2).

Figure 1.2. A highly interconnected spaghetti application with little structure. The solid lines represent dependencies that are identifiable at both compile-time and runtime, whereas the dotted lines are runtime-only dependencies. This sort of dependency graph is typical of procedural languages.

This sort of code is unfortunately common—both in open and closed source projects—and is universally despised. Not only is code like this hard to read and even harder to maintain, it’s also difficult to make even slight changes to its structure or move it to a new system. Even a slight breeze can be enough to cause problems! Given how strongly people dislike this sort of code, it should be a lot less common than it is, but, sadly, in a world where nothing stops you from calling any other function, it’s easy to write spaghetti by accident. The other problem with spaghetti is that, as soon as you have some, it tends to generate more quickly. . .

Object orientation marked a big shift in the development of programming languages, providing a strong level of encapsulation in them. Objects were responsible for maintaining their internal, private state, and could have internal, private methods. It was believed that this would mark the end of spaghetti code, and to an extent it did.

Extending the spaghetti metaphor, conventional Java programs (or any other object-oriented language, for that matter) can be thought of as object minestrone (figure 1.3)—although there’s a distinct object structure (the chunks of vegetable and pasta), there’s no structure beyond the individual objects. The objects are thrown together in a soup and every vegetable can see every other vegetable.

Figure 1.3. An application with no structure beyond individual well-encapsulated objects (connections between objects aren’t shown). This sort of structure is typical of object-oriented languages. Although the objects themselves are highly modular, there’s no more granular modularity.

Classpath Hell

Insufficient encapsulation isn’t the only problem with Java’s existing modularity. Few Java JARs are entirely freestanding; most will have dependencies on some other libraries or frameworks. Unfortunately, determining what these dependencies are is often a matter of trial and error. Inevitably, some dependencies may get left off the classpath when it’s run. In the best case, this omission will be discovered early when a ClassNotFoundException is thrown. In the worst case, the code path will be rarely traveled and the problem won’t be discovered until weeks later when a ClassNotFoundException interrupts some particularly business-critical operation. Good documentation of dependencies can help here, but the only reliable way of ensuring every dependency is present is to package them all up in a single archive with the original JAR. This is inefficient and it’s extra frustrating to have to do it for common dependencies.

What’s worse, even packaging JARs with all the other JARs they depend on isn’t guaranteed to make running an application a happy experience. What if a dependency is one of the common ones—so common that other applications running in the same JVM (Java Virtual Machine) depend on it? This is fine, as long as the required versions are the same. One copy will come first on the classpath and be loaded, and the other copy will be ignored. What happens when the required versions are different? One copy will still be loaded, and the other will still be ignored. One application will run with the version it expects, and the other won’t. In some cases, the losing application may terminate with a NoSuchMethodError because it invokes methods that no longer exist. In other, worse cases, there will be no obvious exceptions but the application won’t behave correctly. These issues are incredibly unpleasant and in Java have been given the rather self-explanatory name classpath hell.

Although classpath hell is a bad problem in core Java, it’s even more pernicious in the enterprise Java domain.

1.1.2. Enterprise Java and modularity—even worse!

Enterprise Java and the Java EE programming model are used by a large number of developers; however, there are many Java developers who have no experience with either. Before we can explain why enterprise Java suffers even more greatly than standard Java, we need to make sure that we have a common understanding of what the enterprise is.

What Distinguishes Enterprise Java from Normal Everyday Java?

Part of the distinction is the involvement of the enterprise—enterprise Java is used to produce applications used by businesses. But then businesses use many other applications, like word processors and spreadsheets. You certainly wouldn’t say that a word processor, no matter how business-oriented, had been produced to an enterprise programming model. Similarly, many enterprise programmers don’t work for particularly large corporations.

What’s different about enterprise applications? In general, they’re designed to support multiple simultaneous users. With multiple users, some sort of remote access is usually required—having 50 users crammed into a single room isn’t going to make anyone happy! Nowadays, remote access almost always means a web frontend.

To store the information associated with these users, enterprise applications usually persist data. Writing database access code isn’t much fun, so persistence providers supply a nicer set of interfaces to manage the interaction between the application code and the database.

This is a business application, and so transactions are usually involved—either buying and selling of goods and services, or some other business agreements. To ensure these real transactions proceed smoothly and consistently, even in the event of a communications problem, software transactions are used.

With all this going on, these enterprise applications are starting to get pretty complex. They’re not going to fit into a single Java class, or a single JAR file. It may not even be practical to run every part on a single server. Distribution allows the code, and therefore the work, to be spread across multiple servers on a network. Some people argue that distribution is the key feature of what’s known as enterprise computing, and the other elements, like transactions and the web, are merely there to facilitate distribution (like the web) or to handle some of the consequences of distribution on networks which aren’t necessarily reliable (such as transactions).

Java EE provides a fairly comprehensive set of standards designed to fit the scaling and distribution requirements of these enterprise applications, and is widely used throughout enterprise application development.

Modular Java EE—Bigger Isn’t Better

Our enterprise application is now running across multiple servers, with a web frontend, a persistence component, and a transaction component. How all the pieces fit together may not be known by individual developers when they’re writing their code. Which persistence provider will be used? What about the transaction provider? What if they change vendors next year? Java EE needs modularity for its applications even more than base Java does. Running on different servers means that the classpath, available dependencies, and technology implementations are likely to diverge. This becomes even more likely as the application is spread over more and more systems.

With these interconnected applications, it’s much better for developers to avoid specifying where all their dependencies come from and how they’re constructed. Otherwise the parts of the application become so closely coupled to one another that changing any of them becomes difficult. In the case of a little program, this close coupling would be called spaghetti code (see figure 1.2 again). In large applications, it’s sometimes known as the big ball of mud. In any case, the pattern is equally awkward and the consequences can be just as severe.

Unfortunately for Java EE, there’s no basic Java modularity to fall back on; the modules within a Java application often spaghettify between one another, and inevitably their open source library dependencies have to be packaged within the applications. To improve cost effectiveness, each server in a Java EE environment typically hosts multiple applications, each of which packages its own dependencies, and potentially requires a different implementation of a particular enterprise service. This is a clear recipe for classpath hell, but the situation is even worse than it first appears. The Java EE application servers themselves are large, complicated pieces of software, and even the best of them contain a little spaghetti. To reliably provide basic functions at low development cost, they also depend on open source libraries, many of the same libraries used by the applications that run on the application server! This is a serious problem,