Spring-OSGI 1.0 M3 中文手册(Spring Dynamic Modules Reference Guide for OSGi(tm) Service Platforms)

Spring Dynamic Modules Reference Guide

for OSGi(tm) Service Platforms.

Version 1.0 M3

1.0 Introduction

This document is the reference guide for Spring Dynamic Modules. It defines the syntax and semantics for the OSGi Service Platform based namespaces; the Dynamic Modules extender bundle; and the OSGi manifest header entries defined by Dynamic Modules. For a tutorial introduction to building OSGi-based applications with Spring Dynamic Modules see the online tutorials and user guide.

OSGi developers looking for an introduction to Spring should review the introductory articles on the springframework.org site.

Note: OSGi is a trademark of the OSGi Alliance. Project name is pending final approval from the Alliance.

Note: Please see the known issues page for Spring Dynamic Modules 1.0 M3 release.

由于商标关系，Spring-osgi改名为 Spring Dynamic Modules

这个文档是Spring Dynamic Modules的手册。它定义了基于名字空间的OSGI服务平台的语法和语义，动态模块bundle和由动态模块定义的OSGI manifest header entries。通过在线指南和用户指南可以了解到使用Spring Dynamic Modules构造基于OSGI的应用

Why Spring Dynamic Modules?

The Spring Framework is the leading full-stack Java/JEE application framework. It provides a lightweight container and a non-invasive programming model enabled by the use of dependency injection, AOP, and portable service abstractions. The OSGi Service Platform offers a dynamic application execution environment in which modules (bundles) can be installed, updated, or removed on the fly. It also has excellent support for modularity and versioning.

Spring是一个全功能的Java/JEE应用框架。它提供了一个轻量级的容易和一个用于依赖注入的非侵入式编程模块，AOP功能和便携式服务抽取。OSGI服务平台提供了一个动态应用执行环境，模块能随时被加载，更新或卸载。当然它对模块和版本控制有很好的支持。

Spring Dynamic Modules makes it easy to write Spring applications that can be deployed in an OSGi execution environment, and that can take advantage of the services offered by the OSGi framework. Spring's OSGi support also makes development of OSGi applications simpler and more productive by building on the ease-of-use and power of the Spring Framework. For enterprise applications, the combination of Spring Dynamic Modules and the OSGi platform provides:

Better separation of application logic into modules, with runtime enforcement of module boundaries
The ability to deploy multiple versions of a module (or library) concurrently
The ability to dynamically discover and use services provided by other modules in the system
The ability to dynamically install, update and uninstall modules in a running system
Use of the Spring Framework to instantiate, configure, assemble, and decorate components within and across modules.
A simple and familiar programming model for enterprise developers to exploit the features of the OSGi platform.

We believe that the combination of OSGi and Spring offers a comprehensive model for building enterprise applications.\

Spring Dynamic Modules使编写一个部署在OSGI执行环境中的Spring应用变得简单，它能利用OSGI框架提供的服务。Spring的osgi支持也使构建在Spring框架中的OSGI应用开发变得更简单，更高产。对于企业级应用，Spring动态模块与OSGI平台的整合能提供以下功能：

模块内部更好的应用逻辑分离
同时部署同一模块的多个版本
在系统中动态发现和使用模块提供的服务
在系统运行时动态安装，更新和卸载模块
使用Spring框架初始化，配置，整合并使用模块中和跨模块的组件
对于使用OSGI平台特性的企业级开发者来说这些都是简单和熟悉的编程模型

Supported OSGi and JDK versions

Spring Dynamic Modules supports OSGi R4 and above, and JDK level 1.4 and above. Bundles deployed for use with Spring Dynamic Modules should specify "Bundle-ManifestVersion: 2" in their manifest. We test against Equinox, Felix, and Knopflerfish as part of our continuous integration process.

要使用Spring动态模块应该在MANIFEST.MF中指定 Bundle-ManifestVersion: 2

Structure of this document

Chapter 2, "Bundles and Application Contexts" describes the relationship between an OSGi Bundle and a Spring Application Context, and introduces the Spring Extender Bundle support for instantiating application contexts automatically.

第二章，"Bundles and Application Contexts"描述了OSGI Bundle与Spring Application Context 的关系，并且介绍了Spring Extender Bundle支持自动初始化应用上下文Application Contexts

Chapter 3, "Packaging and Deploying Spring-based OSGi applications" describes how to deploy the Spring Framework jar files in an OSGi environment, and how to reference external APIs from your application bundles should you need to do so. This chapter also explains some of the issues to be aware of when using existing enterprise libraries not designed for OSGi in an OSGi environment.

第三章，"Packaging and Deploying Spring-based OSGi applications" 描述了如何将Spring框架的jar文件部署到OSGI环境中，并且如何在你的应用bundles中引用外部APIs。本章还解释了在OSGI环境中当使用一些并不是为OSGI而设计的已经存在的企业类库时出现的问题

Chapter 4, "The Service Registry" describes how to export Spring beans as services in the OSGi service registry, and how to inject references to OSGi services into beans. This chapter also defines how the dynamic life-cycle of OSGi services and bundles is supported.

第四章，"The Service Registry" 描述了如何在OSGi service registry中将Spring beans做为服务输出，如何将OSGI服务引用注入到bean里。本章还定义了如何动态支持OSGI服务和Bundles的生命周期

Chapter 5, "Working with Bundles" describes how to declare a bean that represents an OSGi bundle, including support for installing new bundles into the OSGi platform.

第五章，"Working with Bundles" 描述了如何声明一个bean，表现为一个OSGI bundle，包括对安装一个新bundle到OSGI平台中的支持。

Chapter 6, "Compendium Services" describes the support provided for the OSGi Compendium Services, including the Configuration Admin service.

第六章，"Compendium Services" 描述了OSGi Compendium Services提供的支持，包括Configuration Admin service

Chapter 7, "Testing OSGi based Applications" explains the integration testing support provided by Spring Dynamic Modules. This support enables you to write simple JUnit integration tests that can start up an OSGi environment, install the bundles needed for the integration test, execute the test case(s) inside of OSGi, and return the results to the runner. This support makes it easy to integrate OSGi integration testing into any environment that can work with JUnit.

第七章，"Testing OSGi based Applications" 介绍了Spring动态模块提供的综合测试支持。这个功能使你能写一些简单的JUnit综合测试，这个功能能启动OSGI环境，安装测试所需的bundles，执行OSGI里的测试案例，并且返回结果。这个功能使将OSGI综合测试整合进任何JUnit环境变得简单。

Appendix A, "Extensions" describes extensions that are included in the 1.0 distribution, but are not guaranteed to be maintained in a backward-compatible form in future point releases. We anticipate these features moving into the core specification over time.

Appendix B, "Roadmap" describes some features that are included in the 1.0 distribution but are still considered early-access. The externals of these features may change in future releases. This appendix also discusses other planned features for which no implementation yet exists.

Appendix C defines the schemas provided by Spring Dynamic Modules.

2.0 Bundles and Application Contexts

The unit of deployment (and modularity) in OSGi is the bundle (see section 3.2 of the OSGi Service Platform Core Specification). A bundle known to the OSGi runtime is in one of three steady states: installed, resolved, or active. Bundles may export services (objects) to the OSGi service registry, and by so doing make these services available for other bundles to discover and to use. Bundles may also export Java packages, enabling other bundles to import the exported types.

OSGI中的一个部署（或模块）单元称为bundle。一个OSGI运行环境中的bundle有3个固定的状态：installed,resolved, active。这些bundle能做为服务输出到OSGi service registry,这样这些服务就能被其他bundle发现和使用。bundle也可以输出为java包，使其他bundle能够引用这些被输出的类型。

In Spring the primary unit of modularity is an application context, which contains some number of beans (objects managed by the Spring application context). Application contexts can be configured in a hierarchy such that a child application context can see beans defined in a parent, but not vice-versa. The Spring concepts of exporters and factory beans are used to export references to beans to clients outside of the application context, and to inject references to services that are defined outside of the application context.

Spring中最主要的模块单元是application context，它包含了一定数量的bean(由spring application context管理)。Application contexts可以被配置成父子层次，例如child application 能找到parent application 中定义的bean，反之则不行。Spring中的exporters和factory beans的是将bean引用输出到application context以外的客户端，并且将这些引用注入客户端定义的服务中。

There is a natural affinity between an OSGi bundle and a Spring application context. Using Spring Dynamic Modules, an active bundle may contain a Spring application context, responsible for the instantiation, configuration, assembly, and decoration of the objects (beans) within the bundle. Some of these beans may optionally be exported as OSGi services and thus made available to other bundles, beans within the bundle may also be transparently injected with references to OSGi services.

OSGi bundle和Spring application context是天生的一对(natural affinity)。如果使用了Spring Dynamic Modules（Spring-osgi），那么一个状态为active的bundle也许包含一个spring application context，它负责bundle中的bean的初始化，配置，整合和装载。

2.1 The Spring Dynamic Modules Extender bundle

Spring Dynamic Modules provides an OSGi bundle org.springframework.osgi.spring-osgi-extender. This bundle is responsible for instantiating the Spring application contexts for your application bundles. It serves the same purpose as the ContextLoaderListener does for Spring web applications. Once the extender bundle is installed and started it looks for any existing Spring-powered bundles that are already in the ACTIVE state and creates application contexts on their behalf. In addition, it listens for bundle starting events and automatically creates an application context for any Spring-powered bundle that is subsequently started. Section 3 describes what the extender recognizes as a "Spring-powered bundle".

Spring Dynamic Modules提供了一个OSGi bundle - org.springframework.osgi.spring-osgi-extender。这个bundle负责为你的application bundles初始化一个Spring application contexts。它的功能与Spring web applications中的ContextLoaderListener一样。一旦这个bundle(org.springframework.osgi.spring-osgi-extender)被安装并且启动，它将查找所有已经存在的具有spring-powered的状态为ACTIVE的bundle，然后为它们创建一个application context。另外，它还监听bundle的启动事件并自动为这个随后启动的bundle创建一个appliation context。第3节描述了什么样的bundle具备Spring-powered。

2.2 Application Context Creation

The extender bundle creates applications contexts asynchronously. This behavior ensures that starting an OSGi Service Platform is fast and that bundles with service inter-dependencies do not cause deadlock on startup. A Spring-powered bundle may therefore transition to the STARTED state before its application context has been created. It is possible to force synchronous creation of application contexts on a bundle-by-bundle basis. See section 3 for information on how to specify this behavior.

Spring的extender bundle (org.springframework.osgi.spring-osgi-extender)生成applications contexts是异步过程，不会使bundle间的相互依赖发生死锁而减缓OSGI服务平台的速度，因此一个具有Spring-powered的bundle的状态可能会在extender bundle为它生成生成application context之前就转变成STARTED。也可以强行一个bundle一个bundle的同步创建application contexts，第三节详细介绍了这个过程。

If application context creation fails for any reason then the failure cause is logged. The bundle remains in the STARTED state. There will be no services exported to the registry from the application context in this scenario.

任何一个application context创建失败都会被记录，bundle的状态继续保持为STARTED，并且这个bundle不会有任何服务被注册。

2.2.1 Mandatory Service Dependencies

If an application context declares mandatory dependencies on the availability of certain OSGi services (see section 4.0) then creation of the application context is blocked until all mandatory dependencies can be satisfied through matching services available in the OSGi service registry. Since a service may come and go at any moment in an OSGi environment, this behavior only guarantees that all mandatory services were available at the moment creation of the application context began. One or more services may subsequently become unavailable again during the process of application context creation. Section 4.0 describes what happens when a mandatory service reference becomes unsatisfied. In practice for most enterprise applications built using Spring Dynamic Modules services the set of available services and bundles will reach a steady state once the platform and its installed bundles are all started. In such a world the behavior of waiting for mandatory dependencies simply ensures that bundles A and B, where bundle A depends on services exported by bundle B, may be started in any order.

如果一个application context声明有强制依赖某个有效的OSGI服务，那么这个application context的线程将会暂时阻塞直到所有的强制依赖服务都与OSGi service registry中的服务相匹配。因为一个服务随时可能出现，所以这个阻塞过程仅仅能保证所有的强制依赖在application context生成时可用，而application context创建后某些服务可能会重新变得不可用。第四节描述了当一个强制依赖服务引用不匹配时会发生什么。在大多数用Spring Dynamic Modules构建服务的企业级应用实践中，一旦OSGI平台和它的已安装的bundle被启动后，这些服务和bundle就会达到一个稳定的状态。

A timeout applies to the wait for mandatory dependencies to be satisfied. By default the timeout is set to 5 minutes, but this value can be configured using the timeout directive. See section 3.0 for details.

超时用于等待强制依赖关系被解除，默认的超时时间是5分钟，但是可以通过配置修改这个值。具体细节参见3.0节

It is possible to change the application context creation semantics so that application context creation fails if all mandatory services are not immediately available upon startup (see section 3.1). When configured to not wait for dependencies, a bundle with unsatisfied mandatory dependencies will be stopped, leaving the bundle in the RESOLVED state.

如果系统启动时所有的依赖服务不能马上可用，可以修改application context的创建逻辑使application context创建失败。当带有强制依赖的bundle配置成不等待依赖服务时，它将被停止，状态标记为RESOLVED。

2.2.2 Application Context Service Publication

Once the application context creation for a bundle has completed, the application context object is automatically exported as a service available through the OSGi Service Registry. The context is published under the interface org.springframework.context.ApplicationContext (and also all of the visible super-interfaces and types implemented by the context). The published service has a service property named org.springframework.context.service.name whose value is set to the bundle symbolic name of the bundle hosting the application context. It is possible to prevent publication of the application context as a service using a directive in the bundle's manifest. See section 3.2 for details.

一旦bundle的application context创建完成，application context对象将通过OSGi Service Registry注册为服务，发布类型为org.springframework.context.ApplicationContext，它会包含一个属性org.springframework.context.service.name，值为它的bundle的标记名（symbolic name）。可以通过配置bundle的MANIFEST.MF使application context不做为一个服务发布。
Note: the application context is published as a service primarily to facilitate testing, administration, and management. Accessing this context object at runtime and invoking getBean() or similar operations is discouraged. The preferred way to access a bean defined in another application context is to export that bean as an OSGi service from the defining context, and then to import a reference to that service in the context that needs access to the service. Going via the service registry in this way ensures that a bean only sees services with compatible versions of service types, and that OSGi platform dynamics are respected.

注意：application context发布为服务主要是为了方便测试，管理和操作。不鼓励运行时访问context对象和通过getBean()之类的方法。要访问一个定义在别的application context中的bean，更好的方法是在那个application context中将bean输出为OSGi服务，然后在需要访问这个服务的application context中引入服务的引用，通过服务注册，可以确保一个bean只能看见与之版本兼容的服务类型，这也是OSGi动态平台所注重的地方。

2.3 Bundle Lifecycle

OSGi is a dynamic platform: bundles may be installed, started, updated, stopped, and uninstalled at any time during the running of the framework.

OSGi是一个动态平台：运行中的OSGi框架可以在任何时候安装，启动，更新，停止和卸载bundle。

When an active bundle is stopped, any services it exported during its lifetime are automatically unregistered and the bundle returns to the resolved state. A stopped bundle should release any resources it has acquired and terminate any threads. Packages exported by a stopped bundle continue to be available to other bundles.

当一个活动的bundle被停止时，在它处于激活状态时输出的任何服务将自动卸载，并且它的状态会返回到RESOLVED。一个停止活动的bundle应该释放它所有获得的资源并终止所有它开启的线程。但是它输出的packages仍然对其他bundles有效。

A bundle in the resolved state may be uninstalled: packages that were exported by an uninstalled bundle continue to be available to bundles that imported them (but not to newly installed bundles).

一个状态为RESOLVED的bundle可以被卸载：一个被卸载的bundle输出的packages对其他已经存在的bundles仍然有效（但是对新安装的bundles无效）。

A bundle in the resolved state may also be updated. The update process migrates from one version of a bundle to another version of the same bundle.

一个状态为RESOLVED的bundle也可以被更新。这个更新过程是指同一个bundle从一个版本移植到另一个版本。

Finally of course a resolved bundle can be started, which transitions it to the active state.

最后一个状态为RESOLVED的bundle还可以被启动，它的状态则改变为ACTIVE。

The OSGi PackageAdminrefreshPackages operation refreshes packages across the whole OSGi framework or a given subset of installed bundles. During the refresh, an application context in an affected bundle will be stopped and restarted. After a refreshPackages operation, packages exported by older versions of updated bundles, or packages exported by uninstalled bundles, are no longer available. Consult the OSGi specifications for full details.

OSGi中的org.osgi.service.packageadmin.PackageAdmin.refreshPackages(Bundle[] bundles)可以刷新整个OSGi框架或指定的一列已安装的bundles中的packages。如果某个bundle被刷新，那么它的application context将会被停止然后刷新。refreshPackages方法执行完毕后，被更新的旧版本的或被卸载了的bundle的packages将不再有效。具体细节参见OSGi规范。

When a Spring-powered bundle is stopped, the application context created for it is automatically destroyed. All services exported by the bundle will be unregistered (removed from the service registry) and the normal application context tear-down life-cycle is observed (DisposableBean and destroy-method callbacks are invoked on beans in the context).

当一个具有Spring-powered的bundle被停止时，它的application context将自动销毁，它输出的服务将被注销（从service registry删除），然后application context生命周期的正常注销将开始执行（回调context中所有bean的destroy-method）

If a Spring-powered bundle that has been stopped is subsequently re-started, a new application context will be created for it.

如果一个已经停止的具有Spring-powered的bundle后来又重新启动，那么一个新的application context将会被创建。

2.4 The Resource abstraction

The Spring Framework defines a resource abstraction for loading resources within an application context (see Spring's resource abstraction). All resource loading is done through the ResourceLoader associated with the application context. The ResourceLoader is also available to beans wishing to load resources programmatically. Resource paths with explicit prefixes - for example "classpath:" are treated uniformly across all application context types (for example, web application contexts and classpath-based application contexts). Relative resource paths are interpreted differently based on the kind of application context being created. This enables easy integration testing outside of the ultimate deployment environment.

Spring框架为从application context中加载资源定义了一个资源提取功能。通过与application context相关联的ResourceLoader可以完成资源加载。ResourceLoader也适用于bean在程序中加载资源。资源路径会有很清楚的前缀 - 例如“classpath:”前缀将一律被看成是跨application context级的类型（例如web application contexts和基于classpath的application contexts）。其他相关的资源路径则根据application context的创建方式不同而不同，这使得最终部署环境的外部综合测试变得简单。

The Spring extender bundles creates a special subclass of application context, an OSGiApplicationContext. An OSGi application context treats a relative resource path as a reference to a resource defined within the bundle (the bundle and its attached fragments will be searched for matching resources). The context also supports the explicit resource path prefixes osgibundle and osgibundlejar.

The Spring extender bundles会创建一个特殊的application context的子application context - OSGiApplicationContext（只适用于OSGi环境的application context）。一个OSGi application context将相关的资源路径看成定义在bundle中的资源引用（在bundle和它的附加文件中查找匹配的资源）。这个OSGi application context也支持前缀为 "osgibundle:" 和 "osgibundlejar:" 的资源路径。

A resource path of the format "osgibundle:x/y/z" searches for resource "x/y/z" in the bundle and its attached fragments (this is the same as the relative resource behavior).

一个格式为"osgibundle:x/y/z"的资源路径表示在bundle和它的附加文件中查找资源"x/y/z"（这与其它的查找方式是相似的）。

A resource path of the format "osgibundlejar:x/y/z" searches for resource "x/y/z" in the bundle only, ignoring any attached fragments.

一个格式为"osgibundlejar:x/y/z"的资源路径表示仅仅在bundle中查找资源"x/y/z"，不在附加文件中查找。

A resource path using the "classpath:" prefix searches the bundle classpath for matching resources.

一个使用前缀为"classpath:"的资源路径则在bundle的classpath中查找匹配的资源。

All of the regular Spring resource prefixes such as "file:" and "http:" are also supported, as are the pattern matching wildcards. Resources loaded using such prefixes may come from any location, they are not restricted to being defined within the resource-loading bundle or its attached fragments.

类似"file:" 和 "http:"，Spring中列出的资源路径前缀和通配符匹配模式也是被支持的，使用这些前缀加载的资源可能会来自任何位置，这些资源在bundle或bundle的附加片段中的定义是不被限制的。

OSGi platforms may define their own unique prefixes for accessing bundle contents. For example, Equinox defines the 'bundleresource:' and 'bundlentry:' prefixes). These platform specific prefixes may also be used with Spring OSGi, at the cost of course of tying yourself to a particular OSGi implementation.

OSGi平台可能会定义它自己的唯一前缀去访问bundle。例如，Equinox定义了'bundleresource:'和'bundlentry:'。这些平台所特有的前缀也可能会被Spring OSGi使用，这取决于你使用的是什么OSGi实现框架(Equinox，Felix等)。

2.5 Accessing the BundleContext

In general there is no need to depend on any OSGi APIs when using the Spring Dynamic Modules support. If you do need access to the OSGi BundleContext object for your bundle, then Spring makes this easy to do.

通常情况下，在使用Spring Dynamic Modules时是不需要使用任何OSGi APIs的，如果你需要在你的bundle中使用OSGi的BundleContext对象，那么Spring可以很轻松的做到这一点。

The OSGi application context created by the Spring extender will automatically contain a bean of type BundleContext and with name bundleContext. You can inject a reference to this bean into any bean in the application context either by-name or by-type. In addition, Spring Dynamic Modules defines the interface org.springframework.osgi.context.BundleContextAware:

如果一个bundle具有Spring-powered，由Spring extender为其创建的OSGi application context将自动包含一个类型为org.osgi.framework.BundleContext的bean，变量名为bundleContext。你可以通过bean名字或类型将这个bean注入到application context中的任何一个bean中。另外Spring Dynamic Modules还定义了这样一个接口：
public interface BundleContextAware { public void setBundleContext(BundleContext context); }

Any bean implementing this interface will be injected with a reference to the bundle context when it is configured by Spring. If you wish to use this facility within a bundle, remember to import the package org.springframework.osgi.context in your bundle manifest.

任何实现了这个接口的bean被Spring初始化时都会被注入一个bundle context。你需要在bundle的manifest中引入org.springframework.osgi.context才能使用这个功能。

2.5.1 ThreadLocal access to BundleContext

During creation of an application context, access to the BundleContext object for the bundle is also available through an inheritable thread-local variable. This variable is accessible via the org.springframework.osgi.context.support.LocalBundleContext class.

在一个application context被创建的时候，通过thread-local变量也可以使用BundleContext对象。这个变量通过类org.springframework.osgi.context.support.LocalBundleContext访问。

public class LocalBundleContext { public static BundleContext getContext(); }

In addition, when an operation is invoked on an OSGi service reference injected by Spring, Spring makes sure that the invoking bundle's BundleContext is accessible on the invoking thread via the LocalBundleContext.

另外，当一个由Spring注入的OSGi服务被调用的时候，Spring会通过LocalBundleContext确保调用的bundle的BundleContext在调用线程中是可用的。

2.6 Stopping the extender bundle

If the extender bundle is stopped, then all the application contexts created by the extender will be destroyed. Application contexts are shutdown in the following order:

如果spring extender bundle被停止，那么它创建的所有application contexts将被注销。Application contexts的关闭顺序如下：

Application contexts that do not export any services, or that export services that are not currently referenced, are shutdown in reverse order of bundle id. (Most recently installed bundles have their application contexts shutdown first).

Application contexts没有输出任何服务或输出的服务没有被引用，那么则根据它们内部的bundle ID从大到小的顺序关闭（跟堆栈类似，后生成的application contexts先关闭）。
Shutting down the application contexts in step (1) may have released references these contexts were holding such that there are now additional application contexts that can be shutdown. If so, repeat step 1 again.

步骤（1）中关闭的application contexts可能已经释放了被它们持有的其他application contexts的引用，于是更多的application contexts就能够被关闭了，如果是这样，则重复步骤一。
If there are no more active application contexts, we have finished. If there are active application contexts then there must be a cyclic dependency of references. The circle is broken by determining the highest ranking service exported by each context: the bundle with the lowest ranking service in this set (or in the event of a tie, the highest service id), is shut down. Repeat from step (1).

如果没有application contexts处于激活状态，那么就完成了关闭。如果还有处于激活的application contexts，那么一定有被嵌套依赖的引用。解除这个嵌套依赖关系将由各个context输出的最高队列等级的服务决定：通过重复步骤（1）关闭这个嵌套依赖中级别最低的服务的bundl。

3.0 Packaging and Deploying Spring-based OSGi applications

A traditional Spring application uses either a single application context, or a parent context containing service layer, data layer, and domain objects with a child context containing web layer components. The application context may well be formed by aggregating the contents of multiple configuration files.

通常Spring application使用单一的application context或是一个带有包含web层组件的子context的父context，它们包含服务层，数据层和域对象。application context可以又多个配置文件集成的内容组成。

When deploying an application to OSGi the more natural structure is to package the application as a set of peer bundles (application contexts) interacting via the OSGi service registry. Independent subsystems should be packaged as independent bundles or sets of bundles (vertical partitioning). A subsystem may be package in a single bundle, or divided into several bundles partitioned by layer (horizontal partitioning). A straightforward web application may for example be divided into four modules (bundles): a web bundle, service layer bundle, data layer bundle, and domain model bundle. Such an application would look like this:

将一个应用部署到OSGi中更好的结构是将这些应用打包成一系列的bundles，它们通过OSGi service registry 相互作用。独立的子系统应该被打包成一个独立的bundle或划分成多个bundles（垂直划分）或是通过不通的层划分成多个bundles（水平划分）。例如，一个简单的web application可能会被划分成4个模块（4个bundle）：页面显示层bundle，服务层bundle，数据层bundle和域模型bundl。

In this example the data layer bundle yields a data layer application context that contains a number of internal components (beans). Two of those beans are made publicly available outside of the application context by publishing them as services in the OSGi service registry.

在这个例子中，数据层bundle生成一个包含了很多内部组件(beans)的数据层application context。在the OSGi service registry中将这些bean中的其中2个bean做为服务发布可以在application context外部使用它们。

The service layer bundle yields a service layer application context that contains a number of internal components (beans). Some of those components depend on data layer services, and import those services from the OSGi service registry. Two of the service layer components are made externally available as services in the OSGi service registry.

服务层bundle生成一个包含了很多内部组件(beans)的服务层application context。它们中的某些组件依赖于从OSGi service registry中引入的数据层的服务。

The web component bundle yields a web application context that contains a number of internal components (beans). Some of those components depend on application services, and import those services from the OSGi service registry. Since the domain model bundle contributes only domain model types, but does not need to create any components of its own, it has no associated application context.

3.1 Bundle format and Manifest headers

Each application module should be packaged as an OSGi bundle. A bundle is essentially a jar file with a META-INF/MANIFEST.MF file containing a series of headers recognized by the OSGi Service Platform. See the OSGi Service Platform Core Specification section 3.2 for details. Some OSGi implementations may support exploded jar files, but the format remains the same.

每一个应用模块都应该打包成一个OSGi bundle。一个bundle其实就是一个含有META-INF/MANIFEST.MF的jar包，META-INF/MANIFEST.MF中有一系列经过OSGi服务平台验证的headers。关于headers的细节参见OSGi规范中的3.2节。一些OSGi实现框架可能会支持一些与众不同的jar包，但是这些jar包关于OSGi的格式还是不变的。

The Spring extender recognizes a bundle as "Spring-powered" and will create an associated application context when the bundle is started if one or both of the following conditions is true:

如果满足以下两个条件，Spring extender会通过一个bundle的具有"Spring-powered"的验证，当这个bundle启动时会为其创建一个相关联的application context：

The bundle classpath contains a folder META-INF/spring with one or more files in that folder with a '.xml' extension.

这个bundle的classpath包含一个目录META-INF/spring，这个目录中有一个或多个扩展名为'.xml'的文件。
META-INF/MANIFEST.MF contains a manifest header Spring-Context.

这个bundle中的META-INF/MANIFEST.MF文件包含一个名为Spring-Context的header。

In addition, if the optional SpringExtender-Version header is declared in the bundle manifest, then the extender will only recognize bundles where the specified version constraints are satisfied by the version of the extender bundle (Bundle-Version). The value of the SpringExtender-Version header must follow the syntax for a version range as specified in section 3.2.5 of the OSGi Service Platform Core Specification.

另外，如果bundle的manifest声明了可选header - SpringExtender-Version，那么extender将仅仅认可与之版本相符的指定版本约束的bundle（bundle的Bundle-Version）。SpringExtender-Version的值必须遵循OSGi规范3.2.5节中指定的版本范围。

In the absence of the Spring-Context header the extender expects every ".xml" file in the META-INF/spring folder to be a valid Spring configuration file, and all directives (see below) take on their default values.

在缺少Spring-Context的情况下，spring extender仍然认为所有META-INF/spring中".xml"的文件都是spring的配置文件，所有的header都是默认值。

An application context is constructed from this set of files. A suggested practice is to split the application context configuration into at least two files, named by convention modulename-context.xml and modulename-osgi-context.xml. The modulename-context.xml file contains regular bean definitions independent of any knowledge of OSGi. The modulename-osgi-context.xml file contains the bean definitions for importing and exporting OSGi services. It may (but is not required to) use the Spring Dynamic Modules OSGi schema as the top-level namespace instead of the Spring 'beans' namespace.

application context就是根据这些文件(META-INF/spring中".xml"的文件)构造的。一个推荐的做法是将application context配置文件至少分割成2个文件，习惯上命名为 [模块名－context.xml] 和[模块名-osgi-context.xml]。modulename-context.xml文件包含了不依赖与OSGi相关的bean的定义（可以理解为普通bean定义）。modulename-osgi-context.xml文件则定义那些引入或输出OSGi服务的bean。这可能需要使用Spring Dynamic Modules的OSGi schema做为顶级命名空间，取代spring的'bean'命名空间，但这不是必须的。

=====================以下是 Spring-Context的相关内容和配置，主要意思如下：

1.如果在Spring-Context指定了配置文件，那么extender将忽略 META-INF/spring 中的配置文件，除非明确指定。
2.可以用通配符，例如Spring-Context: osgi-*; 3.create-asynchronously=false（默认值是true），使用同步方式创建该bundle的application context。有一点需要注意，同步创建application context的过程是在OSGi的事件线程中进行的，它将阻塞这个线程的事件发送，直到完成application context的初始化。如果这个过程中发生了错误，那么将出现一个FrameworkEvent.ERROR，但是bundle的状态仍然还是ACTIVE。 4.wait-for-dependencies和timeout，从字面意思就能看出来了。 5.publish-context:=false（默认值是true)，不将application context作为一个服务发布。
The Spring-Context manifest header may be used to specify an alternate set of configuration files. The resource paths are treated as relative resource paths and resolve to entries defined in the bundle and the set of attached fragments. When the Spring-Context header defines at least one configuration file location, any files in META-INF/spring are ignored unless directly referenced from the Spring-Context header.

The syntax for the Spring-Context header value is:

Spring-Context-Value ::= context ( ',' context ) *
context ::= path ( ';' path ) * (';' directive) *

This syntax is consistent with the OSGi Service Platform common header syntax defined in section 3.2.3 of the OSGi Service Platform Core Specification.

For example, the manifest entry:

Spring-Context: config/account-data-context.xml, config/account-security-context.xml
will cause an application context to be instantiated using the configuration found in the files account-data-context.xml and account-security-context.xml in the bundle jar file.

A number of directives are available for use with the Spring-Context header. These directives are:

create-asynchronously (false|true): controls whether the application context is created asynchronously (the default), or synchronously.

For example:

Spring-Context: *;create-asynchronously=false

Creates an application context synchronously, using all of the "*.xml" files contained in the META-INF/spring folder.

Spring-Context: config/account-data-context.xml;create-asynchrously:=false
Creates an application context synchronously using the config/account-data-context.xml configuration file. Care must be taken when specifying synchronous context creation as the application context will be created on the OSGi event thread, blocking further event delivery until the context is fully initialized. If an error occurs during the synchronous creation of the application context then a FrameworkEvent.ERROR event is raised. The bundle will still proceed to the ACTIVE state.

wait-for-dependencies (true|false): controls whether or not application context creation should wait for any mandatory service dependencies to be satisfied before proceeding (the default), or proceed immediately without waiting if dependencies are not satisfied upon startup.

For example:

Spring-Context: config/osgi-*.xml;wait-for-dependencies:=false

Creates an application context using all the files matching "osgi-*.xml" in the config directory. Context creation will begin immediately even if dependencies are not satisfied. This essentially means that mandatory service references are treated as though they were optional - clients will be injected with a service object that may not be backed by an actual service in the registry initially. See section 4.2 for more details.

timeout (300): the time to wait (in seconds) for mandatory dependencies to be satisfied before giving up and failing application context creation. This setting is ignored if wait-for-dependencies:=false is specified. The default is 5 minutes (300 seconds).

For example:

Spring-Context: *;timeout:=60

publish-context (true|false): controls whether or not the application context object itself should be published in the OSGi service registry. The default is to publish the context.

For example:

Spring-Context: *;publish-context:=false

If there is no Spring-Context manifest entry, or no value is specified for a given directive in that entry, then the directive takes on its default value.

3.2 Required Spring Framework and Spring Dynamic Modules Bundles

The Spring Dynamic Modules project provides an number of bundle artifacts that must be installed in your OSGi platform in order for the Spring extender to function correctly:

Spring Dynamic Modules提供了很多现成的bundle，要使用Spring extender必须将这些bundle安装到OSGi平台中:

The extender bundle itself, org.springframework.osgi.extender
The core implementation bundle for the Spring Dynamic Modules support, org.springframework.osgi.core
The Spring Dynamic Modules i/o support library bundle, ' org.springframework.osgi.io

In addition the Spring Framework provides a number of bundles that are required to be installed. As of release 2.5 of the Spring Framework, the Spring jars included in the Spring distribution are valid OSGi bundles and can be installed directly into an OSGi platform. The minimum required set of bundles is:

另外spring还提供了很多它自己的bundle，这些bundle可以直接被安装到OSGi平台中。要使用spring的最低要求需要以下几个bundle:

spring-core.jar (bundle symbolic name org.springframework.core)
spring-context.jar (bundle symbolic name org.springframework.context)
spring-beans.jar (bundle symbolic name org.springframework.beans)
spring-aop.jar (bundle symbolic name org.springframework.aop)

In additional the following supporting library bundles are required. OSGi-ready versions of these libraries are shipped with the Spring Dynamic Modules distribution.

以下几个bundle是spring的依赖bundle，可以在Spring Dynamic Modules的分发包中找到它们:

aopalliance
backport-util (for JDK 1.4)
cglib-nodep
commons-logging (SLF4J version highly recommended)

3.3 Importing and Exporting packages

Refer to the OSGi Service Platform for details of the Import-Package and Export-Package manifest headers. Your bundle will need an Import-Package entry for every external package that the bundle depends on. If your bundle provides types that other bundles need access to, you will need Export-Package entries for every package that should be available from outside of the bundle.

这部份是关于OSGi平台MANIFEST中Import-Package和Export-Package的细节描述。你的bundle中的MANIFEST.MF需要一个Import-Package来引入它所依赖的外部package。如果你的bundle提供的type需要被其他bundle使用，你需要使用Export-Package将每一个对外部bundle可用的package输出。

3.4 Considerations when using external libraries

Many enterprise application libraries assume that all of the types and resources that comprise the application are accessible through the context class loader. In OSGi R4, the set of types and resources available through the context class loader is undefined. Libraries that generate new classes dynamically can also cause problems in an OSGi environment.

许多企业级应用程序中的libraries(假设这个libraries是组成这个用应用程序的所有types和资源)都能通过context class loader访问和使用，但是在OSGi R4规范中，确不是这样定义的，同样，在OSGi环境中libraries动态生成classes也会产生问题。

Spring Dynamic Modules guarantees that during the creation of an application context on behalf of a given bundle, all of that types and resources on the bundle's classpath are accessible via the context class loader. Spring Dynamic Modules also allows you to control what is accessible through the context class loader when invoking external services and when servicing requests on exported services. See section 4 for details on this.

Spring Dynamic Modules确保了在为bundle生成application context的时候，bundle的classpath下的所有types和资源都可以通过这个application context的classloader去访问和使用。当调用外部服务和响应对输出服务的请求时，Spring Dynamic Modules也允许你控制所有能通过context的classloader访问的资源。具体细节参加第四部份。

Work is underway in the OSGi R5 timeframe to provide standardized support for dealing with generated classes and implicit class path dependencies introduced by third-party libraries. In the interim you may need to rely on workarounds such as the DynamicImport-Package manifest header, or the facilities provided by specific OSGi implementations such as Equinox's buddy mechanism. The Spring Dynamic Modules tutorial contains more detail on known issues with common enterprise libraries and the workarounds.

3.5 Diagnosing problems

Your chosen OSGi platform implementation should be able to provide you with a good deal of information about the current status of the OSGi environment. For example, starting Equinox with the -console argument provides a command-line console through which you can determine which bundles are installed and their states, the packages and services exported by bundles, find out why a bundle has failed to resolve, and drive bundles through the lifecycle.

OSGi实现框架应该提供很多关于OSGi环境当前状态的信息。例如通过参数-console启动的Equinx会提供一个命令行控制台，通过这个控制台你可以看到哪些bundle被安装了，这些bundle的状态，这些bundle输出的package和服务，找到bundle解析失败的原因，改变bundle生命周期状态。

In addition, Spring itself and the Spring Dynamic Modules bundles contain extensive logging instrumentation that can help you diagnose problems. The recommended approach is to deploy the Simple Logging Facade for Java (slf4j) slf4j-api.jar and slf4j-log4j13.jar bundles (the jar files distributed by the project are valid OSGi bundles). Then you simply need to create a log4j.properties file in the root of your bundle classpath.

另外，spring本身和Spring Dynamic Modules bundles包含了logging的扩展包，能帮助你找到问题。推荐的做法是将Simple Logging Facade for Java (slf4j)的slf4j-api.jar和slf4j-log4j13.jar部署成bundle（分发包中的jar包已经是可用的OSGi bundle了），然后你只需要简单的将log4j.properties放到bundle classpath的根目录下。

4.0 The Service Registry

The OSGi service registry enables a bundle to publish objects to a shared registry, advertised via a given set of Java interfaces. Published services also have service properties associated with them in the registry.

OSGi服务注册器(The OSGi service registry )允许一个bundle将对象发布到一个共享的注册器中，通过一系列java 接口发布注册通知，同时也会有一些服务属性伴随着已经发布的服务。

Spring Dynamic Modules provides an 'osgi' namespace for Spring (see Appendix B) that can be used to export Spring beans as OSGi services, and to define references to services obtained via the service registry. The namespace elements may be used nested inside another top-level namespace (typically the Spring 'beans' namespace), or within the top-level osgi element.

Spring Dynamic Modules提供了一个叫'osgi'的命名空间（见附录B），它可以用来将spring bean做为OSGi服务输出，也可以用来定义从service registry中获得的服务的引用。这个命名空间节点可以被嵌套在其他的顶级命名空间中（特别是Spring的'bean'名字空间），或是在顶级命名空间为'osgi'的节点中。

The following example shows the use of the osgi namespace within the familiar Spring beans element:

<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:osgi="http://www.springframework.org/schema/osgi" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/osgi http://www.springframework.org/schema/osgi/spring-osgi.xsd">  <osgi:service id="simpleServiceOsgi" ref="simpleService" interface="org.xyz.MyService" /> </beans>

Using the OSGi namespace as a top-level namespace the same service would be declared as follows:

<?xml version="1.0" encoding="UTF-8"?>
<osgi xmlns="http://www.springframework.org/schema/osgi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/osgi
http://www.springframework.org/schema/osgi/spring-osgi.xsd">
<!-- use the OSGi namespace elements directly -->
<service id="simpleServiceOsgi" ref="simpleService"
interface="org.xyz.MyService" />
</osgi>

Using the OSGi namespace as a top-level namespace is particularly convenient when following the recommendation of section 3.1 to use a dedicated configuration file for all OSGi-related declarations.

使用OSGi名字空间做为顶级名字空间是推荐做法。

4.1 Exporting a Spring bean as an OSGi service

The service element is used to define a bean representing an exported OSGi service. At a minimum you must specify the bean to be exported, and the service interface that the service offers.

For example, the declaration

<service>节点用来定义将一个bean描述成一个被输出的OSGi服务，而这至少需要你指定这个要被输出为服务的bean，和服务的接口类型，例如这个声明： <service ref="beanToPublish" interface="com.xyz.MessageService"/>
exports the bean with name beanToPublish with interface com.xyz.MessageService. The published service will have a service property with the name org.springframework.osgi.beanname set to the name of the target bean being registered (beanToPublish in this case).

这个声明将一个名字为'beanToPublish'输出为接口类型为com.xyz.MessageService的服务，这个服务将会有一个名字为org.springframework.osgi.beanname的service属性，它的值将被设置为bean的名字（在本例中为 beanToPublish）。

The bean defined by the service element is of type org.osgi.framework.ServiceRegistration and is the ServiceRegistration object resulting from registering the exported bean with the OSGi service registry. By giving this bean an id you can inject a reference to the ServiceRegistration object into other beans if needed. For example:

由<service>节点定义的bean的类型是org.osgi.framework.ServiceRegistration,是通过将bean输出的服务注册到the OSGi service registry中形成的ServiceRegistration对象。通过设置一个ID属性可以将这个对象的引用注入到任何一个bean中，例如：
<service id="myServiceRegistration" ref="beanToPublish" interface="com.xyz.MessageService"/>
As an alternative to exporting a named bean, the bean to be exported to the service registry may be defined as an anonymous inner bean of the service element. Typically the top-level namespace would be the beans namespace when using this style:

做为可选择的bean定义，一个输出到service registry中的bean还可以被定义为一个<service>节点的匿名内部bean。使用下面这种风格的定义是使用<beans>做为顶级名字空间的典型代表。

<osgi:service interface="com.xyz.MessageService"> <bean class="SomeClass"> ... </bean> </osgi:service>

If the bean to be exported implements the org.osgi.framework.ServiceFactory interface then the ServiceFactory contract is honored as per section 5.6 of the OSGi Service Platform Core Specification. As an alternative to implementing this OSGi API, Spring Dynamic Modules introduces a new bean scope, the bundle scope. When a bean with bundle scope is exported as an OSGi service then one instance of the bean will be created for each unique client (service importing) bundle that obtains a reference to it through the OSGi service registry. When a service importing bundle is stopped, the bean instance associated with it is disposed. To declare a bean with bundle scope simply use the scope attribute of the bean element:

按照OSGi服务平台核心规范，如果一个被输出的bean实现了接口org.osgi.framework.ServiceFactory，那么这个ServiceFactory对象与bundle间将会产生一个很受重视的关系。Spring Dynamic Modules引入了一个新的bean范围 - bundle范围。当一个具有bundle范围的bean做为OSGi服务输出的时候，这个bean的一个实例对象将被生成，每一个不同的客户端bundle（引用这个服务的bundle）都通过OSGi service registry获取它。当其中一个引用这个服务的bundle停止时，它所获取的这个bean的实例对象将被除去。要声一个bundle范围的bean，只需要添加一个'scope'属性元素就可以了：

<osgi:service ref="beanToBeExported" interface="com.xyz.MessageService"/> <bean id="beanToBeExported" scope="bundle" class="com.xyz.MessageServiceImpl"/>

4.1.1 Controlling the set of advertised service interfaces for an exported service

The OSGi Service Platform Core Specification defines the term service interface to represent the specification of a service's public methods. Typically this will be a Java interface, but the specification also supports registering service objects under a class name, so the phrase service interface can be interpreted as referring to either an interface or a class.

OSGi服务平台核心规范定义了术语"service interface"用于描述一个服务的公共方法。具有代表性的就是Java interface，不过OSGi规范也支持通过类名来注册服务对象，所以短语"service interface"也能被理解成接口或类。

There are several options for specifying the service interface(s) under which the exported service is registered. The simplest mechanism, shown above, is to use the interface attribute to specify a fully-qualified interface name. To register a service under multiple interfaces the nested interfaces element can be used in place of the interface attribute.

这里也有一些选项用于注册指定这个被输出的服务实现了的接口。如下面所显示的，最简单的办法是使用interface属性指定一个全路径的接口名。如果要注册一个实现了多接口的服务，可以使用interfaces 节点代替interface属性。 <osgi:service ref="beanToBeExported"> <osgi:interfaces> <value>com.xyz.MessageService</value> <value>com.xyz.MarkerInterface</value> </osgi:interfaces> </osgi:service>

Using the auto-export attribute you can avoid the need to explicitly declare the service interfaces at all. The auto-export attribute can have one of four values:

使用'auto-export'属性，可以不用声明一个服务接口，'auto-export'属性具有如下4个值中的其中一个：

disabled : the default value; no auto-detected of service interfaces is undertaken and the interface attribute or interfaces element must be used instead.

disabled: 默认值，具有自动检测功能的服务接口将不被启动，必须使用interface属性或interfaces节点。
interfaces : the service will be registered using all of the Java interface types implemented by the bean to be exported

interfaces: 所有被输出的bean所实现的所有java接口将自动被注册。
class-hierarchy : the service will be registered using the exported bean's implementation type and super-types

class-hierarchy: 这个bean的类和它的父类将被自动注册。
all : the service will be registered using the exported bean's implementation type and super-types plus all interfaces implemented by the bean.

all: 包含 interfaces和class-hierarchy

For example, to automatically register a bean under all of the interfaces that it supports you would declare:

<service ref="beanToBeExported" auto-export="interfaces"/>

Given the interface hierarchy:

public interface SuperInterface {}

public interface SubInterface extends SuperInterface {}

then a service registered as supporting the SubInterface interface is not considered a match in OSGi when a lookup is done for services supporting the SuperInterface interface. For this reason it is a best practice to export all interfaces supported by the service being registered explicitly, using either the interfaces element or auto-export="interfaces".

在OSGi中，当一个SuperInterface的匹配查找结束时，一个支持SubInterface 的注册的服务是不匹配的。这对于使用使用interfaces 节点或auto-export="interfaces"输出被明确注册的服务所支持的接口是很好的实践。

Note that when using auto-export, only types visible to the bundle exporting the service are registered. For example, a super-interface SI would not be exported as a supported service interface even when using auto-export="interfaces" if SI was not on the exporting bundle's classpath.

注意，当使用auto-export时，仅仅只有对输出服务的bundle可见的types（接口或类）才会被注册。例如，一个super-interface SI，如果它不在输出bundle的classpath中，即使当使用auto-export="interfaces"，它也不会做为一个被服务支持的接口输出。

4.1.2 Controlling the set of advertised properties for an exported service

As previously described, an exported service is always registered with the service property org.springframework.osgi.beanname set to the name of the bean being exported. Additional service properties can be specified using the nested service-properties element. The service-properties element contains key-value pairs to be included in the advertised properties of the service. The key must be a string value, and the value must be a type recognized by OSGi Filters. See section 5.5 of the OSGi Service Platform Core Specification for details of how property values are matched against filter expressions.

前面已经描述过，一个输出的服务被注册后，会有一个服务属性org.springframework.osgi.beanname，值就是被输出的bean的名字。可以使用嵌套节点service-properties指定一些附加属性，service-properties节点有包含在服务的通知属性中的键－值对。key必须是一个string，value必须是一个经过OSGi Filters验证的type。对于匹配OSGi filters表达式的细节可以参照OSGi规范5.5节。

The service-properties element must contain at least one nested entry element from the Spring beans namespace.

service-properties节点必须包含至少一个Spring beans名字空间的entry 节点。

For example:

<service ref="beanToBeExported" interface="com.xyz.MyServiceInterface">
  <service-properties>
    <beans:entry key="myOtherKey" value="aStringValue"/>
    <beans:entry key="aThirdKey" value-ref="beanToExposeAsProperty"/>
  <service-properties>
</service>

The Spring Dynamic Modules roadmap includes support for exporting properties registered in the OSGi Configuration Administration service as properties of the registered service. See Appendix A for more details.

Spring Dynamic Modules roadmap 包含了支持将属性做为一个被注册了的服务的属性注册到OSGi Configuration Administration service 中。

4.1.3 The depends-on attribute

Spring will manage explicit dependencies of a service element, ensuring for example that the bean to be exported as a service is fully constructed and configured before exporting it. If a service has implicit dependencies on other components (including other service elements) that must be fully initialized before the service can be exported, then the optional depends-on attribute can be used to express these dependencies.

Spring会管理服务元素中明示性的依赖关系，例如确保哪些被做为服务输出的bean在输出之前被完全构造和配置。如果一个服务隐含依赖于其他组件（包括其他服务元素），这个组件在服务被输出之前要被完全初始化，那么可选的属性depends-on能用来表示这种依赖关系。

<service ref="beanToBeExported" interface="com.xyz.MyServiceInterface" depends-on="myOtherComponent"/>

4.1.4 The ranking attribute

When registering a service with the service registry, you may optionally specify a service ranking (see section 5.2.5 of the OSGi Service Platform Core Specification). When a bundle looks up a service in the service registry, given two or more matching services the one with the highest ranking will be returned. The default ranking value is zero. To explicitly specify a ranking value for the registered service, use the optional ranking attribute.

当注册一个服务时，你可能会随意指定一个ranking（关于ranking，参见OSGi规范5.2.5节）。当一个bundle查找一个服务时，ranking最高的与之匹配的服务将会被返回。默认的ranking值是0.使用可选的ranking属性可以为注册的服务指定一个ranking值。

<service ref="beanToBeExported" interface="com.xyz.MyServiceInterface" ranking="9"/>

4.1.5 The context-classloader attribute

The OSGi Service Platform Core Specification (most current version is 4.1 at time of writing) does not specify what types and resources are visible through the context class loader when an operation is invoked on a service obtained via the service registry. Since some services may use libraries that make certain assumptions about the context class loader, Spring Dynamic Modules enables you to explicitly control the context class loader during service execution. This is achieved using the option context-classloader attribute of the service element.

OSGi规范没有指定当通过service registry获取服务的方法被调用时，什么样的types和资源对context class loader可见。所以假设某个服务如果要用到context class loader相关的libraries时，Spring Dynamic Modules允许你在服务执行期明确的控制context class loader，通过service元素的可选属性'context-classloader'来完成。

The permissible values for the context-classloader attribute are unmanaged (the default) and service-provider. When the service-provider value is specified, Spring Dynamic Modules ensures that the context class loader can see all of the resources on the class path of the bundle defining the service.

'context-classloader'属性允许的值只有2个 'unmanaged'（默认）和 'service-provider'，当指定'service-provider'值时，Spring Dynamic Modules确保了context class loader 能看见定义这个服务的bundle的classpath中所有的资源。

4.1.6 Service registration and unregistration lifecycle

The service defined by a service element is registered with the OSGi service registry when the application context is first created. It will be unregistered automatically when the bundle is stopped and the application context is disposed.

当application context第一次被创建时，由<service>元素定义的服务通过OSGi service registry 注册。这个服务将会在bundle停止和application context被注销时自动注销。

An exported service may depend, either directly or indirectly, on other services in order to perform its function. If one of these services is considered a mandatory dependency (see section 4.2) and the dependency can no longer be satisfied (because the backing service has gone away and there is no suitable replacement available) then the exported service that depends on it will be automatically unregistered from the service registry - meaning that it is no longer available to clients. If the mandatory dependency becomes satisfied once more (by registration of a suitable service), then the exported service will be re-registered in the service registry.

一个输出的服务(ServiceA)可能会因为功能需要而直接或间接地依赖其他服务。如果这些服务中的其中一个服务(ServiceB)匹配ServiceA的强制依赖，并且这个强制依赖关系不再satisfied（因为ServiceB不再可用），那么这个输出的服务(ServiceA)将会自动从service registry中注销，也就是说不再对客户端有效。如果这个强制依赖关系再次变得satified（通过注册一个匹配这个强制依赖关系的服务，可能是ServiceB也可能是其他服务），那么这个输出的服务(ServiceA)将被重新注册到service registry。

This automatic unregistering and re-registering of exported services based on the availability of mandatory dependencies only takes into account declarative dependencies. If exported service S depends on bean A, which in turn depends on mandatory imported service M, and these dependencies are explicit in the Spring configuration file as per the example below, then when M becomes unsatisfied S will be unregistered. When M becomes satisfied again, S will be re-registered.

输出服务基于强制依赖的自动注销和重新注册仅仅用在声明性的依赖关系中。在下面给的例子中，输出的服务S依赖bean A，bean A引入了服务M，那么当M变得unsatisfied时，S将会被自动注销，当M重新变得satisfied是，S将重新注册。

<osgi:service id="S" ref="A" interface="SomeInterface"/> <bean id="A" class="SomeImplementation"> <property name="helperService" ref="M"/> </bean>  <osgi:reference id="M" interface="HelperService" cardinality="1..1"/>

If however the dependency from A on M is not established through configuration as shown above, but instead at runtime through for example passing a reference to M to A without any involvement from the Spring container, then Spring Dynamic Modules will not track this dependency.

If you need to take some action when a service is unregistered because its dependencies are not satisfied (or when it is registered), then you can define a listener bean using the nested registration-listener element.

如果你想在一个服务因为它的依赖关系不再satisfied（或注册）时做点什么，可以使用嵌套元素registration-listener定义个监听bean

The declaration of a registration listener must use either the ref attribute to refer to a top-level bean definition, or declare an anonymous listener bean inline. For example:

声明一个注册监听器必须在顶级bean定义中使用ref 属性或是在它里面声明一个匿名监听器bean。

 <service ref="beanToBeExported" interface="SomeInterface"> <registration-listener ref="myListener" registration-method="serviceRegistered" unregistration-method="serviceUnregistered"/> <registration-listener registration-method="register" unregistration-method="unregister"> <bean class="SomeListenerClass"/> </registration-listener> </service>

The optional registration-method and unregistration-method attributes specify the names of the methods defined on the listener bean that are to be invoked during registration and unregistration. A registration callback method must have a signature matching the following format

可选的registration-method和unregistration-method属性指定了定义在监听bean中的方法的名字，它们会在服务被注册或注销的时候调用。一个注册回调方法必须匹配下面的格式：

public void anyMethodName(ServiceType serviceInstance);
where ServiceType can be any type compatible with the exported service interface of the service.

这里的ServiceType 可以是任何type，当然它必须要兼容你要监听的服务的类型

An unregistration callback method must have a signature of the form

public void anyMethodName(ServiceType serviceInstance);

where ServiceType can be any type compatible with the exported service interface of the service.

The register callback is invoked when the service is initially registered at startup, and whenever it is subsequently re-registered. The unregister callback is invoked immediately after the service is unregistered, including when the service is unregistered because the bundle is stopping.

注册时回调方法会在系统启动时初次注册服务时调用，也会在服务被重新注册时调用。注销回调方法会在服务被注销后立即调用，包括bundle停止时引起的服务注销。

4.2 Defining references to OSGi services

Spring Dynamic Modules supports the declaration of beans that represent services accessed via the OSGi Service Registry. In this manner references to OSGi services can be injected into application components. The service lookup is made using the service interface type that the service is required to support, plus an optional filter expression that matches against the service properties published in the registry.

Spring Dynamic Modules支持将bean声明为可通过OSGi Service Registry访问的服务，这可以将OSGi services的引用注入到应用组件中。服务的查找是通过使用服务支持的接口类型，再加上可选的匹配发布在registry中的服务属性的过滤器表达式。

For some scenarios, a single matching service that meets the application requirements is all that is needed. The reference element defines a reference to a single service that meets the required specification. In other scenarios, especially when using the OSGi whiteboard pattern, references to all available matching services are required. Spring Dynamic Modules supports the management of this set of references as a List, Set.

在某些情况下，一个与应用需求相应的单一匹配是必须的，<reference>元素定义了一个相应的单一服务的引用。在其他情况下，尤其是当使用OSGi whiteboard pattern时，需要所有可用的匹配服务的应用。Spring Dynamic Modules支持将这些应用做为List或Set去管理。

4.2.1 Referencing an individual service

The reference element is used to define a reference to a service in the service registry. The interface attribute identifies the service interface that a matching service must implement. For example, the following declaration creates a bean messageService, which is backed by the service returned from the service registry when querying it for a service offering the MessageService interface.

<reference>元素用来定一个被注册到service registry中的服务的引用。interface 属性用来识别服务接口。例如，下面的声明创建了一个bean - messageService，它实际上是通过查找名字为messageService，接口为MessageService 得到的服务。

<reference id="messageService" interface="com.xyz.MessageService"/>

If there are several services in the service registry then the service returned is the service that would be returned by a call to BundleContext.getServiceReference. This means that the service with the highest ranking will be returned, or if there is a tie in ranking, the service with the lowest service id (the service registered first with the framework) is returned.

如果service registry中有多个服务，那么将通过BundleContext.getServiceReference来返回服务。也就是说返回的这个服务具有最高队列等级，或是如果有一个tie在队列等级中，则返回id最小的那个服务(第一个被注册的服务)。

The bean defined by the reference element implements all of the registered interfaces of the service that are visible to the bundle. If the registered service interfaces include Java class types (as opposed to interface types) then support for these types is subject to the restrictions of Spring's AOP implementation (see the Spring Reference Guide). In short, cglib must be available, and final methods are not supported.

使用<reference>定义的bean要实现所有注册了的服务接口，这些接口需要对bundle可见。如果注册的服务接口包含了java类（非java接口），那么将会影响到Spring的AOP功能。简单的说，会影响到cglib，并且final方法不被支持。

If the property into which a reference bean is to be injected has type ServiceReference (instead of the service interface supported by the reference), then the OSGi ServiceReference for the service will be injected in place of the service itself.

如果一个服务的某个属性，被注入的bean的的引用的类型是ServiceReference(它不是被引用所支持的服务接口)，那么这个服务的服务引用将被注入，而不是这个服务本身。

4.2.1.1 The filter attribute

The optional filter attribute can be used to specify an OSGi filter expression and constrains the service registry lookup to only those services that match the given filter.

可选属性filter 用来指定一个OSGi过滤器表达式，用于service registry查找那些仅仅匹配过滤器条件的服务。

For example:

<reference id="asyncMessageService" interface="com.xyz.MessageService"
  filter="(asynchronous-delivery=true)"/>

4.2.1.2 The bean-name attribute

The bean-name attribute is a convenient short-cut for specifying a filter expression that matches on the bean-name property automatically set when exporting a bean using the service element (see section 4.1).

属性bean-name是一个方便的short-cut，当使用<service >输出一个bean时，用于指定一个匹配自动设置的bean-name属性的过滤表达式。

For example:

<reference id="messageService" interface="com.xyz.MessageService"
   bean-name="defaultMessageService"/>

4.2.1.3 The cardinality attribute

The cardinality attribute is used to specify whether or not a matching service is required at all times. A cardinality value of 1..1 (the default) indicates that a matching service must always be available. A cardinality value of 0..1 indicates that a matching service is not required at all times (see section 4.2.1.6 for more details). A reference with cardinality 1..1 is also known as a mandatory service reference and by default application context creation is deferred until the reference is satisfied.

属性cardinality 用于指定一个匹配的服务是否在任何时候都需要它可用。值'1..1'（默认值）表示一个匹配的服务必须总是可用。值'0..1'表示一个匹配服务不一定在任何时候都需要它可用（细节参见4.2.1.6）。一个cardinality值为'1..1'的服务就已经构成了一个强制依赖服务，而且默认情况下会延迟创建它的application context，直到这个依赖关系变得satisfied。

Note: it is an error to declare a mandatory reference to a service that is also exported by the same bundle, this behavior can cause application context creation to fail through either deadlock or timeout.

注意：声明一个强制依赖引用到一个服务，而这个服务和这个引用被同一个bundle所输出，这是错误的，会导致创建application context是发生死锁或超时。

4.2.1.4 The depends-on attribute

The depends-on attribute is used to specify that the service reference should not be looked up in the service registry until the named dependent bean has been instantiated.

属性depends-on用于指定一个服务不应该在service registry中查找和使用直到与这个属性值相同的bean被初始化。

4.2.1.5 The context-classloader attribute

4.2.1.6 Dealing with Service dynamics

The bean defined by the reference element is unchanging throughout the lifetime of the application context (the object reference remains constant). However, the OSGi service that backs the reference may come and go at any time. For a mandatory service reference (cardinality 1..1), creation of the application context will block until a matching service is available. For an optional service reference, the reference bean will be created immediately, regardless of whether or not there is currently a matching service.

在application context 的生命周期中，使用<reference >定义的bean不会发生改变，尽管如此，引用的这个服务可能随时不可用。对于一个强制依赖的服务引用（包括使用cardinality 1..1），将延迟创建application context 知道匹配服务都可用。对于一个可选的服务引用，这个引用的bean会立即生成application context，与是否是当前匹配服务无关。

When the service backing a reference bean goes away, Spring Dynamic Modules tries to replace the backing service with another service matching the reference criteria. An application may be notified of a change in backing service by registering a listener. If no matching service is available, then the reference is said to be unsatisfied. An unsatisfied mandatory service causes any exported service (service bean) that depends on it to be unregistered from the service registry until such time as the reference is satisfied again.

当一个被bean引用的服务不可用时，Spring Dynamic Modules会尝试使用另一个匹配引用标准的服务替换掉这个服务。一个application context 可能会被一个注册的监听器通知这个服务的变化。如果没有任何服务匹配这个引用标准，则意味着这个引用变得unsatisfied。一个 unsatisfied的强制依赖服务会使依赖它的其他服务也变得 unsatisfied直到这个引用重新变得satisfied。

When an operation is invoked on an unsatisfied reference bean (either optional or mandatory), the invocation blocks until the reference becomes satisfied. The optional timeout attribute of the reference element enables a timeout value (in milliseconds) to be specified. If a timeout value is specified and no matching service becomes available within the timeout period, an unchecked ServiceUnavailableException is thrown.

当调用一个 unsatisfied的bean引用（可选依赖或强制依赖）时，这个调用将会被阻塞直到这个引用变得satisfied。<reference >的可选属性timeout 可以指定一个阻塞的超时时间，如果在指定的超时时间内没有一个匹配的服务可用，将抛出一个ServiceUnavailableException 异常。

When using the osgi element to enclose service and reference elements, the default-timeout attribute may be used to specify a default timeout for all reference elements that do not explicitly specify one. For example:可以用下面的方式为所有的引用指定共同的超时时间，同时也可以单独指定超时时间： <osgi default-timeout="5000">  <reference id="someService" interface="com.xyz.AService"/>  <reference id="someOtherService" interface="com.xyz.BService" timeout="1000"/> </osgi>

For applications that need to be aware of when the service backing a reference bean is bound and unbound, it is possible to register one or more listeners using the nested listener element. The listener element refers to a bean (either by name, or by defining one inline) that will receive bind and unbind notifications. If this bean implements Spring's org.springframework.osgi.service.TargetSourceLifecycleListener interface, then the bind and unbind operations in this interface will be invoked. Instead of implementing this interface (or in addition), custom bind and unbind callback methods may be named.

对于一个应用，当一个引用bean服务 ( the service backing a reference bean - 使用<reference>引用一个被Spring用<service>输出的bean形成的服务 ) 被绑定或解除绑定时，可以使用<listener>设置一个或多个监听器。<listener >引入的bean会收到bind和unbind的通知。如果这个bean实现了Spring的org.springframework.osgi.service.TargetSourceLifecycleListener接口，那么与这个接口响应的方法将被调用，也可以自己定义bind和unbind方法。

An example of declaring a listener that implements TargetSourceLifecycleListener:

<reference id="someService" interface="com.xyz.MessageService">
  <listener ref="aListenerBean"/>
</reference>

An example of declaring an inline listener bean with custom bind and unbind methods:

<reference id="someService" interface="com.xyz.MessageService">
  <listener bind-method="onBind" unbind-method="onUnbind">
     <beans:bean class="MyCustomListener"/>
  </listener>
</reference>

If the listener bean implements the TargetSourceLifecyleListener interface and the listener definition specifies custom bind and unbind operations then both the TargetSourceLifecycleListener operation and the custom operation will be invoked, in that order.

如果一个监听bean实现了TargetSourceLifecyleListener 接口并且自定义了bind和unbind方法，那么先是TargetSourceLifecycleListener 接口的相应方法被调用，然后自定义的方法接着被调用。

The signature of a custom bind or unbind method must be one of:

public void anyMethodName(ServiceType service, Dictionary properties);

public void anyMethodName(ServiceType service, Map properties);

public void anyMethodName(ServiceReference ref);

If the method signature has a single argument of type ServiceReference then the ServiceReference of the service will be passed to the callback in place of the service object itself.

如果这个回调方法只有一个类型为ServiceReference 的参数，那么这个服务的服务引用将被传入这个回调方法，而不是这个服务本身。

where ServiceType can be any type that is assignable from the reference interface type. The properties parameter contains the set of properties that the service was registered with.

ServiceType 是interface指定的类型。属性properties 包含了这个服务注册时的所有属性。

A bind callback is invoked when the reference is initially bound to a backing service, and whenever the backing service is replaced by a new backing service.

当一个引用被绑定到一个服务或这个服务被一个新的服务替换时，将调用绑定回调方法。

An unbind callback is only invoked when the current backing service is unregistered, and no replacement service is immediately available (i.e., the reference becomes unsatisfied).

当一个服务被注销并且没有可用的服务替换它时，将调用解除绑定的回调方法。

Bind and unbind callbacks are made synchronously as part of processing an OSGi serviceChanged event for the backing OSGi service, and are invoked on the OSGi thread that delivers the corresponding OSGi ServiceEvent.

bind和unbind回调方法同步做为为OSGi后台服务处理serviceChanged事件过程的一部分，并且在发生相应ServiceEvent事件的线程中执行调用。

4.2.2 Referencing collections of services

Sometimes an application needs access not simply to any service meeting some criteria, but to all services meeting some criteria. The matching services may be held in a List or Set (optionally sorted).

有时一个应用不仅仅只是简单的使用某个符合匹配标准的服务，而是要使用所有符合匹配标准的服务。这个匹配的服务可能被保存在一个任意类型的List或Set中。

The difference between using a List and a Set to manage the collection is one of equality. Two or more services published in the registry (and with distinct service ids) may be "equal" to each other, depending on the implementation of equals used by the service implementations. Only one such service will be present in a set, whereas all services returned from the registry will be present in a list.

是否相等是使用List和Set管理服务集合的区别。2个或多个发布在registry 中的服务（它们有自己的服务ID）可能是一个等同关系（对象是一样的），这依赖于这个服务是否实现了'equal'方法。只有实现了'equal'方法的服务才会被保存在Set中，否则都会被保存在List中。

The set and list elements are used to define collections of services with set or list semantics respectively.

<set>和<list>分别用于定义具有set或list功能的服务集合。

These elements support the attributes interface, filter, bean-name, cardinality, and context-classloader, with the same semantics as for the reference element. The allowable values for the cardinality attribute are 0..n and 1..n. A cardinality value of 0..n indicates that it is permissible for their to be no matching services. A cardinality value of 1..n indicates that at least one matching service is required at all times. Such a reference is considered a mandatory reference and any exported services from the same bundle (service defined beans) that depend on a mandatory reference will automatically be unregistered when the reference becomes unsatisfied, and reregistered when the reference becomes satisfied again.

这2个节点支持这些属性： interface, filter, bean-name, cardinality 和 context-classloader，这些属性的功能与在<reference>中是一样的。属性cardinality 允许的值是 '0..n' 和'1..n'，值'0..n' 表示集合中可以没有匹配的服务。值 '1..n' 表示集合中至少有一个匹配的服务。

The bean defined by a list element is of type java.util.List. The bean defined by a set element is of type java.util.Set.

The following example defines a bean of type List that will contain all registered services supporting the EventListener interface:

下面这个例子定义了一个类型为List的bean，它将会保存所有接口为com.xyz.EventListener的注册服务。

<list id="myEventListeners" interface="com.xyz.EventListener"/>

The members of the collection defined by the bean are managed dynamically by Spring. As matching services are registered and unregistered in the service registry, the collection membership will be kept up to date. Each member of the collection supports the service interfaces that the corresponding service was registered with and that are visible to the bundle.

Spring会自动管理这个bean定义的集合的成员，这个集合的成员会被更新，就像在service registry中注册和注销一个匹配服务一样。支持定义的服务接口的集合中所有对象都有一个相应的注册服务，它们对bundle是可见的。

It is possible to specify a sorting order using either the comparator-ref attribute, or the nested comparator element. The comparator-ref attribute is used to refer to a named bean implementing java.util.Comparator. The comparator element can be used to define an inline bean. For example:

可以使用属性comparator-ref或内嵌一个<comparator >来指定一个排序方式。comparator-ref属性用来关联一个实现了java.util.Comparator接口的bean。<comparator> 用于指定一个内部bean。例如：

<set id="myServices" interface="com.xyz.MyService" comparator-ref="someComparator"/> <list id="myOtherServices" interface="com.xyz.OtherService"> <comparator> <beans:bean class="MyOtherServiceComparator"/> </comparator> </list>

To sort using a natural ordering instead of an explicit comparator, you can use the natural-ordering element inside of comparator. You need to specify the basis for the natural ordering: based on the service references, following the ServiceReference natural ordering defined in the OSGi Core Specification section 6.1.2.3; or based on the services themselves (in which case the services must be Comparable).

你可以通过在<comparator>中内嵌一个<natural-ordering>来让这个集合自己排序，但是你需要指定它基于什么方式排序，OSGi规范中定义的ServiceReference的自然排序方式是基于服务的引用来排序，可以仿照这个排序方式，也可以基于服务本身来排序（这个服务需要实现Comparable接口）。
<list id="myServices" interface"com.xyz.MyService"> <comparator><natural-ordering basis="services"/></comparator> </list> <set id="myOtherServices"interface="com.xyz.OtherService"> <comparator><natural-ordering basis="service-references"/></comparator> </set>

When iterating over the collection, the semantics of Iterator are guaranteed to be observed (if hasNext() returns true, then next() will return a service, if hasNext() returns false then next() will throw an exception.). In addition any elements added to the collection during iteration over a sorted collection will only be visible if the iterator has not already passed their sort point.

当使用Iterator遍历一个集合时（匹配服务的集合），如果hasNext()返回true，next()将返回一个服务，如果hasNext()返回false，next()将抛出一个exception。另外，在遍历一个集合的过程中，任何新加入的元素仅仅只是在iterator没有遍历到这个新加入元素的排序点时才会被遍历出来。

4.2.2.1 Dealing with Service dynamics

Collection membership is automatically managed as matching services are registered or unregistered. The nested listener element is supported with all of the reference collection beans. The bind callback is invoked whenever a service is added to the collection, and the unbind callback is invoked whenever a service is removed from the collection.

集合的成员自动做为匹配服务进行注册和注销管理。嵌套的<listener>支持所有的引用集合bean。bind回调方法将在一个服务被添加到集合中时调用，unbind方法将在一个服务从集合中除去的时候被调用。

When iterating over the members of a collection, it is always possible that the service backing a collection member is unregistered after it has been returned from an invocation of Iterator.next(). If an operation is invoked on such a service, a ServiceUnavailableException will be thrown.

当遍历一个集合的所有元素时，某个集合成员的服务可能会在通过next()方法返回后被注销，如果这个服务中的方法被调用，那么将抛出一个ServiceUnavailableException 。

5.0 Working with Bundles

The bundle element defines a bean of type org.osgi.framework.Bundle. It provides a simple way to work directly with bundles, including driving their lifecycle. In the simplest case all you need to do is specify the symbolic-name of the bundle you are interested in:

<bundle>用来定义一个类型为org.osgi.framework.Bundle的bean。它提供了一个简单的方式直接操作bundle，包括操纵它们的生命周期。在下面的例子中你只需要简单的为这个bundle指定一个symbolic-name：

<bundle id="aBundle" symbolic-name="org.xyz.abundle"/>

The bean aBundle can now be dependency injected into any property of type Bundle.

现在这个bean可以被注入到任何类型为Bundle的属性中了。

The optional location and action attributes provide declarative control over the bundle's lifecycle. The location attribute is used to specify a URL where the bundle jar file artifact can be found. The action attribute specifies the lifecycle operation to be invoked on the bundle object. The supported action values are install, start, update, stop, and uninstall. These actions have the same semantics as the operations of the corresponding names defined on the Bundle interface (see the OSGi Service Platform Core Specification), with the exception that pre-conditions are weakened to allow for example a 'start' action to be specified against a bundle that is not currently installed (it will be installed first).

可选属性 location 和 action对这个bundle的声明周期提供了声明性的控制。属性location指定一个可以找到bundle jar包的URL，属性action指定了在bundle对象中被调用的生命周期操作。

The following table shows how actions are interpreted for the given Bundle states:

action	UNINSTALLED	INSTALLED/RESOLVED	ACTIVE
install	installs the bundle	no action taken, bundle already installed	no action taken, bundle already installed
start	installs and starts the bundle	starts the bundle	no action taken, bundle already started
update	installs the bundle and then updates it (`Bundle.update()`)	updates the bundle	updates the bundle
stop	no action taken	no action taken	bundle is stopped
uninstall	no action taken	bundle is uninstalled	bundle is stopped and then uninstalled

For example:

<!-- ensure this bundle is installed and started -->
<bundle id="aBundle" symbolic-name="org.xyz.abundle"
   location="http://www.xyz.com/bundles/org.xyz.abundle.jar"
   action="start"/>

The 'start-level' attribute can be used to set the start level of the bundle.

Finally, the bundle element also supports a depends-on attribute which can be used to ensure that the bundle bean is not created before a named bean on which it depends is fully instantiated.

The samples that ship with the Spring Dynamic Modules project further include support for a virtual-bundle element that can be used to create and install OSGi bundles on the fly from existing artifacts.

6.0 Compendium Services

The OSGi Service Platform Service Compendium specification defines a number of additional services that may be supported by OSGi implementations. Spring Dynamic Modules supports an additional "compendium" namespace that provides support for some of these services. By convention, the prefix osgix is used for this namespace.

<?xml version="1.0" encoding="UTF-8"?>
<osgi xmlns="http://www.springframework.org/schema/osgi"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:osgix="http://www.springframework.org/schema/osgi-compendium"
   xsi:schemaLocation="http://www.springframework.org/schema/osgi  
        http://www.springframework.org/schema/osgi/spring-osgi.xsd
        http://www.springframework.org/schema/osgi-compendium"
        http://www.springframework.org/schema/osgi/spring-osgi-compendium.xsd"">

   <!-- use the OSGi namespace elements directly -->
   <service id="simpleServiceOsgi" ref="simpleService"
       interface="org.xyz.MyService" />

   <!-- qualify compendium namespace elements -->
   <osgix:property-placeholder persistent-id="com.xyz.myapp"/>

</osgi>

At present this namespace provides support for the Configuration Admin service. Support for other compendium services may be added in future releases.

6.1 Configuration Admin

6.1.1 Property placeholder support

Spring Dynamic Modules provides support for sourcing bean property values from the OSGi Configuration Administration service. This support is enabled via the property-placeholder element. The property placeholder element provides for replacement of delimited string values (placeholders) in bean property expressions with values sourced from the configuration administration service. The required persistent-id attribute specifies the persistent identifier to be used as the key for the configuration dictionary. The default delimiter for placeholder strings is "${...}".

Given the declarations:

<osgix:property-placeholder persistent-id="com.xyz.myapp"/>

<bean id="someBean" class="AClass">
  <property name="timeout" value="${timeout}"/>
</bean>

Then the timeout property of someBean will be set using the value of the timeout entry in the configuration dictionary registered under the com.xyz.myapp persistent id.

The placeholder strings are evaluated at the time that the bean is instantiated. Changes to the properties made via Configuration Admin subsequent to the creation of the bean do not result in re-injection of property values. See the managed-service and managed-service-reference elements documented in appendix B if you require this level of integration. The placeholder-prefix and placeholder-suffix attributes can be used to change the delimiter strings used for placeholder values.

It is possible to specify a default set of property values to be used in the event that the configuration dictionary does not contain an entry for a given key. The defaults-ref attribute can be used to refer to a named bean of Properties or Map type. Instead of referring to an external bean, the default-properties nested element may be used to define an inline set of properties.

<osgix:property-placeholder persistent-id="com.xyz.myapp">
  <default-properties> 
     <property name="productCategory" value="E792"/>
     <property name="businessUnit" value="811"/> 
  </default-properties>
</osgix:property-placeholder>

The persistent-id attribute must refer to the persistent-id of an OSGi ManagedService, it is a configuration error to specify a factory persistent id referring to a ManagedServiceFactory.

6.1.2 Configuration Dictionaries

Support for directly accessing configuration objects and their associated dictionaries, and for instantiating beans directly from configuration objects is on the Spring Dynamic Modules roadmap. See Appendix A for more information.

7.0 Testing OSGi based Applications

By following best practices and using the Spring Dynamic Modules support, your bean classes should be easy to unit test as they will have no hard dependencies on OSGi, and the few OSGi APIs that you may interact with (such as BundleContext) are interface-based and easy to mock. For integration testing (making sure that your application behaves as expected when running under OSGi) some support is needed.

The Spring Dynamic Modules project provides a test class hierarchy (based on org.springframework.osgi.test.AbstractOsgiTests) that provides support for writing regular JUnit test cases that are then automatically executed in an OSGi environment. The test support:

starts the OSGi framework
installs and starts any specified bundles required for the test
packages the test case itself into a 'virtual bundle' and installs it in the OSGi framework
executes the test case inside the OSGi framework
shuts down the framework
passes the test results back to the originating test case instance that is running outside of OSGi

By following this sequence it is trivial to write JUnit-based integration tests for OSGi and have them integration into any environment (IDE, build, etc.) that can work with JUnit.

It is most likely that your test cases will extend AbstractConfigurableBundleCreatorTests. Within your test case, access to the BundleContext is readily available through the inherited getBundleContext() method. From here it is easy to verify service publication, drive bundles through the lifecycle and verify that components react as expected, and so on.

Here's a simple test that verifies a service has been published as expected:

public class ServicePublicationTest extends AbstractConfigurableBundleCreatorTests {

  protected String[] getBundles() {
    return new String[] {
     "org.xyz.someapp, application-layer, 1.0-SNAPSHOT"
     }
  }

  public void testServicePublication() {
     assertNotNull("MyService should be published in tthe registry", 
                   getBundleContext().getServiceReference("org.xyz.MyService"));        
  }

}

All of the bundles required by Spring Dynamic Modules will be installed by default. By overriding the getBundles method you can specify additional application bundles to be installed for the test. In this example we install one bundle, with group id org.xyz.someapp, module id application-layer, and version 1.0-SNAPSHOT. The default behavior of the test support is to look up this dependency in your local maven repository. It is possible to change the lookup strategy using a pluggable ArtifactLocator (see the javadocs for more information). Support for Ivy-based repositories is planned for a future release.

The test support has been integrated with Equinox, Knopflerfish, and Felix. You can configure the platform used to run the tests in one of two ways:

Set the org.springframework.osgi.test.framework system property to one of equinox, knopflerfish, or felix.
Override the AbstractConfigurableOsgiTests#getPlatformName() operation to return one of the constants: EQUINOX_PLATFORM, KNOPFLERFISH_PLATFORM, or FELIX_PLATFORM.

By default the test harness will attempt to use Equinox.

Appendix A: Extensions

This appendix describes extensions to the core functionality that are shipped with the 1.0 distribution, but are not guaranteed to have backwards compatibility across point releases. We anticipate these features migrating into the core specification in future releases.

A.1 Annotation-based injection

The org.springframework.osgi.extensions.annotation bundle that ships with Spring Dynamic Modules provides early access to annotation-based support for injecting references to OSGi services. JDK 1.5 or above is required to use this feature.

Bean class (setter) methods may be annotated with org.springframework.osgi.annotation.ServiceReference. By default the property type of the annotated property is used to look up a service with a matching service interface in the OSGi service registry and inject the result. For example, given the configuration:

<bean id="annotationDriven" class="MyAnnotationDrivenBeanClass"/>

and the class declaration:

public class MyAnnotationDrivenBeanClass {

  @ServiceReference
  public void setMessageService(MessageService aService) { ... }

}

then a service lookup for services implementing the MessageService interface will be performed, and the best match (using the same algorithm as documented for the reference element) will be injected.

The ServiceReference annotation class has a number of attributes that can be used to control the service lookup (for example, to specify a filter string) that mirror the options provided by the reference element. See the javadoc for more information.

Appendix B: Roadmap

This appendix documents features on the Spring Dynamic Modules roadmap. The design of these features specified here is subject to change.

B.1 Enhanced Configuration Admin Support

B.1.1 Managed Services

It should be possible to easily instantiate a bean from the configuration information stored for a ManagedService, and a set of beans from the configuration information stored for a ManagedServiceFactory. In addition, updates to the configuration information should be propagated to beans created in this way.

The managed-service element is used to define a bean based on the configuration information stored under a given persistent id. It has two mandatory attributes, class and persistent-id. The persistent-id attribute is used to specify the persistent id to be looked up in the configuration administration service, class indicates the Java class of the bean that will be instantiated.

A simple declaration of a managed service bean would look as follows:

 <osgix:managed-service id="myService" class="com.xyz.MessageService" 
   persistent-id="com.xyz.messageservice"/>

The properties of the managed-service bean are autowired by name based on the configuration found under the given persistent id. It is possible to declare regular Spring bean property elements within the managed-service declaration. If a property value is defined both in the configuration object stored in the Configuration Admin service, and in a nested property element, then the value from Configuration Admin takes precedence. Property values specified via property elements can therefore be treated as default values to be used if none is available through Configuration Admin.

It is possible for the configuration data stored in Configuration Admin to be updated once the bean has been created. By default, any updates post-creation will be ignored. To receive configuration updates, the update-strategy attribute can be used with a value of either bean-managed or container-managed.

The default value of the optional update-strategy attribute is none. If an update strategy of bean-managed is specified then the update-method attribute must also be used to specify the name of a method defined on the bean class that will be invoked if the configuration for the bean is updated. The update method must have one of the following signatures:

public void anyMethodName(Map properties)
public void anyMethodName(Map<String,?> properties); // for Java 5
public void anyMethodName(Dictionary properties);

When an update strategy of container-managed is specified then the container will autowire the bean instance by name based on the new properties received in the update. For container-managed updates, the bean class must provide setter methods for the bean properties that it wishes to have updated. Container-managed updates cannot be used in conjunction with constructor injection. Before proceeding to autowire based on the new property values, a lock is taken on the bean instance. This lock is released once autowiring has completed. A class may therefore synchronize its service methods or otherwise lock on the bean instance in order to have atomic update semantics.

B.1.2 Managed Service Factories

The managed-service-factory element is similar to the managed-service element, but instead defines a set of beans, one instance for each configuration stored under the given factory pid. It has two mandatory attributes, factory-pid and class.

A simple managed-service-factory declaration would look as follows:

<osgix:managed-service-factory id="someId" factory-pid="org.xzy.services" 
           class="MyServiceClass"/>

This declaration results in the creation of zero or more beans, one bean for each configuration registered under the given factory pid. The beans will have synthetic names generated by appending "-" followed by the persistent id of the configuration object as returned by Configuration Admin, to the value of the id attribute used in the declaration of the managed-service-factory. For example, someId-config.admin.generated.pid.

Over time new configuration objects may be added under the factory pid. A new bean instance is automatically instantiated whenever a new configuration object is created. If a configuration object stored under the factory pid is deleted, then the corresponding bean instance will be disposed (this includes driving the DisposableBean callback if the bean implements DisposableBean). The option destroy-method attribute of the managed-service-factory element may be used to specify a destroy callback to be invoked on the bean instance. Such a method must have a signature:

public void anyMethodName();

It is also possible for the configuration of an existing bean to be updated. The same update-strategy and update-method attributes are available as for the managed-service element and with the same semantics (though obviously only the bean instance whose configuration has been updated in Configuration Admin will actually be updated). The same client-locking semantics also apply when using the container-managed update strategy

B.1.3 Direct access to configuration data

If you need to work directly with the configuration data stored under a given persistent id or factory persistent id, the easiest way to do this is to register a service that implements either the ManagedService or ManagedServiceFactory interface and specify the pid that you are interested in as a service property. For example:

<service interface="org.osgi.service.cm.ManagedService" ref="MyManagedService">
  <service-properties>
    <entry key="service.pid" value="my.managed.service.pid"/>
  </service-properties>
</service>

<bean id="myManagedService" class="com.xyz.MyManagedService"/>

and where the class MyManagedService implements org.osgi.service.cm.ManagedService.

B.1.4 Publishing configuration administration properties with exported services

We intend to provide support for automatic publication of service properties sourced from the Configuration Admin service under a given persistent id. This support has yet to be designed but may look as follows:

<service ref="toBeExported" interface="SomeInterface">
   <osgix:config-properties persistent-id="pid"/>
</service>

Issues to be considered are scoping of a subset of properties to be published (public/private), and automatic updates to published service properties if the value is updated via config admin.

Note that named properties can easily be published as service properties already without this support, simply by using the property-placeholder support.

B.2 Access to Service References for Collections

The current specification does not provide for access to the ServiceReference objects for services in a managed collection (i.e. obtained via a set or list declaration). A future release of Spring Dynamic Modules will provide an easy means of gaining access to these references.

B.3 Start level integration

A future release of Spring Dynamic Modules may offer the following additional guarantee with respect to application context creation and start levels:

Application context creation happens asynchronously. However, the extender bundle does guarantee that the creation of all application contexts for bundles at start level n will be complete before the creation of any application context at start level m, where m > n. Care must therefore be taken not to introduce any mandatory dependencies on services exported by bundles with higher start levels or a deadlock will be introduced.

In a similar vein, when shutting down the extender bundle, application contexts at start level m will be shut down before application contexts at start level n, where m > n.

B.4 Web application support

A key part of the roadmap for the next release of Spring Dynamic Modules is built-in support for building web applications out of OSGi bundles. This will be supported using both an HttpService provided by a bundle installed into the running OSGi framework, and also by embedding an OSGi container inside an existing servlet container. Pioneering work has been done by Martin Lippert, Bernd Kolb, and Gerd Wutherich amongst others

B.5 ORM support

Care needs to be taken when using JPA or Hibernate under OSGi as the persistence engines must have visibility of the persistent types and mapping files. The Spring Dynamic Modules project will be investigating an extension model to make managing this easier when persistent configuration is split across several bundles. See Peter Krien's blog entry on the topic for an insight into the issues.

Appendix C: Spring Dynamic Modules Schema

To be completed - will import schema once we have finalised and updated it following review. Existing .xsd file needs to be tidied up and have improved documentation.

Appendix D: Acknowledgments

Thanks to Peter Kriens, Jeff McAffer, Richard S. Hall, Andy Piper, Hal Hildebrand, Glyn Normington, Martin Lippert, Gerd Wuetherich, Bill Gallagher, BJ Hargrave, and Olivier Gruber for their contributions in the development of this specification.=

posted on 2007-10-10 16:42 Phrancol Yang 阅读(6946) 评论(1) 编辑收藏所属分类: OSGI


只有注册用户登录后才能发表评论。




网站导航: 博客园 IT新闻知识库 C++博客博问管理
相关文章: Tomcat-OSGi Demo: JPetStoreOSGi(Spring-osgi 1.2.0) Extwind——支持OSGi应用的Tomcat [译]OSGi Service Platform Core Specification Release 4 - Package Admin Service Specification [译]OSGi Service Platform Core Specification Release 4 - Service Layer [译]OSGi Service Platform Core Specification Release 4 - Life Cycle Layer [译]OSGi Service Platform Core Specification Release 4 - Module Layer ( Part I 3.7-) [译]OSGi Service Platform Core Specification Release 4 - Module Layer ( Part I 3.1-3.6) 构建模块化的动态Web应用（演示版） Spring-OSGI 1.0 M3 中文手册(Spring Dynamic Modules Reference Guide for OSGi(tm) Service Platforms) Eric Newcomer on the future of OSGi

留言簿(16)

随笔分类

随笔档案

文章分类

文章档案

test

搜索

最新评论

Spring Dynamic Modules Reference Guide

1.0 Introduction

Why Spring Dynamic Modules?

Supported OSGi and JDK versions

Structure of this document

2.0 Bundles and Application Contexts

2.1 The Spring Dynamic Modules Extender bundle

2.2 Application Context Creation

2.2.1 Mandatory Service Dependencies

2.2.2 Application Context Service Publication

2.3 Bundle Lifecycle

2.4 The Resource abstraction

2.5 Accessing the BundleContext

2.5.1 ThreadLocal access to BundleContext

2.6 Stopping the extender bundle

3.0 Packaging and Deploying Spring-based OSGi applications

3.1 Bundle format and Manifest headers

3.2 Required Spring Framework and Spring Dynamic Modules Bundles

3.3 Importing and Exporting packages

3.4 Considerations when using external libraries

3.5 Diagnosing problems

4.0 The Service Registry

4.1 Exporting a Spring bean as an OSGi service

4.1.1 Controlling the set of advertised service interfaces for an exported service

4.1.2 Controlling the set of advertised properties for an exported service

4.1.3 The depends-on attribute

4.1.4 The ranking attribute

4.1.5 The context-classloader attribute

4.1.6 Service registration and unregistration lifecycle

4.2 Defining references to OSGi services

4.2.1 Referencing an individual service

4.2.1.1 The filter attribute

4.2.1.2 The bean-name attribute

4.2.1.3 The cardinality attribute

4.2.1.4 The depends-on attribute

4.2.1.5 The context-classloader attribute

4.2.1.6 Dealing with Service dynamics

4.2.2 Referencing collections of services

4.2.2.1 Dealing with Service dynamics

5.0 Working with Bundles

6.0 Compendium Services

6.1 Configuration Admin

6.1.1 Property placeholder support

6.1.2 Configuration Dictionaries

7.0 Testing OSGi based Applications

Appendix A: Extensions

A.1 Annotation-based injection

Appendix B: Roadmap

B.1 Enhanced Configuration Admin Support

B.1.1 Managed Services

B.1.2 Managed Service Factories

B.1.3 Direct access to configuration data

B.1.4 Publishing configuration administration properties with exported services

B.2 Access to Service References for Collections

B.3 Start level integration

B.4 Web application support

B.5 ORM support

Appendix C: Spring Dynamic Modules Schema

Appendix D: Acknowledgments