# repos_asf_aries-component-dsl **Repository Path**: mirrors_community_gitbox_apache/repos_asf_aries-component-dsl ## Basic Information - **Project Name**: repos_asf_aries-component-dsl - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-07-29 - **Last Updated**: 2026-08-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # osgi-component-dsl [![Build Status](https://builds.apache.org/buildStatus/icon?job=Aries-component-dsl-master)](https://builds.apache.org/job/Aries-component-dsl-master) [![CI Build](https://github.com/rotty3000/aries-component-dsl/actions/workflows/maven.yml/badge.svg)](https://github.com/rotty3000/aries-component-dsl/actions/workflows/maven.yml) [![Maven Central](https://img.shields.io/maven-central/v/org.apache.aries.component-dsl/org.apache.aries.component-dsl.component-dsl.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22org.apache.aries.component-dsl%22%20AND%20a:%22org.apache.aries.component-dsl.component-dsl%22) A lightweight functional DSL to interact with OSGi registry. This DSL provides a set of operations to fetch service references and configurations from OSGi, as well as to register services back into OSGi registry. It also provides a way to create new custom operations. *This documentation is still work in progress* ## Why should I use it? One of the benefits of using this DSL is that operations are automatically bound to the service or configuration intances that triggered their execution. This allows them to automatically undo (or clean) when those instances are no longer available. This way the user of the DSL does not need to manually account for the tracked instances and ensure the proper cleaning, which is a source of mistakes. For those cases in which manual assistance is needed, such as side effects management, the DSL facilitates specifying the undo operation together with the side effect. This allows for better reutilization. The DSL runs without the need for any additional runtime. ## Quick start The foundation of the DSL is one type `OSGi`. There exist several static functions defined on the `OSGi` class that provide us with instances of the type. Let's start getting a reference to a service: ```java OSGi program = OSGi.service(OSGi.serviceReferences(Service.class)); ``` if we allow static imports from `OSGi` class we can type the former as: ```java OSGi services = service(serviceReferences(Service.class)); OSGi> configurations = configurations("factory-pid"); ``` ### Combining operations Once we have instances of `OSGi` we can combine them. We can use `flatMap` to specify that one operation depends on a previous one. For example we could need to specify a filter for the services that comes in the configuration: ```java OSGi services = configurations("factory-pid").flatMap(conf -> service(serviceReferences(Service.class, conf.get("service.filter").toString())) ); ``` we can also register instances. For this purpose let's create a new class that will hold instances of both `Dictionary` and `Service`. ```java class Holder { Dictionary properties; Service service; public Holder(Dictionary properties, Service service) { this.properties = properties; this.service = service; } } ``` and we can register instances of that class with: ```java OSGi> program = configurations("factory-pid").flatMap(conf -> service(serviceReferences(Service.class, conf.get("service.filter").toString())).flatMap(service -> register(Holder.class, new Holder(conf, service), new HashMap<>()))); ``` in this example we are tracking factory configurations from pid `factory-pid`. For each configuration factory that's there, or that's created in the future, we get the property `service.filter` and use it's value to track services of type `Service` that match the filter in the configuration. Then, for each service that matches that filter and each configuration factory combination we register one `Holder` instance. If any of the configuration factories goes away, or any of the tracked services goes away, the corresponding `Holder` instances will be unregistered automatically, since the DSL tracks the effects each instance has produced. ### Running the _program_ In the previous section we have gone through combining different operations to produce new instances. These instances are values that describe how we are going to interact with OSGi and are immutable. You can use them to produce new programs like reusable components. Once you have a complete specification you can run it passing a `BundleContext` to it: ```java OSGi program; BundleContext bundleContext; OSGiResult result = program.run(bundleContext); ``` the `OSGiResult` instance references the execution of the program. To stop and clean it we call: ```java result.close() ``` ### Combinations without dependency we can also specify combinations when there exist no dependencies between the operations. For instance we can declare we want to register a `Holder` for every configuration + service combination using `OSGi.combine`: ```java OSGi holders = combine(Holder::new, configurations("factory.pid"), services(Service.class)); ``` ## Predefined Operations the DSL comes with some common operations defined on the OSGi type. All these operations produce values of a type and keep track of the next operations. When a tracked value goes away all the associated operations will be cleaned as well. ### Configurations There are two operations to deal with `Configuration Admin` configurations: `OSGi.configuration` to deal with singleton configurations and `OSGi.configurations` to deal with factory configurations. ### Services `OSGi.serviceReferences` is a set of overloaded functions that return operations of type `OSGi`: ```java OSGi> serviceReferences(Class clazz) OSGi> serviceReferences(String filterString) OSGi> serviceReferences(Class clazz, String filterString) OSGi> serviceReferences( Class clazz, String filterString, Refresher> onModified) OSGi> serviceReferences( Class clazz, Refresher> onModified) OSGi> serviceReferences( String filterString, Refresher> onModified) ``` #### CachingServiceReference This class is an explicit wrapper around `ServiceReference` (it DOES NOT implement `ServiceReference`) and provides methods to access underlying `ServiceReference` properties and caches them so future access to the same properties return the same values. Property values are cached *on demand*. Values that have never been queried through the method are not cached. Properties that did not exist when queried will no longer exist even though they were available at a later time in the underlying `ServiceReference`. This class was introduced because `ServiceReference` is mutable, which made it very difficult to operate on it within the DSL in a safe manner. #### Refresher This class is just an alias for `Predicate`. `serviceReferences` operations will invoke the `Refresher` to know if the modified instance needs to be retracted and reintroduced in the execution. If no refresher is passed `serviceReferences` will check `CachingServiceReference.isDirty()`. #### Getting services from `ServiceReference` There are two sets of overloaded operations that allow to get services from `CachingServiceReference` or `ServiceReference`: `service` and `prototypes`. `service` will get services invoking `bundleContext.getService` and unget them using `bundleContext.ungetServices`. `prototypes`, on the other hand, will produce a `ServiceObjects` instance. It will be the responsability of the user to properly balance `getService` and `ungetService` calls to `ServiceObjects`. ### BundleContext `bundleContext` operation will produce the `BundleContext` in use by that piece of program. It will normally be the one used to invoke `OSGi.run` unless it is changed using `OSGi.changeContext(BundleContext bundleContext, OSGi program)` for that particular program. ### Just and nothing `just` set of operations allows to wrap any value inside a `OSGi` type. It is overloaded to support `Supplier` and `Collection`. If a collection is passed it will produce the elements of the list in the order given by the collection. `nothing`, as it name suggests, is a termination operation. Anything depending on the result of `nothing` operation should never be executed. ### Service Registration One common operation when using OSGi is service registration. For that purpose the library offers `register` set of functions. When the associated instances are retracted, `register` set of functions also unregister their instances as a result. ```java OSGi> register( Class clazz, ServiceFactory service, Map properties) OSGi> register( String[] classes, Object service, Map properties) OSGi> register( Class clazz, Supplier service, Supplier> properties) OSGi> register( Class clazz, ServiceFactory service, Supplier> properties) OSGi> register( String[] classes, Supplier service, Supplier> properties) ``` ## Combinators ### All `OSGi all(OSGi ... programs)` will execute all given programs and produce all the elements that the given programs produce. ### Coalesce `OSGi coalesce(OSGi ... programs)`, just as its homonymous SQL function, `coalesce` will produce the value of the first producing program that is being given as argument, from left to right. Since OSGi is a dynamic environment `coalesce` will retract and reintroduce instances when needed. For example: ```java OSGi> props = coalesce( configuration("some.config.pid"), just(Hashtable::new) ); ``` this operation will return an empty Hashtable while no configuration is available. If, at any moment, there is a configuration available the operation will retract the empty `Hashtable` and introduce the incoming configuration. If, at any moment, the configuration is deleted, the operation will retract the `Dictionary` associated with that configuration and reintroduce the empty `Hashtable`. This is very useful to model defaults or to model different level for preferred services, from more specific to more general. ### Combine `OSGi.combine` set of functions is the `Applicative` implementation for `OSGi` class. It produces the result of the invocation to the given function with all the combinations of the values produced by the given operations. ### Once `OSGi.once` will just let the first instance produced by the given operation to pass. Further instances won't be published. Actually `once` does not support any order so it can't decide that any instance is more suitable than any other. `once` will update a counter with the instances that it encounters and that are retracted. It won't retract the instance it produces until all the instances it has _seen_ are gone. ## License ``` Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ```