Updated Aug 08, 2009 by mcculls
Labels:	Featured, Phase-Deploy

UserGuide

Guide for using the peaberry bundle with OSGi.

Eclipse/PDE Example - Text Scrambling Service

download and unzip the example
import the contents into Eclipse as existing projects
open peaberry.target and set it as the target platform:

right-click on peaberry.launch and select Run As... -> peaberry:

you should see both bundles start and produce scrambled output:

try stopping and starting the service bundle using the console

Useful Console Commands

ss       -  list all bundles
stop n   -  stop bundle #n
start n  -  start bundle #n
diag n   -  diagnose bundle

Installing the OSGi binding module

 // provides bindings for the current bundle context + OSGi service registry
 Injector injector = Guice.createInjector(osgiModule(bundleContext), ...);

Fluent API Examples

The following static imports were used to simplify the examples

import static org.ops4j.peaberry.Peaberry.osgiModule;
import static org.ops4j.peaberry.Peaberry.service;

import static org.ops4j.peaberry.util.TypeLiterals.export;
import static org.ops4j.peaberry.util.TypeLiterals.iterable;

import static org.ops4j.peaberry.util.Attributes.names;
import static org.ops4j.peaberry.util.Filters.ldap;

Injecting a stock quote service:

 @Inject
 StockQuote quote;
 ...
 bind(StockQuote.class).toProvider(service(StockQuote.class).single());

Injecting many stock quote services:

 @Inject
 Iterable<StockQuote> quotes;
 ...
 bind(iterable(StockQuote.class)).toProvider(service(StockQuote.class).multiple());

Exporting an implementation as a stock quote service:

 @Inject
 // the service can be controlled by the Export handle
 Export<StockQuote> exportedQuote;
 ...
 // the service is exported at injection time
 bind(export(StockQuote.class)).toProvider(service(myQuoteImpl).export());

Applying a custom filter to find a specific service:

 service(StockQuote.class).filter(ldap("(Currency=GBP)")).single()

Applying custom attributes to an exported service:

 service(myQuoteImpl).attributes(names("Currency=GBP")).export()

(the ldap and names utility methods are from org.ops4j.peaberry.util)

You can also decorate services with additional behaviour:

 service(StockQuote.class).decoratedWith(someDecoratorImpl).single()

or ask for them to be injected directly, instead of using a dynamic proxy:

 service(StockQuote.class).single().direct()

 service(myQuoteImpl).export().direct()

You can use your own registry implementation, instead of the default binding:

 service(StockQuote.class).in(myRegistryImpl).single()

And you can now actively watch for changes in the services you inject:

 bind(StockQuote.class).toProvider(service(StockQuote.class).out(new AbstractWatcher<StockQuote>() {

  @Override
  protected StockQuote adding(Import<StockQuote> service) {
   // the returned object is used in the modified and removed calls
   StockQuote instance = service.get();
   System.out.println("ADDING:" + instance);
   return instance;
  }

  @Override
  protected void modified(StockQuote instance, Map<String, ?> attributes) {
   System.out.println("MODIFIED:" + instance);
  }

  @Override
  protected void removed(StockQuote instance) {
   System.out.println("REMOVED:" + instance);
  }
 }).multiple());

AbstractWatcher is a utility class to make implementing ServiceWatcher a bit easier.

Comment by akollegger, Jan 17, 2009

Are the examples in the user guide up-to-date? It seems to me that the to() calls should be toProvider()

Comment by mcculls, Jan 20, 2009

Thanks for spotting that Andreas, glad someone reads these pages!

Comment by plalloni, Jan 29, 2009

You mean there's something else to read (other than code/examples)? ;)

Now, really... am I missing something?

Comment by akollegger, Jan 29, 2009

It all looks to be corrected, so you're not missing anything for now. Unless you mean some non-code for your reading list, for which I'd recommend the upcoming "Pride and Prejudice and Zombies."

Comment by mcculls, Jan 30, 2009

Yep, the code + wiki is all you get at the moment ;) of course if there's anything missing (apart from period dramas involving zombies!) feel free to raise an issue or email the group...

Comment by masson.aurelien, May 29, 2009

Hi, I'm having some problems using Peaberry to inject services between several eclipse plugins. Briefly, I have 4 plugins: one for an editor, one for service interfaces and two for service implementations. I'd like to inject a chosen implementation to my editor using peaberry. Is there a place where I can expose the problem and ask for help? Thanks.

Comment by mcculls, May 29, 2009

We have a group for Guice-on-OSGi related questions: http://groups.google.com/group/guice-osgi guice-osgi@googlegroups.com (there's a link on the main page)

Testcases really help when debugging, otherwise please provide as much info as possible upfront as it means less to-and-fro on the email and hopefully a fast resolution ;)

Comment by markus.w...@gmail.com, Aug 08, 2009

I think it should read "3. open peaberry.target ..."

Comment by mcculls, Aug 08, 2009

Fixed, thanks