152 CDI Integration Specification - OSGi Enterprise 7

152 CDI Integration Specification - OSGi Enterprise 7
OSGi Enterprise Release 7
Prev
Next
152
CDI Integration Specification
Version 1.0
152.1
Introduction
Contexts and Dependency Injection
[1]
CDI
) is the standard
dependency
injection
technology for Java.
[2]
CDI 2.0
is the current version.
The CDI specification is a composition of the following high level
features:
A well-defined life cycle for stateful objects bound to life
cycle contexts, where the set of contexts is extensible
A sophisticated, typesafe dependency injection mechanism,
including the ability to select dependencies at either development
or deployment time, without verbose configuration
Support for Java EE modularity and the Java EE component
architecture - the modular structure of a Java EE application is
taken into account when resolving dependencies between Java EE
components
Integration with the Unified Expression Language (EL),
allowing any contextual object to be used directly within a JSF or
JSP page
The ability to decorate injected objects
The ability to associate interceptors to objects via typesafe
interceptor bindings
An event notification model
A web conversation context in addition to the three standard
web contexts defined by the Java Servlets specification
A Service Provider Interface (SPI) allowing portable
extensions to integrate cleanly with the container
--
CDI
This specification describes how OSGi is integrated into the CDI
programming model and the interaction with these features.
152.1.1
Essentials
Dependency Injection
- Provide an
advanced dependency injection framework for bundles that can create
and wire objects and services together into an application.
Extender Model
- Enable the configuration
of components inside a bundle based on configuration data provided
by the bundle developer. The life cycle of these components is
controlled by the extender based on the extended bundle's
state.
Unencumbered
- Does not require any
special bundle activator or other code to be written inside the
bundle in order to have components instantiated and
configured.
Services
- Enable the usage of OSGi
services as injected dependencies.
Configuration
- Enable the usage of
Configuration Admin configuration objects as injected
dependencies.
Dependencies
- Allow components to depend
on configuration objects and services and to register services, with
the full breadth of the OSGi capabilities.
Reactive
- It must be possible to react
to changes in the external dependencies with different
policies.
Introspection
- It must be possible to
introspect the service components.
Business Logic
- A focus on writing
business logic by using the features of CDI and reusable
functionality provided by extensions.
Familiarity
- Familiar to Java developers
knowledgeable in CDI.
152.1.2
Entities
CDI Entities
CDI
- Contexts and Dependency
Injection 2.0.
Bean
- A Java class that satisfies
the criteria of a bean as defined in CDI and which provides
contextual objects that define application state and/or
logic.
Producer
- A producer method or field
acts as a source of objects to be injected. It is an alternative
to beans.
Contextual Instance
- The object
instances produced by beans or producers within a given
context
Context
- A Service Provider
Interface (SPI) defining the life cycle for a set of contextual
instances. The context also determines which contextual
instances of beans are visible to the contextual instances of
other beans.
Scope
- A (CDI) scope identifies a
particular
Context
implementation. All
beans have a scope and are therefore bound to a particular
context implementation. A scope is represented by an annotation
type. Any contextual instances produced from the bean exist
within a context identified by the scope.
Injection Point
- A location in a
contextual instance or producer which is the target for
injection for a contextual instance.
Qualifier
- An annotation used to
define a quality used for matching. Qualifiers are applied to
injection points, beans, producers (among other things). CDI
finds beans matching an injection point's type then makes sure
the qualifiers of the bean match all those on the injection
point.
Stereotype
- An annotation
meta-annotated with
javax.enterprise.inject.Stereotype
used to define a
recurring role by aggregating a CDI scope and various other
aspects into a reusable unit.
Decorators and Interceptors
- Actors
that intercept certain method invocations of contextual
instances.
Portable Extension
- A portable
extension uses the CDI SPI to provide additional and reusable
functionality to a set of CDI beans.
CDI Container
- For each CDI bundle,
required portable extensions are loaded , metadata and bean
classes are analyzed to create a bean injection graph. This
process is encapsulated by a CDI container.
Entities defined by this
specification
CDI Bundle
- An OSGi bundle
containing CDI beans.
CDI Extension Bundle
- A bundle
providing one or more portable extensions.
CDI Component Runtime (CCR)
- The
actor that manages the CDI containers and their life cycle and
allows introspection of CDI containers.
Configuration Object
- Configuration
Admin object which implements the
Configuration
interface and contains configuration data.
Factory Configuration Object
- A
Configuration Object having a factory PID whose instances for
which there can be 0 or N are under the control of Configuration
Admin, all sharing the same factory PID.
Single Configuration Object
- A
configuration object that has no factory PID and remains
singularly independent from all other configuration
objects.
Component
- A set of beans whose life
cycle is derived from it's dependencies.
Dependency
- A configuration object
or service upon which beans depend. These dependencies are
dynamic in that their life cycle is independently controlled by
other actors within the OSGi Framework and CCR must properly
accommodate for this.
Configuration Template
- The static
metadata describing a configuration object dependency.
Reference Template
- The static
metadata describing a reference dependency.
Component Template
- The static
definition of a
component
combining all the
metadata defined by its beans, and its dependencies. The
component template does not change between restarts of the CDI
bundle.
Component Scope
- A (CDI) scope
defined by this specification that represents the granular life
cycle associated with a set of dependencies.
Component Instance
- A runtime
instance of the component template which observes and reacts to
the state of the OSGi Framework based on the metadata of the
component template.
Container Component
- A component
encompassing all beans in the CDI container
not
in the component scope. The
container component results in a single component
instance.
Single Component
- A component that
encompasses beans that have the
Component
Scope
, whose dependencies may include single
configuration objects and services. A single component results
in a single component instance.
Factory Component
- A component that
encompassed beans having the
Component
Scope
, that are driven by factory configuration
objects and whose dependencies may include single configuration
objects and services. A factory component results in any number
of component instances, one for every factory configuration
object.
152.1.3
Synopsis
The CDI Extender reads CDI metadata from started CDI bundles.
These metadata are in the form of XML documents, annotation types and
requirements which define the set of
beans
available to the CDI container. Beans express dependencies on OSGi
configuration objects and services and are assembled into components.
The life cycle of a component is driven from the dependencies of its
beans.
There are three types of components:
Container Component
- Consists of beans
not in the
component scope
. There is exactly
one container component per CDI bundle. It's life cycle is
synonymous with the CDI container. The container component must be
completely satisfied before other component types can be satisfied.
The container component may provide multiple services. Altering the
state of the container component's static dependencies results in
the entire CDI container, and all other component types being
destroyed and recreated.
Single Component
- A
Single
Component
begins with a bean annotated by the
@SingleComponent
annotation and is further enhanced by other beans in it's injection
graph that are component scoped. A single component may provide
immediate functionality or a service resulting in an immediate
instance or a single service registration. Unlike the container
component, single components may be created, destroyed and react to
changes in the state of it's dependencies in isolation, without
affecting the entire CDI container. A single component's life cycle
is driven first by the container component which must be satisfied
and second by it's dependencies.
Factory Component
- A
Factory
Component
begins with a bean annotated by the
@FactoryComponent
annotation and is further enhanced by other beans in it's injection
graph that are component scoped. A factory component may provide
immediate functionality or a service, resulting in one immediate
instance or service registration. Unlike the container component,
factory components may be created, destroyed and react to changes in
the state of it's dependencies in isolation, without affecting the
entire CDI container. A factory component's life cycle is driven
first by the container component which must be satisfied, secondly
by factory configuration which result in one component instance per
factory configuration object, and finally by it's
dependencies.
Figure
152
.1 CCR Model
152.2
Components
A traditional CDI application is composed of beans that have a
well-defined life cycle based on the CDI scope they declare. This
specification defines a component model in terms of beans and scopes as
they are defined in the CDI specification in order to act as a good CDI
citizen.
Components
are defined by this specification to
have the following characteristics:
Components exist within a CDI bundle.
Components are defined by collections of beans (referred to as
component beans).
Components may have dependencies on configuration objects and
services. These dependencies are described using annotations defined
by this specification.
Components have properties, referred to as
component
properties
. Some of these are defined by this specification
and must be present. Others are aggregated from various configuration
sources as defined in
Component Properties
Components have unique names within the CDI bundle.
Components produce one or more
component
instances
. Component instances are the runtime
representation of the component. They independently react to the state
of the dependencies declared by their component beans.
152.3
Component Scope
This specification uses the facilities of CDI
[8]
Scopes and contexts
to define a life cycle
for beans specifically for supporting a relationship with OSGi
dependencies.
Associated with every CDI scope is an object implementing
javax.enterprise.context.spi.Context
or
javax.enterprise.context.spi.AlterableContext
. The life cycle
and visibility rules for said scope are defined by this implementation
which collaborates with the CDI container to create or destroy contextual
instances. Contextual instances associated with the scope exist within a
context
which acts as a cache, creating new or
returning existing contextual instances as needed. These contexts are
managed by CCR in conjunction with the CDI container.
Figure
152
.2 CDI Scope Model
The
component scope
is a
[9]
Pseudo-scope
identified by the
@ComponentScoped
annotation. The
component scope
allows component
instances to use component beans to create or destroy contextual instances
when dependencies are satisfied or unsatisfied without interfering with
the life cycle of other component instances (including the
container
component
).
The context implementation must be registered with the CDI container
using the CDI SPI. For example:
void afterBeanDiscovery(
@Observes javax.enterprise.inject.spi.AfterBeanDiscovery abd) {

Context ctx = ...
abd.addContext(ctx);
The
ComponentScoped
annotation must be registered with
the CDI container using the CDI SPI. For example:
void beforeBeanDiscovery(
@Observes javax.enterprise.inject.spi.BeforeBeanDiscovery bbd) {

bbd.addScope(ComponentScoped.class, false, false);
152.3.1
Contexts
The creation and destruction of the component scope's contexts
must adhere to the following process:
The following steps are taken to create a
context
the context is made active
- The
method
javax.enterprise.context.spi.Context.isActive()
must return
true
contextual instances are created and
injected
- Contextual instances can be retrieved by
calling
javax.enterprise.context.spi.Context.get(...)
the @Initialized event is fired
- On
success of step 2, the CDI event
@Initialized(ComponentScoped.class)
is fired
synchronously. See
Table
152
.1
When the component is a
single
component
, the event payload is the contextual
instance of the bean marked
@SingleComponent
When the component is a
factory
component
the event payload is the contextual
instance of the bean marked
@FactoryComponent
Any qualifiers defined on the bean of the contextual
instance must be attached to the event.
On failure of step 2, errors are logged and made available
in
errors
the context is deactivated
- The
method
javax.enterprise.context.spi.Context.isActive()
must return
false
The following steps are taken to destroy a
context
the context is made active
- The
method
javax.enterprise.context.spi.Context.isActive()
must return
true
the @BeforeDestroy is fired
- The CDI
event
@BeforeDestroy(ComponentScoped.class)
is
fired synchronously. See
Table
152
.1
When the component is a
single
component
the event payload is the contextual
instance of the bean marked
@SingleComponent
When the component is a
factory
component
the event payload is the contextual
instance of the bean marked
@FactoryComponent
Any qualifiers defined on the bean of the contextual
instance must be attached to the event.
contextual instances are destroyed
Any exceptions are logged.
the context is deactivated
- The
method
javax.enterprise.context.spi.Context.isActive()
must return
false
the context is destroyed
the @Destroyed event is fired
- The
CDI event
@Destroyed(ComponentScoped.class)
is
fired synchronously. See
Table
152
.1
When the component is a
single
component
the event payload is the contextual
instance of the bean marked
@SingleComponent
When the component is a
factory
component
the event payload is the contextual
instance of the bean marked
@FactoryComponent
Any qualifiers defined on the bean of the contextual
instance must be attached to the event.
Note
that the object
may not be
usable
during this event because
the context under which it was created is already
destroyed.
Table
152
.1 Component Context Events
Event Qualifier
Condition
@Initialized(ComponentScoped.class)
when a context is initialized and ready for use
@BeforeDestroy(ComponentScoped.class)
when a context is about to be destroyed, but before
actual destruction
@Destroyed(ComponentScoped.class)
after a context is destroyed
152.3.1.1
When Contexts are Created
context
is created under each of the
following conditions:
Immediate instance
- A component
instance that does not provide a service requires the immediate
creation of
a context
Singleton scoped service from a
@SingleComponent
- A single component
instance that provides a singleton scoped service requires the
immediate
creation of a
context
The service object is the contextual instance of the bean
marked
@SingleComponent
obtained from the
context.
Singleton scoped service from a
@FactoryComponent
- A factory component
instance that provides a singleton scoped service requires the
immediate
creation of a
context
for each factory configuration object.
The service object is the contextual instance of the bean
marked
@FactoryComponent
obtained from the
context.
Bundle scoped service
- A component
instance that provides a bundle scope service requires the
creation of a
context
when the
ServiceFactory.getService()
method is called.
If the component is a
single component
the service object is the contextual instance of the bean marked
@SingleComponent
obtained from the context.
If the component is a
factory
component
, the service object is the contextual
instance of the bean marked
@FactoryComponent
obtained from the context.
The context is released and destroyed when the
ServiceFactory.ungetService()
method is
called.
Prototyped scoped service
- A component
instance that provides a prototype scope service requires the
creation of
a context
when the
PrototypeServiceFactory.getService()
method is
called.
If the component is a
single component
the service object is the contextual instance of the bean marked
@SingleComponent
obtained from the context.
If the component is a
factory
component
, the service object is the contextual
instance of the bean marked
@FactoryComponent
obtained from the context.
The context is released and destroyed when the
PrototypeServiceFactory.ungetService()
method is
called.
In addition to the cases specified above, all contexts produced
by an immediate component or by the service registration are released
and destroyed when the component instance is no longer satisfied or
when the CDI container is destroyed.
152.4
Container Component
The
container component
is composed of all the
beans available to the CDI container which are
not
ComponentScoped
The container component draws it's name from the CDI container id.
By default, the CDI container id is equal to the
Bundle-SymbolicName
of the CDI bundle prefixed by
osgi.cdi.
'.
containerId ::= 'osgi.cdi.' bsn
bsn ::= < Bundle-SymbolicName >
The container id can be specified using the
container.id
attribute of the
CDI extender
requirement
in the bundle manifest. The value must follow the
Bundle-SymbolicName
syntax. For example:
Require-Capability:
osgi.extender;
filter:=”(&(osgi.extender=osgi.cdi)(version>=
1.0
)(!(version>=2.0.0)))”;
container.id="my.id"
152.4.1
Container Component Configuration
The container component must be configurable using it's container
id as a PID; referred to as the
container
PID
containerPID ::= < container id >
Given a bundle with
Bundle-SymbolicName
equal to
com.acme.bar
which does not set the
container.id
attribute in the requirement, the container id
would be:
osgi.cdi.com.acme.bar
From the requirement example above where the container id is set
to
my.id
, the container PID would be:
my.id
The configuration object used to satisfy the container PID must be
a single configuration object. However the configuration policy for this
configuration object is
optional
and is not
required to satisfy the container component.
152.4.2
Container Component Life Cycle
The container component is largely synonymous with the CDI
container. When the dependencies of the container component are
satisfied the CDI container completes it's initialization process and
subsequently is fully functional. When the dependencies of the container
component are no longer satisfied the CDI container is shutdown and all
contextual instances are destroyed.
A container component with no beans would be immediately satisfied
since it specifies no dependencies.
152.5
Standard Definitions
152.5.1
Annotation Inheritance
Annotations are not inherited unless meta-annotated by
@java.lang.annotation.Inherited
152.5.2
Code Examples
This specification provides several source code examples. In order
to avoid repetition the following Java types are defined and re-used
throughout:
interface Dog {}

interface Hound extends Dog {}

abstract class BassetHound implements Hound {}

class Spot extends BassetHound {}

class Buddy implements Hound {}
152.6
Single Component
Single Component
begins with and is rooted by
a bean annotated by the
@SingleComponent
annotation. It is further enhanced by beans in it's injection graph that
are
@ComponentScoped
which are discovered according to CDI's
rules for
[7]
Typesafe Resolution
starting from the
@SingleComponent
bean and recursing through
all injection points until all injection points are resolved.
Resolution results which contain non-root beans marked with
@SingleComponent
or
@FactoryComponent
result in
a definition error.
Any failed resolutions result in a definition error.
Applying any scope besides
@ComponentScoped
to a bean
marked with
@SingleComponent
results in a definition
error.
Any
@ComponentProperties
or
@Reference
injection point that is resolved by beans which are not provided by CCR
results in a definition error.
A single component has an implicit dependency on the container
component. Therefore it may never be satisfied until the container
component is satisfied.
152.6.1
Single Component Naming
The
@SingleComponent
annotation is a
stereotype
which carries the
@javax.inject.Named
meta-annotation. This indicates that
the default component name is:
the unqualified class name of the bean class, after
converting the first character to lower case
--
CDI
For example:
// component.name = fido
@SingleComponent
class Fido {}
However, the name may be specified by adding
@javax.inject.Named
directly to the bean and specifying a
value whose syntax follows
cname
defined by the
[11]
General Syntax Definitions
// component.name = Champ
@SingleComponent
@Named("Champ")
class Fido {}
152.6.2
Single Component Configuration
By default a single component must be configurable by using it's
component name, prefixed by the container PID and a period
), as a configuration PID. This
component
PID
will be represented throughout the remained of the
specification by the symbol
(capital Phi).
Φ ::= containerPID '.' compName
containerPID ::= < container PID >
compName ::= < component name >
A single component may change or add additional PIDs on which it
depends. When multiple PIDs are referenced the order is relevant and
affects the aggregation of the configuration objects into a flattened
dictionary of component properties. Later PIDs take precedence over
earlier PIDs. Also, it must be possible to reposition the component PID
within the order. The
PID
annotation is used to
control both referenced PIDs and their order.
The following is an example of a component that is configurable by
it's component PID:
// component pids = [Φ]
@SingleComponent
class Fido {}
An example of a component replacing it's component PID with a
specific PID:
// component pids = [com.acme.foo]
@SingleComponent
@PID("com.acme.foo")
class Fido {}
An example of multiple PIDs:
// component pids = [com.acme.foo, com.gamma.bar]
@SingleComponent
@PID("com.acme.foo")
@PID("com.gamma.bar")
class Fido {}
See
Component Properties
for how
multiple component PIDs are merged into component properties.
Using
@PID
without arguments refers to the component
PID:
// component pids = [Φ]
@SingleComponent
@PID
class Fido {}
This allows the component PID to be included anywhere in the
order:
// component pids = [com.acme.foo, Φ, com.gamma.bar]
@SingleComponent
@PID("com.acme.foo")
@PID
@PID("com.gamma.bar")
class Fido {}
Each
@PID
annotation may specify a policy for the
configuration object. The property
policy
is used to
specify the value. The possible values are:
OPTIONAL
- A configuration object is not required.
This is the
default policy.
REQUIRED
- A configuration object is required.
// component pids = [com.acme.foo, Φ, com.gamma.bar]
@SingleComponent
@PID(value = "com.acme.foo", policy = Policy.REQUIRED)
@PID
@PID("com.gamma.bar")
class Fido {}
It is a definition error to refer to the same PID more than
once.
The configuration objects used to satisfy the single component's
referenced PIDs must be single configuration objects.
152.7
Factory Component
Factory Component
begins with and is rooted
by a bean annotated by the
@FactoryComponent
annotation. It is further enhanced by beans in it's injection graph that
are
@ComponentScoped
which are discovered according to CDI's
rules for
[7]
Typesafe Resolution
starting from the
@FactoryComponent
bean and recursing
through all injection points until all injection points are
resolved.
The
@FactoryComponent
annotation indicates that the
component is bound to the life cycle of factory configuration objects
associated with the factory PID specified in it's
value
property (or it's default component factory PID). Each factory
configuration object associated with this factory PID results in a new
component instance
. The component properties of the
component instance are supplemented by the properties of the factory
configuration object.
Resolution results which contain a non-root bean marked with
@SingleComponent
or
@FactoryComponent
result in
a definition error.
Any failed resolutions result in a definition error.
Applying any scope besides
@ComponentScoped
to a bean
marked with
@FactoryComponent
results in a definition
error.
Any
@ComponentProperties
or
@Reference
injection point that is resolved by beans which are not provided by CCR
results in a definition error.
A factory component has an implicit dependency on the container
component. Therefore it may never be satisfied until the container
component is satisfied.
152.7.1
Factory Component Naming
The
@FactoryComponent
annotation is a
stereotype
which carries the
@javax.inject.Named
meta-annotation. This indicates that
the default component name is:
the unqualified class name of the bean class, after
converting the first character to lower case
--
CDI
For example:
// component.name = fido
@FactoryComponent
class Fido {}
However, the name may be specified by adding
@javax.inject.Named
directly to the bean and specifying a
value whose syntax follows
cname
defined by the
[11]
General Syntax Definitions
// component.name = Champ
@FactoryComponent
@Named("Champ")
class Fido {}
152.7.2
Factory Component Configuration
By default a factory component must be configurable by using it's
component name, prefixed by the container PID and a period
), as a factory PID. This
component factory
PID
will be represented throughout the remained of the
specification by the symbol
(capital Sigma).
Σ ::= containerPID '.' compName
containerPID ::= < container PID >
compName ::= < component name >
An example of a factory component that is configurable by it's
component factory PID:
// component pids = [Σ]
@FactoryComponent
class Fido {}
A factory component may specify a factory PID using it's
value
property. The value must conform to the syntax defined for the
Bundle-SymbolicName
header.
An example of a factory component specifying a factory PID:
// component pids = [com.acme.foo-####]
@FactoryComponent("com.acme.foo")
class Fido {}
A factory component may change or add additional PIDs on which it
depends. When multiple PIDs are referenced the order is relevant and
affects the aggregation of the configuration objects into a flattened
dictionary of component properties. Later PIDs take precedence over
earlier PIDs. The
PID
annotation is used to control both referenced PIDs and their
order.
An example of multiple PIDs:
// component pids = [com.gamma.bar, com.acme.foo-####]
@FactoryComponent("com.acme.foo")
@PID("com.gamma.bar")
class Fido {}
Each
@PID
annotation may specify a policy for the
configuration dependency. The property
policy
is used to
specify the value. The possible values are:
OPTIONAL
- A configuration object is not required.
This is the
default policy.
REQUIRED
- A configuration object is required.
// component pids [com.acme.foo, com.gamma.bar, Σ]
@FactoryComponent
@PID(value = "com.acme.foo", policy = Policy.REQUIRED)
@PID("com.gamma.bar")
class Fido {}
See
Component Properties
for how
multiple component PIDs are merged into component properties.
The component factory PID always reserves the highest precedence
among specified PIDs and is positioned last in PID ordering for the
purpose of aggregation
A factory component can only reference a single factory
PID.
Notwithstanding the factory PID, it is a definition error to refer
to the same PID more than once.
The configuration object used to satisfy the factory component's
component factory PID must be a factory configuration object.
Configuration objects used to satisfy the PIDs referred to by the
@PID
annotations must be single configuration
objects.
152.8
Component Properties
Each component instance is associated with a set of
component properties
. Component properties are
specified in the following
configuration sources
(in
order of precedence, where the properties provided by later lines
overwrite those of earlier lines):
Properties specified as Bean Property Types on the bean
annotated with
@SingleComponent
or
@FactoryComponent
must be treated according to
Bean Property Types
Properties provided by single configuration objects whose PIDs
are matched to and are processed in the order they are specified by
the component.
Properties provided by a factory configuration object whose PID
matches to the factory PID specified by the factory component.
The precedence behavior allows certain default values to be
specified in component metadata while allowing properties to be replaced
and extended by a configuration object.
Normally, a property value from a higher precedence configuration
source replace a property value from a lower precedence configuration
source. However, the
service.pid
property values receive
different treatment. For the
service.pid
property, if the
property appears multiple times in the configuration sources, CCR must
aggregate all the values found into a
Collection
having an iteration order such that
the first item in the iteration is the property value from the lowest
precedence configuration source and the last item in the iteration is the
property value from the highest precedence configuration source. If the
component refers to multiple PIDs, then the order of the
service.pid
property values collected from the corresponding
configuration objects must match the order in which the PIDs are specified
by the component. The values of the
service.pid
component
property are the values as they come from the configuration sources and
may container more values than those referred to by the component.
CCR always adds the following component properties, which cannot be
overridden:
component.name
- The component name. The syntax for
the
component.name
follows
cname
defined by
the
[11]
General Syntax Definitions
component.id
- A unique value (
Long
that is larger than all previously assigned values. These values are
not persistent across restarts of CCR.
152.8.1
Reference Properties
This specification defines some component properties which are
associated with a specific reference. These are called
reference properties
. The name of a reference
property for a reference is the name of the reference appended with a
full stop (
'.' \u002E
) and a suffix unique to the reference
property. Reference properties can be set wherever component properties
can be set.
All component property names starting with a reference name
followed by a full stop (
'.' \u002E
) are reserved for use
by this specification.
Following are the reference properties defined by this
specification.
152.8.1.1
Target Property
The
target property
is a reference property
which aids in the selection of target services for the reference. See
Reference Injection Points
. The name of a
target property is the name of a reference appended with
.target
target ::= refName '.target'
refName ::= < reference name >
For example, the target property for a reference with the name
http
@Inject
@Reference
Http http;
would have the name
http.target
. The
value of a target property is a filter String used to select target
services for the reference.
http.target=(context.name=foo)
A default target property value can also be set by the
@Reference.target
property.
The target property value must be a valid filter String
according to
[12]
Filter Syntax
. Invalid
filters result in unmatchable reference filters.
CCR must support the target property for all references.
152.8.1.2
Minimum Cardinality Property
The initial minimum cardinality of a reference is specified by
the optionality of the reference. The minimum cardinality of a
reference cannot exceed the multiplicity: a scalar reference has a
multiplicity of 1 and a
java.util.List
or
java.util.Collection
reference has a multiplicity of
n.
The
minimum cardinality property
is a
reference property which can be used to raise the minimum cardinality
of a reference from its initial value. That is, a
0..1
cardinality can be raised to a
1..1
cardinality by
setting the reference's minimum cardinality property to
. A
0..n
cardinality can be raised to a
m..n
cardinality by setting the reference's minimum
cardinality property to
such that
is a
positive integer. The minimum cardinality of a reference cannot be
lowered. A mandatory reference cannot be reduced to optional through
this property. That is, a
1..1
cardinality can not be
lowered to a
0..1
cardinality because the component was
written to expect at least one bound service.
The name of a minimum cardinality property is the name of a
reference appended with
.cardinality.minimum
minimumCardinality ::= refName '.cardinality.minimum'
refName ::= < reference name >
For example, the minimum cardinality property for a reference
with the name
http
@Inject
@Reference
Http http;
would have the name
http.cardinality.minimum
http.cardinality.minimum=3
The value of a minimum cardinality property must be a positive
integer or a value that can be coerced into a positive integer using
the
conversions
defined by the
Converter Specification
. If the numerical
value of the minimum cardinality property is not valid for the
reference's cardinality or the minimum cardinality property value
cannot be coerced into a numerical value, then the minimum cardinality
property must be ignored and a warning message logged.
Attempts to reduce the initial minimum cardinality will result
in a warning message to be logged and the value to be otherwise
ignored.
CCR must support the minimum cardinality property for all
references.
152.9
Bean Property Types
Component properties can be defined and accessed through a user
defined annotation type, called a
bean property type
containing the property names, property types and default values. A bean
property type allows properties to be defined and accessed in a type safe
manner. Bean Property Types must be annotated with the
BeanPropertyType
meta-annotation.
The following example shows the definition of a bean property type
called
Props
which defines three properties where the name of
the property is the name of the method, the type of the property is the
return type of the method and the default value for the property is the
default value of the method.
@BeanPropertyType
public @interface Props {
boolean enabled() default true;
String[] names() default {"a", "b"};
String topic() default "default/topic";
Bean Property Types can be used in several ways:
Bean Property Types can be used along side the
SingleComponent
or
FactoryComponent
annotations to provide component properties.
Bean Property Types can be used on
ApplicationScoped
or
Dependent
scoped
beans, where the
Service
annotation is
applied to provide service properties.
Bean Property Types can be used on fields and methods
annotated with
@Produces
, where the
Service
annotation is
applied, to provide service properties.
Bean Property Types can be used on injection points where the
Reference
annotation is applied, to provide target filter properties. Target
filter properties can only provide
AND
filters.
Bean Property Types can be used on injection points as the
injection point type where the
ComponentProperties
annotation is applied to provide type safe coercion of component
properties.
Each use defines property names, types and values.
The following example shows a component bean annotated with the
example
Props
bean property type which specifies a property
value for the component which is different than the default value. The
example also shows an injection point method taking the example
Props
bean property type as the injection point type and the
method implementation accesses component property values by invoking
methods on the bean property type object.
@SingleComponent
@Props(names="myapp")
public class MyBean {
@Inject
void activate(Props props) {
if (props.enabled()) {
// do something
for (String name : props.names()) {
// do something with each name
Bean Property Types must be defined as annotation types. This is
done for several reasons. First, the limitations on annotation type
definitions make them well suited for Bean Property Types. The methods
must have no parameters and the return types supported are limited to a
set which is well suited for component properties. Second, annotation
types support default values which is useful for defining the default
value of a component property. Finally, as annotations, they can be used
to annotate bean classes.
At runtime, when CCR needs to provide injection points an object
whose type is a bean property type, CCR must construct an instance of the
bean property type whose methods are backed by the values of the component
properties. This object can then be used to obtain the property values in
a type safe manner.
152.9.1
Bean Property Type Mapping
Each method of a bean property type is mapped to a component
property. The property name is derived from the method name. Certain
common property name characters, such as full stop (
'.'
\u002E
) and hyphen-minus (
'-' \u002D
) are not valid
in Java identifiers. So the name of a method must be converted to its
corresponding property name as follows:
A single dollar sign (
'$' \u0024
) is removed
unless it is followed by:
A low line (
'_' \u005F
) and a dollar sign
in which case the three consecutive characters
"$_$"
) are converted to a single hyphen-minus
'-' \u002D
).
Another dollar sign in which case the two consecutive
dollar signs (
"$$"
) are converted to a single
dollar sign.
A single low line (
'_' \u005F
) is converted
into a full stop (
'.' \u002E
) unless is it followed
by another low line in which case the two consecutive low lines
"__"
) are converted to a single low line.
All other characters are unchanged.
If the bean property type declares a
PREFIX_
field whose value is a compile-time constant String, then the
property name is prefixed with the value of the
PREFIX_
field.
Table
152
.2
contains some name mapping examples.
Table
152
.2 Bean Property Type Name Mapping Examples
Bean Property Type Method Name
Component Property Name
myProperty143
myProperty143
$new
new
my$$prop
my$prop
dot_prop
dot.prop
_secret
.secret
another__prop
another_prop
three___prop
three_.prop
four_$__prop
four._prop
five_$_prop
five..prop
six$_$prop
six-prop
seven$$_$prop
seven$.prop
However, if the bean property type is a
single-element
annotation
, see 9.7.3 in
[16]
The Java Language Specification, Java SE 8 Edition
, then the property name for the
value
method is derived from the name of the bean property
type rather than the name of the method.
In this case, the simple name of the bean property type, that is,
the name of the class without any package name or outer class name, if
the bean property type is an inner class, must be converted to the
property name as follows:
When a lower case character is followed by an upper case
character, a full stop (
'.' \u002E
) is inserted
between them.
Each upper case character is converted to lower case.
All other characters are unchanged.
If the bean property type declares a
PREFIX_
field whose value is a compile-time constant String, then the
property name is prefixed with the value of the
PREFIX_
field.
Table
152
.3
contains
some mapping examples for the
value
method.
Table
152
.3 Single-Element Annotation Mapping Examples for
value
Method
Bean Property Type Name
value
Method Component Property Name
ServiceRanking
service.ranking
Some_Name
some_name
OSGiProperty
osgi.property
If the bean property type is a
marker
annotation
, see 9.7.2 in
[16]
The Java Language Specification, Java SE 8 Edition
, then the property name is derived
from the name of the bean property type, as is described above for
single-element annotations, and the value of the property is
Boolean.TRUE
. Marker annotations can be used to annotate
component beans to set a component property to the value
Boolean.TRUE
. However, since marker annotations have no
methods, they are of no use as injection point types.
The property type can be directly derived from the type of the
method. All types supported for annotation elements can be used except
for annotation types. Method types of an annotation type or array
thereof are not supported.
If the method type is
Class
or
Class[]
then the property type must be
String
or
String[]
, respectively, whose values are fully qualified
class names in the form returned by the
Class.getName()
method.
If the method type is an enumeration type or an array thereof,
then the property type must be
String
or
String[]
, respectively, whose values are the names of the
enum constants in the form returned by the
Enum.name()
method.
152.9.2
Coercing Bean Property Type Values
When a bean property type is used as an injection point type alone
with
@ComponentProperties
, CCR must create a contextual
instance that implements the bean property type and maps the methods of
the bean property type to component properties. The name of the method
is converted to the property name as described in
Bean Property Type Mapping
. The property value
may need to be coerced to the type of the method. In
Table
152
.4
, the columns are source types,
that is, the type of the component property value, and the rows are
target types, that is, the method types. The property value is
number
is a primitive
numerical type and
Number
is a wrapper numerical
type. An invalid coercion is represented by
throw
. Such a
coercion attempt must result in throwing a Bean Property Exception when
the bean property type method is called. Any other coercion error, such
as parsing a non-numerical String to a number or the inability to coerce
a String into a Class or enum object, must be wrapped in a Bean Property
Exception and thrown when the bean property type method is
called.
Table
152
.4 Coercion From Property Value to Method Type
target
source
String
Boolean
Character
Number
Collection/array
String
. toString()
. toString()
. toString()
If
has no elements,
null
; otherwise the first element of
is coerced.
boolean
Boolean. parseBoolean(
. booleanValue()
. charValue() != 0
. doubleValue() != 0
If
has no elements,
false
; otherwise the first element of
is coerced.
char
. length() > 0 ?
. charAt(0) : 0
. booleanValue() ? 1 : 0
. charValue()
(char)
. intValue()
If
has no elements, 0; otherwise
the first element of
is coerced.
number
Number
parse
Number
. booleanValue() ? 1 : 0
number
charValue()
number
Value()
If
has no elements, 0; otherwise
the first element of
is coerced.
Class
Bundle. loadClass(
throw
throw
throw
If
has no elements,
null
; otherwise the first element of
is coerced.
EnumType
EnumType
. valueOf(
throw
throw
throw
If
has no elements,
null
; otherwise the first element of
is coerced.
annotation type
throw
throw
throw
throw
throw
array
A single element array is
created and
is coerced into the single
element of the new array.
An array the size of
is created and each element of
is coerced into the corresponding element
of the new array.
Component properties whose names do not map to bean property type
methods are ignored. If there is no corresponding component property for
a bean property type method, the bean property type method must:
Return 0 for numerical and char method types.
Return
false
for boolean method type.
Return
null
for String, Class, and enum.
Return an empty array for array method types.
Throw a BeanPropertyException for annotation method
types.
152.9.3
Standard Bean Property Types
Bean Property Types for standard service properties are specified
in the
org.osgi.service.cdi.propertytypes
package.
The
ServiceDescription
bean
property type can be used to add the
service.description
component property, service property or target filter. The
ServiceRanking
bean
property type can be used to add the
service.ranking
component property, service property or target filter. The
ServiceVendor
bean
property type can be used to add the
service.vendor
component property, service property or target filter. For example,
using these Bean Property Types as annotations:
@FactoryComponent
@ServiceDescription(”My Acme Service implementation”)
@ServiceRanking(100)
@ServiceVendor("My Corp")
public class MyBean implements AcmeService {}
will result in the following component properties:
service.description=My Acme Service implementation # String
service.ranking=100 # Integer
service.vendor=My Corp # String
The
ExportedService
bean
property type can be used to specify service properties for remote
services.
152.10
Providing Services
A key aspect of working with OSGi is the ability to provide
services. Services are published to the service registry specifying
service types. The
@Service
annotation provides this capability to CCR and serves a dual role; the
first of which is indicating that a bean publishes a service, the second
indicating the service types.
@Service
can be applied in any
one of the following ways:
152.10.1
@Service applied to bean class
Applying the
@Service
annotation to the bean class
indicates the set of service types will be one of (in order of
precedence):
the specified type(s)
- When providing a
specified
value
, these
are the types under which the service is published.
// service types = [BassetHound, Dog]
@Service({BassetHound.class, Dog.class})
class Spot {}
directly implemented interfaces
- These
are the interfaces for which the bean class directly specifies an
implements
clause.
// service types = [Hound]
@Service
class Fido implements Hound {}
bean class
- The class of the bean itself
is the type under which the service is published.
// service types = [Fido]
@Service
class Fido
The
@Service
annotation is
never
inherited
. CCR ignores instances of the annotation on super
classes, interfaces or super interfaces for this purpose.
152.10.2
@Service applied to type use
A convenient readability optimization is to apply the
@Service
annotation on
type_use
. This
is to say that it may be applied to
extends
and/or
implements
clauses. For example:
// service types = [BassetHound]
class Fido extends @Service BassetHound {}
Or:
// service types = [Hound]
class Fido implements @Service Hound {}
The two approaches can be combined.
@Service
annotations are collected so that the service is published with all
collected types:
// service types = [BassetHound, Hound]
class Fido extends @Service BassetHound implements @Service Hound {}
In this scenario, any use of the
@Service.value
property will result in a definition error.
Applying
@Service
to both bean class, and type use
will result in a definition error.
152.10.3
@Service applied to Producers
Applying the
@Service
annotation to producer methods
or fields indicates the set of service types as described in the
following table (earlier rows take precedence over later rows).
Table
152
.5 @Service applied to Producers
Case
Description
the type(s) specified by
@Service.value
When providing a specified
@Service.value
, these are the types under which the
service is published.
// service types = [BassetHound, Dog]
@Produces
@Service({BassetHound.class, Dog.class})
Spot getSpot() {
return new Spot();
the returned interface
In the case of a producer method, if the return
type is an interface, this type is used as the service
type.
// service types = [Dog]
@Produces
@Service
Dog getDog() {
return new Spot();
all directly implemented interfaces of returned
type
In the case of a producer method, if the return
type is a concrete type, use any interfaces directly implemented
by the concrete type.
// service types = [Hound]
@Produces
@Service
Buddy getBuddy() {
return new Buddy();
the return type
In the case of a producer method, if the return
type is a concrete type which does not directly implement any
interfaces, use the concrete type.
class Fido {}

// service types = [Fido]
@Produces
@Service
Fido getFido() {
return new Fido();
the field interface
In the case of a producer field, if the field type
is an interface this type is used as the service type.
// service types = [Dog]
@Produces
@Service
Dog dog = new Spot();
all directly implemented interfaces of the field
type
In the case of a producer field, if the field type
is a concrete type use any interfaces directly implemented by
the concrete type.
// service types = [Hound]
@Produces
@Service
Buddy buddy = new Buddy();
the field type
In the case of a producer field if the field type
is a concrete type which does not directly implement any
interfaces use the concrete type.
class Fido {}

// service types = [Fido]
@Produces
@Service
Fido fido = new Fido();
152.10.4
@Service Type Restrictions
Regardless of the source, no service type may be a generic type. A
generic type found in the set of service types will result in a
definition error.
Service types must be a subset of bean types, including types
restricted by the use of the
@javax.enterprise.inject.Typed
annotation. This restriction is required to support CDI features like
Decorators
and
Interceptors
Using the
@Service
annotation on injection points
will result in a definition error.
152.10.5
Service Properties
The main source of service properties is
Component Properties
When CCR registers a service on behalf of a component instance,
CCR must follow the recommendations in
Property Propagation
and must not propagate
private configuration properties. That is, the service properties of the
registered service must be all the component properties of the component
configuration whose property names do not start with full stop
'.' \u002E
).
Component properties whose names start with full stop are
available to the component instance but are not available as service
properties of the registered service.
152.10.5.1
Container component service properties
In addition to component properties, services provided by the
container component obtain additional service properties from Bean
Property Types on the bean or producer providing the service. See
Bean Property Types
152.10.6
Service Scope
Service scope represents the scope of the registered service
object. There are three scopes supported by the OSGi Framework. Each can
be represented in CCR.
Bundle scope
- In order to specify a
bundle scoped service, the
@ServiceInstance
annotation is specified on the bean class, producer method or
producer field with the value
BUNDLE
@Service
@ServiceInstance(ServiceScope.BUNDLE)
class Fido implements Hound {}
Prototype scope
- In order to specify a
prototype scoped service, the
@ServiceInstance
annotation is specified on the bean class, producer method or
producer field with the value
PROTOTYPE
. The service
object is the contextual instance created by the producer or
bean.
@Service
@ServiceInstance(ServiceScope.PROTOTYPE)
class Fido implements Hound {}
Singleton scope
- Unless otherwise
specified, services are singleton scoped but the scope can be
explicitly expressed if the
@ServiceInstance
annotation is specified on the bean class, producer method or
producer field with the value
SINGLETON
. The service
object is the contextual instance created by the producer or
bean.
@Service
@ServiceInstance(ServiceScope.SINGLETON) // equal to omitting the annotation
class Fido implements Hound {}
152.10.7
Container Component Services
Beans, producer methods and producer fields that are
@ApplicationScoped
result in contextual instances that are
shared throughout the CDI container. Therefore they can only provide
singleton scoped services. Each such case results in a single service
registration. The service object is the contextual instance created by
the producer or bean. However,
@ApplicationScoped
beans can
implement
org.osgi.framework.ServiceFactory
or
org.osgi.framework.PrototypeServiceFactory
in order to
provide bundle or prototype scoped service objects.
Beans, producer methods and producer fields that are
@Dependent
result in contextual instances which are never
shared in that a new contextual instance is created for each caller.
Therefore they can provide services of all scopes as outlined in
Service Scope
. The service object is a
contextual instance created by the producer or bean on each request for
a service object.
The use of
@ServiceInstance
on
@ApplicationScoped
beans will result in a definition
error.
152.10.8
Single Component Services
Single components can only apply the
@Service
annotation to beans marked with
@SingleComponent
A single component providing a service results in a single service
registration.
Service objects provided by the service registration are defined
by the creation of
contexts
. In
all cases, the service object provided is the contextual instance of the
bean marked
@SingleComponent
obtained from the
context.
152.10.9
Factory Component Services
Factory components can only apply the
@Service
annotation to beans marked with
@FactoryComponent
A factory component providing a service results in one service
registration for every factory configuration object associated with the
factory PID of the component.
Service objects provided by the service registration are defined
by the creation of
contexts
. In
all cases, the service object provided is the contextual instance of the
bean marked
@FactoryComponent
obtained from the
context.
152.11
Component Property Injection Points
A bean specifies injection of component properties using the
@ComponentProperties
annotation at an injection point.
The type typically associated with component properties is
java.util.Map
@Inject
@ComponentProperties
Map componentProperties;
However, component properties can be automatically converted to any
type compatible with the
conversions
defined by the
Converter Specification
Given the following configuration properties:
pool.name (String)
min.threads (int)
max.threads (int)
keep.alive.timeout (long)
The following example demonstrates conversion of component
properties into a type safe object with defaults.
public static @interface PoolConfig {
String pool_name();
int min_threads() default 2;
int max_threads() default 10;
long keep_alive_timeout() default 500;

@Inject
@ComponentProperties
PoolConfig poolConfig;
Using
@Reference
in
conjunction with
@ComponentProperties
will result in a
definition error.
152.11.1
Coordinator Support
The
Coordinator Service Specification
defines a mechanism for
multiple parties to collaborate on a common task without
priori
knowledge of who will collaborate in that task. Like
Configuration Admin Service Specification
, CCR must participate in such scenarios to
coordinate with provisioning or configuration tasks.
If configuration changes occur and an implicit coordination
exists, CCR must delay taking action on the configuration changes until
the coordination terminates, regardless of whether the coordination
fails or terminates regularly.
152.12
Reference Injection Points
Any injection point annotated with
@Reference
declares a service dependency.
152.12.1
Reference injection point types
Injection points specifying
@Reference
are limited to
one of the following
injection point types
as
representations of the dependent service(s). Given that type
is a type under which a service is published, the
following
injection point types
are
supported:
Table
152
.6 Reference injection point types
Injection Point Type
Description
// S = Dog
@Inject
@Reference
Dog dog;
org.osgi.framework.ServiceReference
// S = Dog
@Inject
@Reference
ServiceReference dog;
java.util.MapObject>
In this case the
@Reference
annotation
must specify service type
using it's
value
property.
// S = Dog
@Inject
@Reference(Dog.class)
Map dogProperties;
Failure to
specify the type in this scenario results in a definition
error.
java.util.Map.EntryObject>, S>
Represents a
tuple
containing
the map of service properties as the key and the service
instance as the value.
// S = Dog
@Inject
@Reference
Map.Entry, Dog> dog;
BeanServiceObjects
// S = Dog
@Inject
@Reference
BeanServiceObjects dogs;
must be a concrete service type. The OSGi service
registry does not support generics, therefore
cannot
specify a generic type.
A definition error will result if any other types are used with
injection points marked
@Reference
unless otherwise
specified by this specification.
152.12.2
Reference Service scope
For a bound service, CCR must get the service object from the OSGi
Framework's service registry using the
getService
method on
the component's Bundle Context. If the service object for a bound
service has been obtained and the service becomes unbound, CCR must
unget the service object using the
ungetService
method on
the component's Bundle Context and discard all references to the service
object. This ensures that the bundle will only be exposed to a single
instance of the service object at any given time.
For a bound service of a reference where the
PrototypeRequired
annotation was specified, only services registered with prototype
service scope can be considered as target services. This ensures that
each component instance can be exposed to a single, distinct instance of
the service object. Using
@PrototypeRequired
effectively
adds
service.scope=prototype
to the
target property
of the
reference. A service that does not use prototype service scope cannot be
used as a bound service for a reference with
@PrototypeRequired
since the service cannot provide a
distinct service object for each component instance.
@Inject
@PrototypeRequired
@Reference
Hound hound;
152.12.3
Bean Service Objects
A Bean Service Objects for the bound service, can be used to
obtain the actual service object or objects. This approach is useful
when the referenced service has prototype service scope and the
component instance needs multiple service objects for the
service.
@Inject
@PrototypeRequired
@Reference
BeanServiceObjects hounds;
The
@PrototypeRequired
annotation is optional. See
Service Scope
152.12.4
Reference Greediness
References are greedy by default which means that higher ranking
matches are immediately bound. Use the
@Reluctant
annotation to indicate that higher ranking matches should not bind once
the reference has been resolved. Note that in the case of static
references the component will be destroyed and recreated in order to
immediately apply the better match. In the case of the container
component, this will result in the entire CDI container being destroyed
and recreated.
A static, greedy reference:
@Inject
@Reference
Hound hound;
A static, reluctant reference:
@Inject
@Reluctant
@Reference
Hound hound;
152.12.5
Service Type
As demonstrated earlier, it's possible to specify the service type
of the reference by using
@Reference.value()
property. This
supports use cases like
java.util.Map
where the service type cannot be determined.
@Inject
@Reference(Hound.class)
Map properties;
This makes it possible to target a more specific service type. A
reference injection point whose type is
Dog
may target a
service of type
BassetHound
@Inject
@Reference(BassetHound.class)
Dog dog;
The injection point type must be compatible with the service type.
Otherwise a definition error will result.
152.12.6
Any Service Type
A special exception to the service type rules is defined when the
special marker type
Reference.Any
is set as
@Reference.value
. This allows for any service to match the
reference. However, the following criteria must be satisfied:
@Reference.value
must specify the single value
Reference.Any.class
@Reference.target
must specify a valid, non-empty
filter value
The injection point
service type
must be
java.lang.Object
. For example:
@Inject
@Reference(value = Reference.Any.class, target = "(foo=bar)")
Optional