Fuse 6 is no longer supported
As of February 2025, Red Hat Fuse 6 is no longer supported. If you are using Fuse 6, please upgrade to Red Hat build of Apache Camel.Questo contenuto non è disponibile nella lingua selezionata.
Chapter 13. OSGi Services
Abstract
13.1. The Blueprint Container Copia collegamentoCollegamento copiato negli appunti!
Abstract
13.1.1. Blueprint Configuration Copia collegamentoCollegamento copiato negli appunti!
Location of blueprint files in a JAR file Copia collegamentoCollegamento copiato negli appunti!
OSGI-INF/blueprint
OSGI-INF/blueprint
.xml
, under this directory are interpreted as blueprint configuration files; in other words, any files that match the pattern, OSGI-INF/blueprint/*.xml
.
Location of blueprint files in a Maven project Copia collegamentoCollegamento copiato negli appunti!
ProjectDir/src/main/resources/OSGI-INF/blueprint
ProjectDir/src/main/resources/OSGI-INF/blueprint
Blueprint namespace and root element Copia collegamentoCollegamento copiato negli appunti!
http://www.osgi.org/xmlns/blueprint/v1.0.0
http://www.osgi.org/xmlns/blueprint/v1.0.0
blueprint
, so a blueprint XML configuration file normally has the following outline form:
<?xml version="1.0" encoding="UTF-8"?> <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"> ... </blueprint>
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
...
</blueprint>
blueprint
root element, there is no need to specify the location of the blueprint schema using an xsi:schemaLocation
attribute, because the schema location is already known to the blueprint framework.
Blueprint Manifest configuration Copia collegamentoCollegamento copiato negli appunti!
META-INF/MANIFEST.MF
, as follows:
Custom Blueprint file locations Copia collegamentoCollegamento copiato negli appunti!
OSGI-INF/blueprint/*.xml
), you can specify a comma-separated list of alternative locations in the Bundle-Blueprint
header in the manifest file—for example:
Bundle-Blueprint: lib/account.xml, security.bp, cnf/*.xml
Bundle-Blueprint: lib/account.xml, security.bp, cnf/*.xml
Mandatory dependencies Copia collegamentoCollegamento copiato negli appunti!
availability
attribute to optional
on a reference
element or a reference-list
element). Declaring a dependency to be mandatory means that the bundle cannot function properly without that dependency and the dependency must be available at all times.
Bundle-SymbolicName
manifest header to configure the grace period:
blueprint.graceperiod
- If
true
(the default), the grace period is enabled and the blueprint container waits for mandatory dependencies to be resolved during initialization; iffalse
, the grace period is skipped and the container does not check whether the mandatory dependencies are resolved. blueprint.timeout
- Specifies the grace period timeout in milliseconds. The default is 300000 (5 minutes).
Bundle-SymbolicName
header in the manifest file:
Bundle-SymbolicName: org.fusesource.example.osgi-client; blueprint.graceperiod:=true; blueprint.timeout:= 10000
Bundle-SymbolicName: org.fusesource.example.osgi-client;
blueprint.graceperiod:=true;
blueprint.timeout:= 10000
Bundle-SymbolicName
header is a semi-colon separated list, where the first item is the actual bundle symbolic name, the second item, blueprint.graceperiod:=true
, enables the grace period and the third item, blueprint.timeout:= 10000
, specifies a 10 second timeout.
13.1.2. Defining a Service Bean Copia collegamentoCollegamento copiato negli appunti!
Overview Copia collegamentoCollegamento copiato negli appunti!
bean
element. You can create all of your main application objects this way. In particular, you can use the bean
element to create a Java object that represents an OSGi service instance.
Blueprint bean element Copia collegamentoCollegamento copiato negli appunti!
bean
element is defined in the blueprint schema namespace, http://www.osgi.org/xmlns/blueprint/v1.0.0
. The blueprint {http://www.osgi.org/xmlns/blueprint/v1.0.0}bean
element should not be confused with the Spring {http://www.springframework.org/schema/beans}bean
selement, which has a similar syntax but is defined in a different namespace.
bean
element under the beans
root element, (as long as you define each bean
elements using the appropriate namespace prefix).
Sample beans Copia collegamentoCollegamento copiato negli appunti!
bean
element enables you to create objects using a similar syntax to the conventional Spring bean
element. One significant difference, however, is that blueprint constructor arguments are specified using the argument
child element, in contrast to Spring's constructor-arg
child element. The following example shows how to create a few different types of bean using blueprint's bean
element:
Account
class referenced by the last bean example could be defined as follows:
Differences between Blueprint and Spring Copia collegamentoCollegamento copiato negli appunti!
bean
element and the Spring bean
element are similar, there are a few differences, as you can see from Table 13.1, “Comparison of Spring bean with Blueprint bean”. In this table, the XML tags (identifiers enclosed in angle brackets) refer to child elements of bean
and the plain identifiers refer to attributes.
Spring DM Attributes/Tags | Blueprint Attributes/Tags |
---|---|
id | id |
name /<alias> | N/A |
class | class |
scope | scope=("singleton"|"prototype") |
lazy-init=("true"|"false") | activation=("eager"|"lazy") |
depends-on | depends-on |
init-method | init-method |
destroy-method | destroy-method |
factory-method | factory-bean |
factory-bean | factory-ref |
<constructor-arg> | <argument> |
<property> | <property> |
scope
attribute is singleton
and the default value of the blueprint activation
attribute is eager
.
References Copia collegamentoCollegamento copiato negli appunti!
- Spring Dynamic Modules Reference Guide v2.0 (see the blueprint chapters).
- Section 121 Blueprint Container Specification, from the OSGi Compendium Services R4.2 specification.
13.1.3. Exporting a Service Copia collegamentoCollegamento copiato negli appunti!
Overview Copia collegamentoCollegamento copiato negli appunti!
Exporting with a single interface Copia collegamentoCollegamento copiato negli appunti!
service
element that references the relevant service bean, using the ref
attribute, and specifies the published interface, using the interface
attribute.
SavingsAccountImpl
class under the org.fusesource.example.Account
interface name using the blueprint configuration code shown in Example 13.1, “Sample Service Export with a Single Interface”.
Example 13.1. Sample Service Export with a Single Interface
ref
attribute specifies the ID of the corresponding bean instance and the interface
attribute specifies the name of the public Java interface under which the service is registered in the OSGi service registry. The classes and interfaces used in this example are shown in Example 13.2, “Sample Account Classes and Interfaces”
Example 13.2. Sample Account Classes and Interfaces
Exporting with multiple interfaces Copia collegamentoCollegamento copiato negli appunti!
service
element that references the relevant service bean, using the ref
attribute, and specifies the published interfaces, using the interfaces
child element.
SavingsAccountImpl
class under the list of public Java interfaces, org.fusesource.example.Account
and org.fusesource.example.SavingsAccount
, using the following blueprint configuration code:
interface
attribute and the interfaces
element cannot be used simultaneously in the same service
element. You must use either one or the other.
Exporting with auto-export Copia collegamentoCollegamento copiato negli appunti!
auto-export
attribute.
SavingsAccountImpl
class under all of its implemented public interfaces, use the following blueprint configuration code:
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"> <bean id="savings" class="org.fusesource.example.SavingsAccountImpl"/> <service ref="savings" auto-export="interfaces"/> ... </blueprint>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
<bean id="savings" class="org.fusesource.example.SavingsAccountImpl"/>
<service ref="savings" auto-export="interfaces"/>
...
</blueprint>
interfaces
value of the auto-export
attribute indicates that blueprint should register all of the public interfaces implemented by SavingsAccountImpl
. The auto-export
attribute can have the following valid values:
disabled
- Disables auto-export. This is the default.
interfaces
- Registers the service under all of its implemented public Java interfaces.
class-hierarchy
- Registers the service under its own type (class) and under all super-types (super-classes), except for the
Object
class. all-classes
- Like the
class-hierarchy
option, but including all of the implemented public Java interfaces as well.
Setting service properties Copia collegamentoCollegamento copiato negli appunti!
service-properties
child element that contains one or more beans:entry
elements (one beans:entry
element for each service property).
bank.name
string property with a savings account service, you could use the following blueprint configuration:
bank.name
string property has the value, HighStreetBank
. It is possible to define service properties of type other than string: that is, primitive types, arrays, and collections are also supported. For details of how to define these types, see Controlling the Set of Advertised Properties. in the Spring Reference Guide.
entry
element ought to belong to the blueprint namespace. The use of the beans:entry
element in Spring's implementation of blueprint is non-standard.
Default service properties Copia collegamentoCollegamento copiato negli appunti!
service
element, as follows:
osgi.service.blueprint.compname
—is always set to theid
of the service'sbean
element, unless the bean is inlined (that is, the bean is defined as a child element of theservice
element). Inlined beans are always anonymous.service.ranking
—is automatically set, if the ranking attribute is non-zero.
Specifying a ranking attribute Copia collegamentoCollegamento copiato negli appunti!
0
being the default. You can specify the service ranking by setting the ranking
attribute on the service
element—for example:
<service ref="savings" interface="org.fusesource.example.Account" ranking="10"/>
<service ref="savings" interface="org.fusesource.example.Account" ranking="10"/>
Specifying a registration listener Copia collegamentoCollegamento copiato negli appunti!
registration-listener
child element to a service
element.
listenerBean
, which is referenced by a registration-listener
element, so that the listener bean receives callbacks whenever an Account
service is registered or unregistered:
registration-listener
element's ref
attribute references the id
of the listener bean, the registration-method
attribute specifies the name of the listener method that receives the registration callback, and unregistration-method
attribute specifies the name of the listener method that receives the unregistration callback.
Listener
class that receives notifications of registration and unregistration events:
register
and unregister
, are specified by the registration-method
and unregistration-method
attributes respectively. The signatures of these methods must conform to the following syntax:
- First method argument—any type T that is assignable from the service object's type. In other words, any supertype class of the service class or any interface implemented by the service class. This argument contains the service instance, unless the service bean declares the
scope
to beprototype
, in which case this argument isnull
(when the scope isprototype
, no service instance is available at registration time). - Second method argument—must be of either
java.util.Map
type orjava.util.Dictionary
type. This map contains the service properties associated with this service registration.
13.1.4. Importing a Service Copia collegamentoCollegamento copiato negli appunti!
Overview Copia collegamentoCollegamento copiato negli appunti!
reference
element or the reference-list
element to import an OSGi service. The key difference between these elements is not (as you might at first be tempted to think) that reference
returns a single service reference, while reference-list
returns a list of service references. Rather, the real difference is that the reference
element is suitable for accessing stateless services, while the reference-list
element is suitable for accessing stateful services.
Managing service references Copia collegamentoCollegamento copiato negli appunti!
Reference manager Copia collegamentoCollegamento copiato negli appunti!
reference
element. This element returns a single service reference and is the preferred approach for accessing stateless services. Figure 13.1, “Reference to Stateless Service” shows an overview of the model for accessing a stateless service using the reference manager.
Figure 13.1. Reference to Stateless Service
- If multiple services instances are found that match the criteria in the
reference
element, the reference manager can arbitrarily choose one of them as the backing instance (because they are interchangeable). - If the backing service disappears, the reference manager can immediately switch to using one of the other available services of the same type. Hence, there is no guarantee, from one method invocation to the next, that the proxy remains connected to the same backing service.
ServiceUnavailable
exception. The length of the timeout is configurable by setting the timeout
attribute on the reference
element.
Reference list manager Copia collegamentoCollegamento copiato negli appunti!
reference-list
element. This element returns a list of service references and is the preferred approach for accessing stateful services. Figure 13.2, “List of References to Stateful Services” shows an overview of the model for accessing a stateful service using the reference list manager.
Figure 13.2. List of References to Stateful Services
java.util.List
object (the provided object), which contains a list of proxy objects. Each proxy is backed by a unique service instance in the OSGi service registry. Unlike the stateless model, backing services are not considered to be interchangeable here. In fact, the lifecycle of each proxy in the list is tightly linked to the lifecycle of the corresponding backing service: when a service gets registered in the OSGi registry, a corresponding proxy is synchronously created and added to the proxy list; and when a service gets unregistered from the OSGi registry, the corresponding proxy is synchronously removed from the proxy list.
ServiceUnavailable
exception.
Matching by interface (stateless) Copia collegamentoCollegamento copiato negli appunti!
interface
attribute on the reference
element. The service is deemed to match, if the interface
attribute value is a super-type of the service or if the attribute value is a Java interface implemented by the service (the interface
attribute can specify either a Java class or a Java interface).
SavingsAccount
service (see Example 13.1, “Sample Service Export with a Single Interface”), define a reference
element as follows:
reference
element creates a reference manager bean with the ID, savingsRef
. To use the referenced service, inject the savingsRef
bean into one of your client classes, as shown.
SavingsAccount
. For example, you could define the Client
class as follows:
Matching by interface (stateful) Copia collegamentoCollegamento copiato negli appunti!
interface
attribute on the reference-list
element. The reference list manager then obtains a list of all the services, whose interface
attribute value is either a super-type of the service or a Java interface implemented by the service (the interface
attribute can specify either a Java class or a Java interface).
SavingsAccount
service (see Example 13.1, “Sample Service Export with a Single Interface”), define a reference-list
element as follows:
reference-list
element creates a reference list manager bean with the ID, savingsListRef
. To use the referenced service list, inject the savingsListRef
bean reference into one of your client classes, as shown.
savingsAccountList
bean property is a list of service objects (for example, java.util.List<SavingsAccount>
). You could define the client class as follows:
Matching by interface and component name Copia collegamentoCollegamento copiato negli appunti!
interface
attribute and the component-name
attribute on the reference
element, as follows:
<reference id="savingsRef" interface="org.fusesource.example.SavingsAccount" component-name="savings"/>
<reference id="savingsRef"
interface="org.fusesource.example.SavingsAccount"
component-name="savings"/>
interface
attribute and the component-name
attribute on the reference-list
element, as follows:
<reference-list id="savingsRef" interface="org.fusesource.example.SavingsAccount" component-name="savings"/>
<reference-list id="savingsRef"
interface="org.fusesource.example.SavingsAccount"
component-name="savings"/>
Matching service properties with a filter Copia collegamentoCollegamento copiato negli appunti!
filter
attribute on the reference
element or on the reference-list
element. The value of the filter
attribute must be an LDAP filter expression. For example, to define a filter that matches when the bank.name
service property equals HighStreetBank
, you could use the following LDAP filter expression:
(bank.name=HighStreetBank)
(bank.name=HighStreetBank)
&
conjunction, which combines expressions with a logical and
.For example, to require that the foo
property is equal to FooValue
and the bar
property is equal to BarValue
, you could use the following LDAP filter expression:
(&(foo=FooValue)(bar=BarValue))
(&(foo=FooValue)(bar=BarValue))
interface
and component-name
settings, in which case all of the specified conditions are required to match.
SavingsAccount
type, with a bank.name
service property equal to HighStreetBank
, you could define a reference
element as follows:
<reference id="savingsRef" interface="org.fusesource.example.SavingsAccount" filter="(bank.name=HighStreetBank)"/>
<reference id="savingsRef"
interface="org.fusesource.example.SavingsAccount"
filter="(bank.name=HighStreetBank)"/>
SavingsAccount
type, with a bank.name
service property equal to HighStreetBank
, you could define a reference-list
element as follows:
<reference-list id="savingsRef" interface="org.fusesource.example.SavingsAccount" filter="(bank.name=HighStreetBank)"/>
<reference-list id="savingsRef"
interface="org.fusesource.example.SavingsAccount"
filter="(bank.name=HighStreetBank)"/>
Specifying whether mandatory or optional Copia collegamentoCollegamento copiato negli appunti!
reference
element or a reference-list
element by setting the availability
attribute on the element. There are two possible values of the availability
attribute: mandatory
(the default), means that the dependency must be resolved during a normal blueprint container initialization; and optional
, means that the dependency need not be resolved during initialization.
reference
element shows how to declare explicitly that the reference is a mandatory dependency:
<reference id="savingsRef" interface="org.fusesource.example.SavingsAccount" availability="mandatory"/>
<reference id="savingsRef"
interface="org.fusesource.example.SavingsAccount"
availability="mandatory"/>
Specifying a reference listener Copia collegamentoCollegamento copiato negli appunti!
optional
availability—it is often useful to track when a backing service gets bound to the registry and when it gets unbound from the registry. To receive notifications of service binding and unbinding events, you can define a reference-listener
element as the child of either the reference
element or the reference-list
element.
savingsRef
:
org.fusesource.example.client.Listener
type as a callback that listens for bind
and unbind
events. Events are generated whenever the savingsRef
reference manager's backing service binds or unbinds.
Listener
class:
onBind
and onUnbind
, are specified by the bind-method
and unbind-method
attributes respectively. Both of these callback methods take an org.osgi.framework.ServiceReference
argument.