h1. WARNING : this project is no longer updated

the project has moved to "https://github.com/weld/core":https://github.com/weld/core on the master (environments/osgi) branch. This project is only used for wiki and issues tracker about Weld-OSGi.

If you want to use and hack Weld-OSGi, please fork "https://github.com/weld/core":https://github.com/weld/core

You can find actual documentation at : "http://mathieuancelin.github.com/weld-osgi/":http://mathieuancelin.github.com/weld-osgi/

h1. Weld OSGi integration

This project aims to provide an OSGi integration for Weld. This project will take full advantage of OSGi like frameworks such as iPojo, Blueprint, SCR, Peaberry, etc ...

h3. How does it works

!https://github.com/mathieuancelin/weld-osgi/raw/master/images/diagrams.png!

h3. How to use it

First of all, you will need to install and start the Weld/OSGi bundle in your OSGi environment. Then you can write a standard OSGi bundle with a valid manifest (You don't need to write an activator or anything else). To enable Weld for this bundle, you need to create a beans.xml file in the META-INF folder.

• to make an auto startable bean, just catch the BundleContainerInitialized event :

  
  public void onStartup(@Observes BundleContainerInitialized event) {}
  

• to do stuff on bundle shutdown, just catch the BundleContainerShutdown event :

  
  public void onShutdown(@Observes BundleContainerShutdown event) {}
  

• to publish a bean as an OSGi service, add the @Publish annotation on it.

  
  @Publish
  @ApplicationScoped
  public class MyServiceImpl implements MyService {
  @Overrides
  public void doSomething() { ... }
  }
  

• to inject an OSGi service, use the @OSGiService qualifier. You can also use the OSGi service provider :

  
  // direct injection 
  @Inject @OSGiService MyService service;
  ...
  service.doSomething();
  ... 
  // provider injection
  @Inject Service myService;
  ...
  myService.get().doSomething();
  

  you can also filter service with :

  
  @Inject @OSGiService @Filter("(&(lang=EN)(country=US))") MyService service;
  ...
  @Inject @Filter("(&(lang=EN)(country=US))") Service service;
  ... 
  

• to inject multiple OSGi services (whiteboard pattern), also use the OSGi service provider :

  
  @Inject Service myServices;
  ... 
  // print number of available services
  logger.log(myServices.size());
  ...
  for (MyService myService : myServices) {
  myService.doSomething();
  }
  

  you can also filter services with :

  
  @Inject @Filter("(&(lang=EN)(country=US))") Service myServices;
  ... 
  

• if you absolutely need certain OSGi services to run your application, you can mark them as Required. Then when the required services will be registered in OSGi service registry, the Valid event will be raised so you can catch it and launch your app. When the required services will be unregistered from OSGi service registry, the Invalid event will be raised.

  
  @Inject @OSGiService @Required MyService service;
  ...
  @Inject @Required Service myService;
  ...
  public void validate(@Observes Valid event) {
  // start application here
  }
  ...
  public void invalidate(@Observes Invalid event) {
  // stop application here
  }
  

• to deal with the dynamism of OSGi bundles, you can catch bundle events (extender pattern) :

  
  public void bindBundle(@Observes BundleInstalled event) {}
  public void unbindBundle(@Observes BundleUninstalled event) {}
  ...
  

  you can also filter event for specific bundles :

   
  public void bindService(@Observes @BundleName("com.sample.gui") BundleInstalled event) {}
  public void bindService(@Observes @BundleVersion("4.2.1") BundleInstalled event) {}
  public void bindService(@Observes @BundleName("com.sample.gui") @BundleVersion("4.2.1") BundleInstalled event) {}
  

• to deal with the dynamism of OSGi services, you can catch services events (whiteboard pattern) :

  
  public void bindService(@Observes ServiceArrival event) {}
  public void unbindService(@Observes ServiceDeparture event) {}
  public void changeService(@Observes ServiceChange event) {}
  ...
  

  you can also filter event for specific services types :

   
  public void bindService(@Observes @Specification(MyService.class) ServiceArrival event) {}
  

  or filter with native OSGi filters;

   
  public void bindService(@Observes @Specification(MyService.class) @Filter("(&(lang=EN)(country=US))") ServiceArrival event) {}
  

• to manipulate the OSGi service registry and register/unregister dynamically services inside your application you can use the ServiceRegistry bean :

      
  @Inject Instance