Equinox OSGi系列之三 Equinox配置参数详解
1、概述
上文我们对Equinox OSGi运行环境的组成及搭建过程做了详细讲述。本文主要对Equinox OSGi运行环境的可配置参数及其作用加以介绍，从而使用户在实际使用过程中可以对Equinox运行环境更好地进行控制。
Equinox项目沿袭Eclipse的特点，具有高度的可配置性。用户可以通过命令行参数或系统属性参数（JVM属性参数）两种方式对Equinox OSGi运行环境进行设定。命令行参数可以看作是系统属性参数的简化方式，Equinox中提供的很多系统属性参数可能不具有对应的命令行快捷设定。
2、Equinox配置参数详解
Equinox配置的参数在实际使用中可以通过以下三种方式：
- 在命令行中，使用Java虚拟机参数-D作为系统属性来设定，如：-Declipse.ignoreApp=true；
- 在配置文件config.ini文件中进行配置，如：osgi.framework=plugins/org.eclipse.osgi_<版本号>.jar
- 在Eclipse Launcher的配置文件<launcher>.ini文件中进行配置。在此配置文件中用户需要使用命令行参数而不是系统属性的格式。如：-console。用户在发布Equinox或RCP应用时可以设定启动程序（Eclipse Launcher）的名称和图标，如将启动程序改为：MyApp.exe，则对应的启动配置文件应命名为：MyApp.ini。
下表列举了Equinox3.3版本主要的配置参数。该列表包括系统参数，用于JVM属性配置或config.ini文件配置；命令行参数（如果有）用于<launcher>.ini文件配置；参数的简要说明描述该参数的用途。
说明：
- 表中所列参数来自于Eclipse3.3帮助文档，关于参数的解释可能不够准确，请用户参考Eclipse帮助获取详细信息。
- 表中所列参数严格说来仅部分用于Equinox OSGi，全部适用于Eclipse。在下述说明中将不区分Equinox和Eclipse。
| 系统参数 | 命令行参数 | 参数说明 |
| eclipse.activateRuntimePlugins | 用于控制运行时（Runtime）插件的激活。如果RCP应用程序不需要使用运行时插件提供的服务，可以将该属性值设定为false，从而避免在系统启动时激活运行时插件。 | |
| eclipse.allowAppRelaunch | 如果值为true，当当前运行的应用程序Application退出时，Equinox系统主线程会一直等待该应用的另一个应用被启动。如果停止system.bundle即Bundle ID值为0的Bundle，则会强制Equinox主线程停止等待另一个应用启动。该参数的默认值为false。 | |
| eclipse.application | -application <id> | 该Equinox系统所启动的应用程序的标识符。该参数值会覆盖eclipse.product系统属性中定义的应用程序。 |
| eclipse.application.launchDefault | 当系统启动时，该属性用于自动启动默认的Application应用。默认的应用通过eclipse.application或eclipse.product系统属性设定。该属性的默认值为"true"。如果该属性值设为false，当系统启动时不会自动启动默认的application，系统主线程会持续等待，直至一个application通过应用描述符服务（application descriptor service）启动。 | |
| eclipse.application.registerDescriptors | 该属性控制所有安装的application是否注册相应的应用描述符服务。该属性的默认值为false。如果设定为false，只有默认的application在服务注册表中具有相应的应用描述符服务；如果设定为true，所有安装的application在OSGi服务注册表中都具有相应的应用描述符服务注册。 | |
| eclipse.commands | 在启动Equinox系统时，使用该属性参数将用回车换行方式分隔的命令行参数列表传递给系统。 | |
| eclipse.consoleLog | 如果该属性参数设定且值为true，则所有的日志输出都会传送到Java的System.out。该属性参数可以和-debug参数结合用于调试。 | |
| eclipse.debug.startupTime | 该属性用于设定系统运行时Java虚拟机启动的时间（单位为毫秒） |
|
| eclipse.ee.install.verify | 如果该属性值设定为true，在Bundle组件安装时，OSGi框架会检查框架运行所需要的运行环境。该参数默认值为false。 | |
| eclipse.exitOnError | 该参数设定为true时，如果系统在运行时遇到无法处理的错误，则系统会退出。该参数默认值为true。 | |
| eclipse.ignoreApp | 该参数设定为true时，系统主线程将不启动默认的application，同时停止并退出系统进程。该属性参数的默认值为false。 该参数不同于"eclipse.application.launchDefault"，系统主线程不会等待任何的应用描述符服务启动。 |
|
| eclipse.log.backup.max | 该参数用于设定允许备份的日志文件的最大数。如果备份的日志文件的数量达到该参数的设定值，则最早的日志文件将被删除。该参数的默认值为10，如果用户设定值小于或等于0，则系统启用默认值。 | |
| eclipse.log.size.max | 每个日志文件的最大允许文件大小（单位：KB），该参数的默认值为"1000"。当日志文件达到允许的最大值时，日志文件会循环写入。如果该参数值被设定为0或负值，Equinox系统会使用默认值。 | |
| eclipse.noExtensionMunging | 如果该参数值为 "true"，则遗留的注册扩展将会保留。默认情况下，这些扩展会更新为Eclipse3.0中的新的扩展点。 | |
| eclipse.noLazyRegistryCacheLoading {-noLazyRegistryCacheLoading} |
如果该参数值为"true"，平台的插件注册表缓存加载优化将不被激活。默认情况下，配置项在需要的时候会从注册表缓存（如果存在）中加载，以提升性能。该参数如果值为true，系统启动时会强制加载所有注册表缓存信息。 | |
| eclipse.noRegistryCache | -noRegistryCache | 如果该参数值为"true"，将不使用内部扩展注册缓存。 |
| eclipse.pluginCustomization {-pluginCustomization} |
保存默认插件配置的属性文件的文件路径。该属性文件中的配置项会覆盖主配置中的插件属性。如果该参数值为相对路径，则系统会认为路径相对于当前eclipse工作目录。 | |
| eclipse.product | -product | 运行的产品标识。该参数控制各种产品定义信息和产品使用的application |
| eclipse.service.jobs | 该参数控制org.eclipse.core.jobs插件是否注册为OSGi服务，如果值为"false"则不注册为OSGi服务 |
|
|
该参数控制org.eclipse.equinox.preferences插件是否注册为OSGi服务，如果值为"false"则不注册为OSGi服务 |
|
| eclipse.startTime | 该参数在Equinox启动时设定。该参数的值为System.currentTimeMillis()方法返回值的字符串表示。用户不需要设定该参数 | |
| eclipse.stateSaveDelayInterval | 该参数为系统状态变更请求的序列化延迟间隔，单位毫秒，默认值为30000ms。该参数用于阻止系统管理操作（如安装Bundle组件）过程中产生的大量的磁盘写操作。 | |
| eclipse.vm | -vm | 该参数指向系统启动所需的Java执行程序(JRE)的路径。如果不指定此项，则 JRE 位于 jre（它与Eclipse.exe 可执行文件位于同一目录）。此信息用于构造系统重启使用的命令行。 |
|
|
该参数用于配置系统启动所需的Java虚拟机参数。此信息用于构造系统重启使用的命令行。 |
| osgi.adaptor | OSGi框架启动使用的框架适配（framework adaptor）的类名称 | |
|
|
定义 Eclipse 平台在其上运行的处理器体系结构。Eclipse 平台通常使用 Java os.arch 属性的常用值来计算最佳设置。如果在此处指定该项，则这是 Eclipse 平台使用的值。此处指定的值可作为 BootLoader.getOSArch() 用于插件。示例值有："x86"、"sparc"、"PA-RISC"和"ppc"。 |
| osgi.baseConfiguration.area | 当osgi.configuration.area参数未指定时，该参数用于指定基本的配置信息。 | |
|
该参数用于限定框架保持打开的Jar文件的数量。该参数允许的最小值为10，默认最大值不受限定。 | |
| osgi.bundles | 以逗号分隔的bundle列表。该列表中的bundle在系统启动运行时，会自动安装并根据设定启动（可选）。每一个Bundle配置形式遵循下面的规范： <URL | simple bundle location>[@ [<start-level>] [":start"]]如果忽略start-level (>0的整数)被忽略，则将该Bundle设定为默认的启动等级。如果"start"标记被设定，则该Bundle在安装后框架会启动该Bundle。"Simple bundle location"被解释为相对于框架所作路径的上一级目录。"start-level"标明该Bundle应该在哪一OSGi启动等级运行该Bundle，如果。"start-level"未被设定，则系统会自动为Bundle配置适当的默认启动级别。 |
|
| osgi.bundles.defaultStartLevel | 系统安装的所有的Bundle的启动级别。用户可以在osgi.bundles配置中为某一Bundle指定特定的启动等级。如果未设定Bundle的启动等级，则Bundle的启动等级为该参数设定值。该参数默认值为4。 | |
|
如果该参数值为"true"，当一个类或资源查找不到时，类加载器会启动父类加载器进行最后的查找。该参数的默认值为"true" | |
| osgi.compatibility.errorOnFailedStart | Bundle组件可以通过Bundle清单属性"Eclipse-LazyStart"或"Bundle-ActivationPolicy"标记自身的延迟激活策略。自OSGi R4.1规范开始，如果一个设定了延迟激活策略的Bundle启动失败，从该Bundle进行类加载必须仍然成功。在OSGi R4.1之前，Eclipse定义的延迟激活策略允许启动失败的Bundle抛出类加载异常。如果该属性设定为"true"，那么在启动失败的Bundle中加载类时将导致类加载错误；否则，仍然允许从启动失败的Bundle中加载类。 该参数的默认值为"true" |
|
| osgi.compatibility. eagerStart.LazyActivation |
OSGi R4.1规范强制要求所有的Bundle，包括设定了延迟激活策略的Bundle，在允许激活前必须被标记为启动状态。规范添加了一个新方法Bundle.start(options)使得延迟激活的Bundle可以按照设定的延迟激活策略启动。 如果osgi.compatibility.eagerStart.LazyActivation设定为"true"，所有设定了延迟激活策略的组件会被自动标记为激活状态；否则，标记了延迟激活策略的组件必须通过Bundle.start(options)方法来启动。 该参数的默认值为"true"。 |
|
| osgi.checkConfiguration | 如果该参数值为"true"，系统会检查配置缓存的时间戳以保证缓存内容反映了安装的Bundle的最新配置。该参数默认值为"false"。 | |
| osgi.classloader.singleThreadLoads | 如果该参数值为"true"，那么同一时间只能有一个线程允许加载类。默认值为"false"。该参数用于屏蔽可能引发死锁的虚拟机Bug。 | |
|
如果该参数值为"true"，系统在启动时，会清除OSGi框架及Eclipse运行时缓存的任何数据。该参数会清除Bundle依赖缓存和eclipse扩展注册缓存。适用该参数可以强制eclipse重新初始化上述缓存。 | |
| osgi.configuration.cascaded | 如果该参数设定为"true"，该配置会级联到父配置。父配置通过osgi.sharedConfiguration.area参数设定。 | |
|
|
系统配置(默认为config.ini)的存储路径。 |
|
系统配置(默认为config.ini)的默认存储路径。该参数值只有在参数"osgi.configuration.area "未设定时适用。 | |
| osgi.console | -console [port] | 如果该参数设定为一个非空值，系统会启用OSGi控制台。如果该参数的值是一个适当的整数，系统会将该值作为控制台监听用户输入的端口，同时也作为控制台的输出端口。 |
|
该参数用于设定运行的控制台实现的类名称。 | |
|
该参数用于设定控制台输入与输出信息的编码方式。如果该参数未设定，系统默认使用虚拟机file.encoding属性的值，如果file.encoding属性未设定，则默认使用iso8859-1作为编码方式。 | |
|
OSGi框架使用的上下文类加载器的父类加载器类型，有效的类型包括：
|
|
|
|
将平台置于调试方式，并从给定位置处的文件装入调试选项（如果指定的话）。此文件指示哪些调试点可用于插件以及是否已启用它们。如果未给出文件位置，则平台在启动 eclipse 的目录中查找称为".options"的文件。URL 和文件系统路径都可作为文件位置。 |
|
|
将平台置于开发方式。将可选类路径条目（用逗号分隔的列表）添加至每个插件的运行时类路径。例如，当工作空间包含要开发的插件时，指定 -dev bin 会为每个插件项目的名为 bin 的目录添加类路径条目，允许在其中存储最新生成的类文件。除去了冗余或不存在的类路径条目。 |
| osgi.filepermissions.command | 该参数设定一个可选的操作系统命令用于设定抽取的本机代码的文件操作权限。在一些操作系统中，某些本机代码需要设定为可执行，可以使用此参数设定执行授权的命令。如UNIX类型的操作系统，用户可以使用如下代码设定某一可执行文件具有执行权限： osgi.filepermissions.command="chmod +rx [fullpath]"此处[fullpath]用于指代实际的文件路径。 |
|
|
-framework | OSGi框架实现的位置（URL格式）。如osgi.framework=file://d:/proxy/org.eclipse.osgi.jar |
| osgi.frameworkClassPath | 该参数可以为OSGi框架指定一个以逗号分隔的类路径列表。如果设定类路径为相对路径，则系统认为相对于OSGi框架的所在路径（参考osgi.framework)。 | |
|
该参数用于指定框架扩展的Bundle列表。每一个Bundle遵循如下规则： <simple bundle location>系统会在org.eclipse.osgi Bundle的父目录中查找Simple bundle location。框架扩展可以用来使用不同的框架适配来运行Eclipse。框架扩展可用包含一个eclipse.properties文件来设定系统属性。例如，一个提供了自定义框架适配实现的框架扩展可以使用osgi.adaptor属性参数设定其框架适配实现的类名称。 |
|
|
该属性设定Eclipse OSGi框架实现的形式。Eclipse启动时自动设定该属性，不需要用户配置。属性值"jar"表明框架实现包含在一个单一的Jar文件中；属性值"folder"表明框架实现包含在一个文件目录中。 | |
|
用逗号分隔的附加扩展类库文件查找列表。如果未设定此参数，则系统只使用System.mapLibraryName(String)方法返回的值作为查找路径。有些特定的系统允许一种以上的类库扩展，如AIX系统允许.a和.so类库文件扩展，而System.mapLibraryName(String)方法只返回.a的类库文件扩展。 | |
| osgiframeworkParentClassloader | OSGi框架类加载器的父类加载器类型，可用的类型包括：
|
|
| osgi.framework.useSystemProperties | 控制将框架属性设定为全局系统属性还是由每一个框架实例自行持有。默认情况（值为true）下框架属性也配置为系统属性。 该属性在同一个Java虚拟机中运行多个OSGi框架实例时，可让每个实例控制自己独立的属性配置。 |
|
| osgi.hook.configurators | 用逗号分隔的hook配置列表。如果设定了该配置参数，那么系统将只使用该列表中指定的hook配置。所有在hookconfigurators.properties文件中配置的hook将被忽略。 | |
|
用逗号分隔的附加hook配置列表。该参数可用于配置可选的hook配置，如果参数"osgi.hook.configurators"被设定，则该参数的值将被忽略。 | |
| osgi.hook.configurators.exclude | 用逗号分隔的被排除的hook配置的列表。该参数可用于排除hookconfigurators.properties配置文件中配置的hook。如果参数"osgi.hook.configurators"被设定，则该参数的值将被忽略。 | |
| osgi.install.area | -install | 平台的安装位置。该位置指明了Eclipse插件的位置，一般为eclipse目录下的plugins目录。 |
|
|
运行系统实例数据存储区。插件使用此位置存储其运行数据。默认情况下，用户可以在此参数下的.metadata目录及子目录中找到这些数据。该参数也是资源插件用来存储项目的位置，即工作空间Workspace。 |
|
运行系统默认的实例数据存储区。系统中的插件使用此位置存储各自的运行数据。例如，资源插件使用该位置存储所有项目（即工作空间workspace）。该参数仅在配置参数"osgi.instance.area"未设定时启用。 | |
|
运行平台所使用的锁类型。可用的类型包括："java.io", "java.nio", 和 "none"。默认值为"java.nio"。如果JRE不支持"java.nio"，那么"java.io"将作为默认值。 | |
|
Bundle清单的生成和查找路径。Bundle清单缓存位置可以独立设定，默认为系统配置存储区。 | |
|
|
定义 Eclipse 平台在其上运行的语言环境的名称。Eclipse 平台通常自动计算最佳设置。如果在此处指定该项，则这是 Eclipse 平台使用的值。此处指定的值可作为 BootLoader.getNL() 用于插件。示例值有："en_US"和"fr_FR_EURO"。 |
|
当用户在命令行添加-nl参数时，该属性设定locale的名称。 | |
| osgi.noShutdown | -noExit | 如果值为"true"，当eclipse应用程序停止时，Java虚拟机并不退出。这在eclipse应用停止后检查OSGi框架非常有帮助。 |
|
|
定义 Eclipse 平台在其上运行的操作系统。Eclipse 平台通常使用 Java os.name 属性的常用值来计算最佳设置。如果在此处指定该项，则这是 Eclipse 平台使用的值。此处指定的值可作为 BootLoader.getOS() 用于插件，并用于解析插件清单文件中提及的路径中 $os$ 变量的出现。示例值有："win32"、"linux"、"hpux"、"solaris"和"aix"。 |
| osgi.parentClassloader | 框架中所有安装的Bundle的类加载器的父类加载器类型。可用的类型为：
|
|
| osgi.requiredJavaVersion | 运行Eclipse所要求的Java环境的最低版本。默认值为"1.4.1"。 | |
| osgi.resolverMode | 对安装到框架中的Bundle的解析模式。设定值为"strict"时，框架将使用严格的解析模式。默认的解析模式是不严格的。当使用严格模式解析Bundle时，框架从标记了x-internal 或 x-friends标签的导出包中加载类或资源时使用更严格的访问限定。 | |
| osgi.sharedConfiguration.area | Eclipse平台运行时的共享配置存储区。如果参数"osgi.configuration.cascaded"设定为"true" ，该参数定义的共享配置存储区内的配置将作为根配置。 | |
| osgi.splashLocation | 运行系统时，启动屏幕（.bmp文件）的URL绝对路径。该属性会覆盖"osgi.splashPath"属性的设定值。 | |
| osgi.splashPath | 用逗号分隔的URL，该URL指向一个名为"splash.bmp"的文件。该属性会被配置参数"osgi.splashLocation"设定的任何值覆盖。 | |
| osgi.startLevel | 框架的启动级别，默认启动级别为6。 | |
| osgi.support.signature.verify | 用逗号分隔的Bundle签名校验策略。可选的策略包括：
|
|
| osgi.syspath | 指定Eclipse OSGi框架(org.eclipse.osgi)实现的存储路径，如"<eclipse install path>/eclipse/plugins"。该属性在Eclipse平台启动时由系统设定，不需要用户配置。 | |
| osgi.user.area | -user | 用户数据的存储位置。该位置特定于操作系统用户，与Eclipse安装位置无关，可用于存储用户配置数据。 |
| osgi.user.area.default | 用户数据的默认存储位置。该位置特定于操作系统用户，与Eclipse安装位置无关，可用于存储用户配置数据。该属性只在参数"osgi.user.area"未设定时使用。 | |
| osgi.ws | -ws | 该参数设定窗口系统类型，如win32, motif, ... |
3、其他命令行参数
说明：下述参数仅用于3.3以上版本
- --launcher.ini <location> (Executable) NEW
- <launcher>.ini文件的位置。如果不指定，系统会在执行程序的相同位置查找与执行程序相同名称且扩展名为.ini的文件。如eclipse.exe会查找eclipse.ini，product.exe会查找product.ini。
- --launcher.suppressErrors (Executable) NEW
- 如果指定该参数，启动程序将不显示任何错误或消息窗口。
- -name <string> NEW
-
当应用程序启动后，在任务中显示的程序名称。如果未设定，将显示<launcher>.exe的名称。
- -noSplash (版本1.0+)
- 是否显示启动屏幕
- -showSplash <bitmap> (Executable, Main) NEW
- 指定启动屏幕使用的bitmap文件。如果设定了该参数，Equinox Launcher会在启动Java虚拟机之前显示启动屏幕。如果未指定，虚拟机启动后Main入口会查找参数osgi.splashLocation 和 osgi.splashPath 设定的启动屏幕文件。
- -startup <location> (Executable) NEW
- 启动eclipse使用的jar文件的位置。该jar文件的MANIFEST.MF文件中中应设定Main-Class属性的值为：org.eclipse.equinox.launcher.Main。如果该参数未设定，Launcher会在plugins目录下查找版本号最大的org.eclipse.equinox.launcher组件。
4、launcher.ini文件格式举例
Equinox launcher.ini文件的命令行参数设定格式如下例所示：
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
-vmargs
-Xms40m
-Xmx256m