domino.java

Class OsgiContext

java.lang.Object

domino.java.capsule.DynamicCapsuleContext

domino.java.OsgiContext

All Implemented Interfaces:

CapsuleContext, ServiceConsuming, ServiceProviding, ServiceWatching, org.osgi.framework.BundleActivator

public class OsgiContext
extends DynamicCapsuleContext
implements org.osgi.framework.BundleActivator, ServiceWatching, ServiceProviding, ServiceConsuming

This is the main entry point to the Domino Java DSL.

By having your bundle activator extend from this class, you get *full* access to the Domino Java DSL.

By calling whenBundleActive(Procedure1), you implicitly create a Capsule which is tighly coupled to the bundles actived state. All (most) other methods of this class should be called inside this capsule (in the given procedure).

Note that if you use watchAdvancedServices(Class, String, Procedure1), you might additionally want to import the relevant watcher events.

== Example 1: Wait for a service

 // file: MyService.java
 package org.example.domino_test_one

 import org.osgi.service.http.HttpService

 public class MyService {

   private final HttpService httpService;

   public MyService(HttpService httpService) {
     this.httpService = httpService;
   }

 }
  

 // file: Activator.java
 package org.example.domino_test_one

 import domino.java.OsgiContext
 import org.osgi.service.http.HttpService

 public class Activator extends OsgiContext {

   public Activator() {

     whenBundleActive(bundleContext -> {
       // Make MyService available as long as HttpService is present
       whenServicePresent(HttpService.class, httpService -> {
         MyService myService = new MyService(httpService);
         providesService(myService, MyService.class);
       });
     });
   }

  }
 

TODO: Do not allow per default multiple calls to whenBundleActive(Procedure1), and introduce a new setter to allow overriding whenBundleActive(Procedure1)

Constructor Summary

Constructors

Constructor and Description
OsgiContext() Will be called by the OSGi framework, if you inherit from this class.

Method Summary

Modifier and Type	Method and Description
protected <S> org.osgi.framework.ServiceRegistration<S>	internalProvideService(S service, java.lang.Iterable<java.lang.Class<? super S>> interfaces, java.util.Map<java.lang.String,java.lang.Object> properties)
boolean	isActive() Returns `true` as long as the bundle is active and it's bundle context is valid.
void	onStop(java.lang.Runnable f) Provides convenient `onStop` method which the end user can use for ad-hoc adding stop logic to the current scope.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service) Registers the service under it's own specified type and without service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.lang.Class<? super S> type) Registers the service under the specified type and without service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.lang.Class<? super S> type1, java.lang.Class<? super S> type2) Registers the service under the specified types and without service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.lang.Class<? super S> type1, java.lang.Class<? super S> type2, java.lang.Class<? super S> type3) Registers the service under the specified types and without service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.lang.Class<? super S> type1, java.lang.Class<? super S> type2, java.lang.Class<? super S> type3, java.lang.Class<? super S> type4) Registers the service under the specified types and without service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.lang.Class<? super S> type1, java.lang.Class<? super S> type2, java.lang.Class<? super S> type3, java.lang.Class<? super S> type4, java.util.Map<java.lang.String,java.lang.Object> properties) Registers the service under the specified types with the given service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.lang.Class<? super S> type1, java.lang.Class<? super S> type2, java.lang.Class<? super S> type3, java.util.Map<java.lang.String,java.lang.Object> properties) Registers the service under the specified types with the given service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.lang.Class<? super S> type1, java.lang.Class<? super S> type2, java.util.Map<java.lang.String,java.lang.Object> properties) Registers the service under the specified types with the given service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.lang.Class<? super S> type, java.util.Map<java.lang.String,java.lang.Object> properties) Registers the service under the specified type with the given service properties.
<S> org.osgi.framework.ServiceRegistration<S>	providesService(S service, java.util.Map<java.lang.String,java.lang.Object> properties) Registers the service under it's own specified type with the given service properties.
<S> de.tototec.utils.functional.Optional<S>	service(java.lang.Class<S> type) Returns the highest-ranked service of the specified type if available.
<S> de.tototec.utils.functional.Optional<S>	service(java.lang.Class<S> type, java.lang.String filter) Returns the first available service of the specified class which satisfies the filter if available.
<S> de.tototec.utils.functional.Optional<org.osgi.framework.ServiceReference<S>>	serviceRef(java.lang.Class<? super S> type) Like ServiceConsuming.service(Class) but returns the reference so you can access meta information about that service.
<S> de.tototec.utils.functional.Optional<org.osgi.framework.ServiceReference<S>>	serviceRef(java.lang.Class<S> type, java.lang.String filter) Like ServiceConsuming.service(Class, String) with filter but returns the service reference.
<S> java.util.Collection<org.osgi.framework.ServiceReference<S>>	serviceRefs(java.lang.Class<S> type, java.lang.String filter) Like ServiceConsuming.services(Class, String) with filters but returns the references.
<S> java.util.List<S>	services(java.lang.Class<S> type) Returns all services of the given type.
<S> java.util.List<S>	services(java.lang.Class<S> type, java.lang.String filter) Returns all services of the specified type which satisfy the given filter.
void	start(org.osgi.framework.BundleContext context)
void	stop(org.osgi.framework.BundleContext context)
<S> org.osgi.util.tracker.ServiceTracker<S,S>	watchAdvancedServices(java.lang.Class<S> type, java.lang.String filter, de.tototec.utils.functional.Procedure1<ServiceWatcherEvent<S>> f) Lets you react to service events for services with the specified type which match the given filter.
<S> org.osgi.util.tracker.ServiceTracker<S,S>	whenAdvancedServicePresent(java.lang.Class<S> type, java.lang.String filter, de.tototec.utils.functional.Procedure1<S> f) Activates the given inner logic as long as the first service of the given type is present.
void	whenBundleActive(de.tototec.utils.functional.Procedure1<org.osgi.framework.BundleContext> f) Defines a handler `f` to be executed when the bundle becomes active.
<S> org.osgi.util.tracker.ServiceTracker<S,S>	whenServicePresent(java.lang.Class<S> type, de.tototec.utils.functional.Procedure1<S> f) Waits until a service of the specified type is available and executes the given event handler with it.
<S1,S2,S3,S4> org.osgi.util.tracker.ServiceTracker<S1,S1>	whenServicesPresent(java.lang.Class<S1> type1, java.lang.Class<S2> type2, java.lang.Class<S3> type3, java.lang.Class<S4> type4, de.tototec.utils.functional.Procedure4<S1,S2,S3,S4> f)
<S1,S2,S3> org.osgi.util.tracker.ServiceTracker<S1,S1>	whenServicesPresent(java.lang.Class<S1> type1, java.lang.Class<S2> type2, java.lang.Class<S3> type3, de.tototec.utils.functional.Procedure3<S1,S2,S3> f)
<S1,S2> org.osgi.util.tracker.ServiceTracker<S1,S1>	whenServicesPresent(java.lang.Class<S1> type1, java.lang.Class<S2> type2, de.tototec.utils.functional.Procedure2<S1,S2> f)
<S,R> R	withService(java.lang.Class<S> type, de.tototec.utils.functional.F1<de.tototec.utils.functional.Optional<S>,R> f) Executes the given handler with the highest-ranked service of the specified type.

Methods inherited from class domino.java.capsule.DynamicCapsuleContext

addCapsule, executeWithinNewCapsuleScope

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OsgiContext

public OsgiContext()

Will be called by the OSGi framework, if you inherit from this class.

If you construct this class manually, you have to take care to properly call the start(BundleContext) and stop(BundleContext) methods.

Method Detail

isActive

public boolean isActive()

Returns `true` as long as the bundle is active and it's bundle context is valid.

whenBundleActive

public void whenBundleActive(de.tototec.utils.functional.Procedure1<org.osgi.framework.BundleContext> f)

Defines a handler `f` to be executed when the bundle becomes active. `f` is executed as soon as the bundle activator's `start` method is called. This should be called in the constructor of your activator.

In `f`, you have the opportunity to add so called capsules, which have their own `start` and `stop` methods (a kind of mini bundles). Their `stop` methods will be invoked as soon as the bundle activator's `stop` method is called. So you have the big chance here to encapsulate start and stop logic at one place, making the bundle activator less error-prone, better readable and easier to write.

Parameters:

f - Handler

start

public void start(org.osgi.framework.BundleContext context)

Specified by:

start in interface org.osgi.framework.BundleActivator

stop

public void stop(org.osgi.framework.BundleContext context)
          throws java.lang.Exception

Specified by:

stop in interface org.osgi.framework.BundleActivator

Throws:

java.lang.Exception

onStop

public void onStop(java.lang.Runnable f)

Provides convenient `onStop` method which the end user can use for ad-hoc adding stop logic to the current scope.

Parameters:

f - stop logic

internalProvideService

protected <S> org.osgi.framework.ServiceRegistration<S> internalProvideService(S service,
                                                                               java.lang.Iterable<java.lang.Class<? super S>> interfaces,
                                                                               java.util.Map<java.lang.String,java.lang.Object> properties)

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service)

Description copied from interface: ServiceProviding

Registers the service under it's own specified type and without service properties.

Specified by:

providesService in interface ServiceProviding

Returns:

The service registration.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.lang.Class<? super S> type)

Description copied from interface: ServiceProviding

Registers the service under the specified type and without service properties.

Specified by:

providesService in interface ServiceProviding

Returns:

The service registration.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.lang.Class<? super S> type1,
                                                                     java.lang.Class<? super S> type2)

Description copied from interface: ServiceProviding

Registers the service under the specified types and without service properties.

Specified by:

providesService in interface ServiceProviding

Returns:

The service registration.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.lang.Class<? super S> type1,
                                                                     java.lang.Class<? super S> type2,
                                                                     java.lang.Class<? super S> type3)

Description copied from interface: ServiceProviding

Registers the service under the specified types and without service properties.

Specified by:

providesService in interface ServiceProviding

Parameters:

service - The service.

Returns:

The service registration.

See Also:

to easily create a map in-place.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.lang.Class<? super S> type1,
                                                                     java.lang.Class<? super S> type2,
                                                                     java.lang.Class<? super S> type3,
                                                                     java.lang.Class<? super S> type4)

Description copied from interface: ServiceProviding

Registers the service under the specified types and without service properties.

Specified by:

providesService in interface ServiceProviding

Parameters:

service - The service.

Returns:

The service registration.

See Also:

to easily create a map in-place.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.util.Map<java.lang.String,java.lang.Object> properties)

Description copied from interface: ServiceProviding

Registers the service under it's own specified type with the given service properties.

Specified by:

providesService in interface ServiceProviding

Parameters:

service - The service.

properties - The service properties.

Returns:

The service registration.

See Also:

to easily create a map in-place.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.lang.Class<? super S> type,
                                                                     java.util.Map<java.lang.String,java.lang.Object> properties)

Description copied from interface: ServiceProviding

Registers the service under the specified type with the given service properties.

Specified by:

providesService in interface ServiceProviding

Parameters:

service - The service.

properties - The service properties.

Returns:

The service registration.

See Also:

to easily create a map in-place.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.lang.Class<? super S> type1,
                                                                     java.lang.Class<? super S> type2,
                                                                     java.util.Map<java.lang.String,java.lang.Object> properties)

Description copied from interface: ServiceProviding

Registers the service under the specified types with the given service properties.

Specified by:

providesService in interface ServiceProviding

Parameters:

service - The service.

properties - The service properties.

Returns:

The service registration.

See Also:

to easily create a map in-place.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.lang.Class<? super S> type1,
                                                                     java.lang.Class<? super S> type2,
                                                                     java.lang.Class<? super S> type3,
                                                                     java.util.Map<java.lang.String,java.lang.Object> properties)

Description copied from interface: ServiceProviding

Registers the service under the specified types with the given service properties.

Specified by:

providesService in interface ServiceProviding

Parameters:

service - The service.

properties - The service properties.

Returns:

The service registration.

See Also:

to easily create a map in-place.

providesService

public <S> org.osgi.framework.ServiceRegistration<S> providesService(S service,
                                                                     java.lang.Class<? super S> type1,
                                                                     java.lang.Class<? super S> type2,
                                                                     java.lang.Class<? super S> type3,
                                                                     java.lang.Class<? super S> type4,
                                                                     java.util.Map<java.lang.String,java.lang.Object> properties)

Description copied from interface: ServiceProviding

Registers the service under the specified types with the given service properties.

Specified by:

providesService in interface ServiceProviding

Parameters:

service - The service.

properties - The service properties.

Returns:

The service registration.

See Also:

to easily create a map in-place.

watchAdvancedServices

public <S> org.osgi.util.tracker.ServiceTracker<S,S> watchAdvancedServices(java.lang.Class<S> type,
                                                                           java.lang.String filter,
                                                                           de.tototec.utils.functional.Procedure1<ServiceWatcherEvent<S>> f)

Description copied from interface: ServiceWatching

Lets you react to service events for services with the specified type which match the given filter.

Specified by:

watchAdvancedServices in interface ServiceWatching

Parameters:

type - The `Class` representing the service type.

f - Service event handler

Returns:

Underlying service tracker

whenAdvancedServicePresent

public <S> org.osgi.util.tracker.ServiceTracker<S,S> whenAdvancedServicePresent(java.lang.Class<S> type,
                                                                                java.lang.String filter,
                                                                                de.tototec.utils.functional.Procedure1<S> f)

Description copied from interface: ServiceWatching

Activates the given inner logic as long as the first service of the given type is present. This implements the concept of required services. The inner logic is started as soon as a service s of the given type gets present and stopped when s is removed.

Specified by:

whenAdvancedServicePresent in interface ServiceWatching

Parameters:

type - The `Class` representing the service type.

whenServicePresent

public <S> org.osgi.util.tracker.ServiceTracker<S,S> whenServicePresent(java.lang.Class<S> type,
                                                                        de.tototec.utils.functional.Procedure1<S> f)

Description copied from interface: ServiceWatching

Waits until a service of the specified type is available and executes the given event handler with it. When the service disappears, the capsules added in the handlers are stopped. You can wait on a bunch of services if you nest `whenServicePresent` methods.

Specified by:

whenServicePresent in interface ServiceWatching

f - Handler

Returns:

Underlying service tracker

whenServicesPresent

public <S1,S2> org.osgi.util.tracker.ServiceTracker<S1,S1> whenServicesPresent(java.lang.Class<S1> type1,
                                                                               java.lang.Class<S2> type2,
                                                                               de.tototec.utils.functional.Procedure2<S1,S2> f)

Specified by:

whenServicesPresent in interface ServiceWatching

whenServicesPresent

public <S1,S2,S3> org.osgi.util.tracker.ServiceTracker<S1,S1> whenServicesPresent(java.lang.Class<S1> type1,
                                                                                  java.lang.Class<S2> type2,
                                                                                  java.lang.Class<S3> type3,
                                                                                  de.tototec.utils.functional.Procedure3<S1,S2,S3> f)

Specified by:

whenServicesPresent in interface ServiceWatching

whenServicesPresent

public <S1,S2,S3,S4> org.osgi.util.tracker.ServiceTracker<S1,S1> whenServicesPresent(java.lang.Class<S1> type1,
                                                                                     java.lang.Class<S2> type2,
                                                                                     java.lang.Class<S3> type3,
                                                                                     java.lang.Class<S4> type4,
                                                                                     de.tototec.utils.functional.Procedure4<S1,S2,S3,S4> f)

Specified by:

whenServicesPresent in interface ServiceWatching

withService

public <S,R> R withService(java.lang.Class<S> type,
                           de.tototec.utils.functional.F1<de.tototec.utils.functional.Optional<S>,R> f)

Description copied from interface: ServiceConsuming

Executes the given handler with the highest-ranked service of the specified type. If it's not available, it still executes it but with `None`. Doesn't take type parameters into account! When the handler returns, the service is released using BundleContext.ungetService(org.osgi.framework.ServiceReference).

Specified by:

withService in interface ServiceConsuming

f - Handler that uses the service.

Returns:

The handler result.

serviceRef

public <S> de.tototec.utils.functional.Optional<org.osgi.framework.ServiceReference<S>> serviceRef(java.lang.Class<? super S> type)

Description copied from interface: ServiceConsuming

Like ServiceConsuming.service(Class) but returns the reference so you can access meta information about that service. An implicit conversion adds a `service` property to the reference, so you can simply use that to obtain the service. Doesn't take type parameters into account!

Specified by:

serviceRef in interface ServiceConsuming

serviceRef

public <S> de.tototec.utils.functional.Optional<org.osgi.framework.ServiceReference<S>> serviceRef(java.lang.Class<S> type,
                                                                                                   java.lang.String filter)

Description copied from interface: ServiceConsuming

Like ServiceConsuming.service(Class, String) with filter but returns the service reference.

Specified by:

serviceRef in interface ServiceConsuming

serviceRefs

public <S> java.util.Collection<org.osgi.framework.ServiceReference<S>> serviceRefs(java.lang.Class<S> type,
                                                                                    java.lang.String filter)

Description copied from interface: ServiceConsuming

Like ServiceConsuming.services(Class, String) with filters but returns the references.

Specified by:

serviceRefs in interface ServiceConsuming

service

public <S> de.tototec.utils.functional.Optional<S> service(java.lang.Class<S> type)

Description copied from interface: ServiceConsuming

Returns the highest-ranked service of the specified type if available. The service is not explicitly released. It's assumed that the service will be used until the bundle stops. Doesn't take type parameters into account!

Specified by:

service in interface ServiceConsuming

Returns:

service if available

service

public <S> de.tototec.utils.functional.Optional<S> service(java.lang.Class<S> type,
                                                           java.lang.String filter)

Description copied from interface: ServiceConsuming

Returns the first available service of the specified class which satisfies the filter if available. If the service is not available, it returns `None`. The service is not explicitly released.

Specified by:

service in interface ServiceConsuming

filter - filter expression

Returns:

service if available

services

public <S> java.util.List<S> services(java.lang.Class<S> type,
                                      java.lang.String filter)

Description copied from interface: ServiceConsuming

Returns all services of the specified type which satisfy the given filter.

Specified by:

services in interface ServiceConsuming

filter - filter expression

Returns:

services

services

public <S> java.util.List<S> services(java.lang.Class<S> type)

Description copied from interface: ServiceConsuming

Returns all services of the given type.

Specified by:

services in interface ServiceConsuming