OSGi R4服务平台核心规范 :第六章 Framework API(7)

 由  满江红开放技术研究组织 发布

6.1.16. public class FrameworkUtil

框架实用类
这个包含了访问框架功能的通用的方法,对bundle来说,这些方法可能很有用。
Since 1.3

6.1.16.1. public static Filter createFilter( String filter ) throws InvalidSyntaxException

filter 表达式字符串。
创建一个Filter对象。可以使用这个Filter对象来和一个ServiceReference对象或者是Dictionary对象进行匹配。 如果不能解析表达式字符串,那么抛出异常InvalidSyntaxException,并且在异常中包含了可读信息描述不能解析的部分。
Returns 封装了表达式字符串的Filter对象。
Throws InvalidSyntaxException – 如果在Filter中包含了不能解析的部分。
NullPointerException – 如果filter参数为null。
See Also Filter[p.167]

6.1.17. public class InvalidSyntaxException extends Exception

框架异常
一个InvalidSyntaxException对象中包含了一个具有无效语法而不能解析的表达式字符串参数。
See Filter[p.167]关于表达式字符串的语法描述。

6.1.17.1. public InvalidSyntaxException( String msg, String filter )

msg 消息
filter 非法的表达式字符串
创建一个InvalidSyntaxException类型的异常。 这个方法创建一个InvalidSyntaxException对象,对象中包含了指定的消息和产生异常的表达式字符串。

6.1.17.2. public InvalidSyntaxException( String msg, String filter, Throwable cause)

msg 消息
filter 非法的表达式字符串
cause 异常的原因
创建一个InvalidSyntaxException类型的异常。 这个方法创建一个InvalidSyntaxException对象,对象中包含了指定的消息和产生异常的表达式字符串。
Since 1.3

6.1.17.3. public Throwable getCause( )

返回异常的原因,如果创建这个对象的时候没有指定原因,那么返回null。
Returns 异常的原因,如果创建这个对象的时候没有指定原因,那么返回null。
Since 1.3

6.1.17.4. public String getFilter( )

返回生成这个InvalidSyntaxException对象的表达式字符串。
Returns 非法的表达式字符串。
See Also BundleContext.getServiceReferences[p.143]
BundleContext.addServiceListener(ServiceListener,String)[p.138]

6.1.17.5. public Throwable initCause( Throwable cause )

cause异常的原因
异常的原因,只有在构造的时候才可以设置。
Returns这个对象。
ThrowsIllegalStateException – 这个方法通常都会抛出异常IllegalStateException,这是由于只有在创建的时候才可以设置的。
Since1.3

6.1.18. public final class PackagePermission extends BasicPermission

bundle导入或者导出包的权限。其中包名称是点号分割的包全名。例如: org.osgi.service.http
包权限具有两个操作:EXPORT 和IMPORT,其中EXPORT隐含了EXPORT

6.1.18.1. public static final String EXPORT = “export”

操作名称:export。

6.1.18.2. public static final String IMPORT = “import”

操作名称:import。

6.1.18.3. public PackagePermission( String name, String actions )

name 包名称。
actions EXPORT,IMPORT(规范顺序)
定义了在OSGi环境下的导入和/或导出包的权限。
其中包名称使用Java包名称:点号分割的字符串,可以使用通配符。例如:
org.osgi.service.http
javax.servlet.*
*
包权限将授予包的所有版本。如果一个bundle需要导出一个包,那么必须要有合适的包权限;同样的,如果bundle需要导入一个包,也需要具有相应的包权限。
可以将权限赋予给类或者资源。

6.1.18.4. public boolean equals( Object obj )

obj 和这个包权限对象进行比较的Object对象。
判断这两个PackagePermission对象是否相等,这个方法检查这两个对象是否具有相同的包名称和权限操作。
Returns 如果obj对象是一个PackagePermission对象,而且具有相同的包名称和操作,那么返回true,否则返回false。

6.1.18.5. public String getActions( )

返回这个PackagePermission对象的权限操作的规范字符串。 通常返回的操作顺序如下:
EXPORT,IMPORT
Returns 这个PackagePermission对象的权限操作的规范字符串

6.1.18.6. public int hashCode( )

返回这个对象的哈希码
Returns 这个对象的哈希码

6.1.18.7. public boolean implies( Permission p )

p 待查询的目标权限
检查这个对象是否隐含了指定的目标权限。这个方法检查目标Permission对象的包名称是否隐含在这个对象的包名称中。这个PackagePermission对象的操作列表必须要和目标对象的操作匹配或者是隐含了目标对象的操作。 导出包的权限(export)
隐含了导入同名包的权限(import): x.y.*,”export” -> x.y.z,”export” 为true
*,”import” -> x.y, “import” 为true
*,”export” -> x.y, “import” 为 true
x.y,”export” -> x.y.z, “export” 为false
Returns 如果这个对象隐含了指定的包权限操作,那么返回true;否则false。

6.1.18.8. public PermissionCollection newPermissionCollection( )

为对PackagePermission进行排序返回一个新的PermissionCollection对象。
Returns 个新的PermissionCollection对象

6.1.19. public class ServiceEvent extends EventObject

来自框架的事件,描述服务的生命周期改变。
当发生了服务生命周期改变的事件发生之后,将ServiceEvent对象发送到ServiceListener监听器对象。使用类型码来区分事件的类型。
See Also ServiceListener[p.176]

6.1.19.1. public static final int MODIFIED = 2

修改了一个注册的服务的属性。 当服务属性被修改之后,将这个事件同步发送到监听器。 MODIFIED 的值为0x00000002
See Also ServiceRegistration.setProperties[p.180]

6.1.19.2. public static final int REGISTERED = 1

服务已经注册。
当在框架中注册了服务之后,将这个事件同步发送到监听器。
REGISTERED的值为0x00000001
See Also BundleContext.registerService(String[],Object, java.util.Dictionary)[p.145]

6.1.19.3. public static final int UNREGISTERING = 4

正在取消注册服务。
在完成取消注册服务之前,将这个事件同步发送到监听器。
如果一个bundle使用了一个UNREGISTERING的服务,那么当它接收到这个事件之后应该释放对这个服务的使用,当完成了取消注册服务操作之后,框架自动的释放bundle对服务的使用。
UNREGISTERING 的值为0x00000004
See Also ServiceRegistration.unregister[p.180] ,
BundleContext.ungetService[p.147]

6.1.19.4. public ServiceEvent( int type, ServiceReference reference )

type 事件类型
reference 生命周期改变了的服务的ServiceReference对象。
创建一个新的服务事件对象。

6.1.19.5. public ServiceReference getServiceReference( )

返回在生命周期中发生改变的服务的一个服务引用。
这个引用是事件源。
Returns 在生命周期中发生改变的服务的一个服务引用

6.1.19.6. public int getType( )

返回事件的类型。事件类型值为:
• REGISTERED[p.174]
• MODIFIED[p.174]
• UNREGISTERING[p.174]
Returns 服务生命周期改变的类型。

6.1.20. public interface ServiceFactory

允许在OSGi环境中提供定制的服务对象。
当注册服务时,可以使用一个ServiceFactory对象来代替一个服务对象,这样,bundle开发人员就可以控制分配的服务对象,服务对象分配给使用这个服务的bundle。
当bundle请求服务对象时,方法BundleContext.getService(ServiceReference)调用ServiceFactory.getService方法来根据指定的请求bundle来创建一个服务对象。ServiceFactory返回的对象由框架暂存,直到bundle释放了对服务的使用。
当bundle对这个服务的使用计数变为0时(包含停止bundle或者是服务取消注册的情况),调用ServiceFactory.ungetService方法。
在OSGi环境中,只有框架才能使用ServiceFactory对象,而且其他bundle不能获得这个对象。
See Also BundleContext.getService[p.142]

6.1.20.1. public Object getService( Bundle bundle, ServiceRegistration registration )

bundle 使用服务的bundle
registration 服务的服务注册ServiceRegistration对象
创建一个新的服务对象。框架第一次调用这个方法时,指定的bundle调用方法 BundleContext.getService(ServiceReference)请求一个服务对象。服务工厂为每一个bundle返回一个指定的服务对象。 框架暂存返回的值(除非为null),而且如果同样的bundle调用方法BundleContext.getService后,都返回这个暂存的对象。 框架检查返回的服务对象是否为注册时的所有类的实例,如果不是,返回null。
Returns 服务对象,这个对象必须是服务注册时的所有类的实例。
See Also BundleContext.getService[p.142]

6.1.20.2. public void ungetService( Bundle bundle, ServiceRegistration registration, Object service )

bundle 释放服务的bundle
registration 服务的ServiceRegistration对象
service 原来调用ServiceFactory.getService方法返回的服务对象。
释放一个服务对象。
当bundle释放了一个服务之后,框架调用这个方法。有可能已经销毁了这个服务对象。
See Also BundleContext.ungetService[p.147]

6.1.21. public interface ServiceListener extends EventListener

服务事件监听器(ServiceEvent)。当发出了一个ServiceEvent,将这个事件同步发送到bundle监听器(BundleListener)。
ServiceListener是一个接口,bundle的开发人员可以实现这个接口。
框架使用BundleContext.addServiceListener方法来注册一个ServiceListener对象。当注册、修改或者是处理取消注册服务时,传入一个ServiceEvent 对象调用ServiceListener对象。
发送给ServiceListener对象的ServiceEvent对象是通过注册监听器时指定的表达式来过滤选择的。如果Java运行环境支持权限,那么还要增加其他的过滤。只有当定义这个监听器对象类的bundle具有相应的ServicePermission来使用至少一个注册的类名获得服务的时候,ServiceEvent对象才会发送到这个监听器。
而且,还要根据ServiceReference.isAssignableTo(Bundle, String)[p.179]中定义的包资源来对ServiceEvent对象进行过滤。
See Also ServiceEvent[p.173] , ServicePermission[p.176]

6.1.21.1. public void serviceChanged( ServiceEvent event )

event ServiceEvent对象
收到关于服务生命周期改变的通知。

6.1.22. public final class ServicePermission extends BasicPermission

表示对bundle注册或者是获得一个服务的授权。
●ServicePermission.REGISTER操作允许bundle在一个指定的名称上注册一个服务。
●ServicePermission.GET操作允许bundle检测并获得一个服务。

6.1.22.1. public static final String GET = “get”####

权限操作get

6.1.22.2. public static final String REGISTER = “register”

权限操作register

6.1.22.3. public ServicePermission( String name, String actions )

name 类名称
actions get,register(规范顺序)
创建一个ServicePermission对象。
服务的名称通过一个指定的全局类名称来确定。
ClassName ::= |
例如:
org.osgi.service.http.HttpService
org.osgi.service.http.*
org.osgi.service.snmp.*
有两种可能的操作:get 和register。get权限允许拥有权限者通过名称来获得服务。register权限允许bundle在这个名称下注册服务。

6.1.22.4. public boolean equals( Object obj )

obj 待检查的对象
检查这两个ServicePermission对象是否相等。检测指定的obj是否和这个ServicePermission类具有相同的类名和操作。
Returns 如果obj是一个ServicePermission类,而且和这个ServicePermission类具有相同的名称和操作,返回true;
否则返回false。

6.1.22.5. public String getActions( )

返回规范排列的操作字符串。通常返回的顺序如下:get, register。
Returns 表示操作的规范排列的字符串。

6.1.22.6. public int hashCode( )

返回这个对象的哈希值
Returns 这个对象的哈希值

6.1.22.7. public boolean implies( Permission p )

p 检测的目标权限。
检查这个ServicePermission对象是否隐含了指定的权限。
Returns 如果这个对象隐含了指定权限,返回true;否则返回false。

6.1.22.8. public PermissionCollection newPermissionCollection( )

为对ServicePermission对象排序,返回一个新的PermissionCollection对象。
Returns 一个新的PermissionCollection对象,应用于ServicePermission对象排序。

6.1.23. public interface ServiceReference

对服务的引用。当调用BundleContext.getServiceReference方法和BundleContext.getServiceReferences方法时,框架返回一个ServiceReference对象。
可以在bundle之间共享ServiceReference对象,而且可以通过使用ServiceReference对象来检测服务属性,获得服务对象。
每一个在框架中注册的服务都具有一个惟一的ServiceRegistration对象,但是却可能有多个,截然不同的ServiceReference对象,关联到同一个ServiceRegistration对象的多个ServiceReference对象具有相同的哈希值,而且可以看作是相等的(当调用equal方法时返回true)。
如果多次注册了同一个服务对象,那么关联到不同ServiceRegistration对象的ServiceReference对象之间是不相等的。
See Also BundleContext.getServiceReference[p.142] ,
BundleContext.getServiceReferences[p.143] ,
BundleContext.getService[p.142]

6.1.23.1. public Bundle getBundle( )

返回注册这个ServiceReference对象引用服务的bundle。
如果服务已经取消注册,那么这个方法返回null。
这可以用来检测服务是否已经取消注册。
Returns 注册这个ServiceReference对象所引用服务的bundle;
如果已经取消注册了这个服务,那么返回null。
See Also BundleContext.registerService(String[],Object,java.util.Dictionary)[p.145]

6.1.23.2. public Object getProperty( String key )

key 属性键
返回这个ServiceReference对象引用服务的属性Dictionary对象中和指定的属性键匹配的属性值。
属性键是不区分大小写的。
即使服务已经是取消注册的,这个方法依然要返回属性值。这样就可以对已经取消注册的服务(例如,存储在日志中的ServiceReference对象)也可以进行询问。
Returns 匹配的属性键的值;如果没有属性和这个键匹配,返回null。

6.1.23.3. public String[] getPropertyKeys( )

返回这个ServiceReference对象所引用服务的属性Dictionary对象中的属性键数组。
即使服务已经取消注册了,对这个方法的调用依然可以返回属性键。这样就可以对已经取消注册的服务(例如,存储在日志中的ServiceReference对象)也可以进行询问。
这个方法是保留大小写的;也就是说返回的数组中的属性键名称必须要和注册服务时传递给方法BundleContext.registerService(String[],Object, java.util.Dictionary)[p.145] 或者方法ServiceRegistration.setProperties的属性Dictionary中的属性键是大小写一样的。
Returns 属性键数组

6.1.23.4. public Bundle[] getUsingBundle( )

使用这个ServiceReference对象所引用服务的bundle。具体来说,这个方法返回的是对这个服务的使用计数大于0的bundle。
Returns 对这个ServiceReference对象所引用服务的使用计数大于0的bundle数组。 如果没有使用这个服务的bundle,返回null。
Since 1.1

6.1.23.5. public boolean isAssignableTo( Bundle bundle, String className )

bundle 待检测的Bundle对象
className 待检测的类的名称
检查指定bundle和注册了这个ServiceReference所引用服务的bundle是否对指定类使用了同样的包来源。 这个方法按照以下顺序来检查: 1. 从指定类名称来获得包名称; 2. 为注册了这个ServiceReference所引用服务的bundle查找包的来源。如果没有找到来源,而且注册bundle等于传入的参数bundle,返回true;否则返回false; 3. 如果注册bundle的包来源等于传入参数bundle的包来源,返回true;否则返回false。
Returns 如果注册了这个ServiceReference所引用服务的bundle和传入的参数bundle对指定的类具有同样的包来源,返回true;否则返回false。
Since 1.3

6.1.24. public interface ServiceRegistration

一个注册的服务。
当成功调用了BundleContext.registerService方法之后,框架返回一个ServiceRegistration对象。ServiceRegistration对象是注册服务的bundle的私有属性,不能和其他bundle共享。
可以使用这个ServiceRegistration对象来对服务进行属性更新或者是取消注册服务。
See Also BundleContext.registerService(String[],Object,Dictionary)[p.145]

6.1.24.1. public ServiceReference getReference( )

返回一个已经注册了的服务的ServiceReference对象。
可以在bundle之间共享ServiceReference对象。
Returns ServiceReference对象
Throws IllegalStateException – 如果这个服务已经取消注册

6.1.24.2. public void setProperties( Dictionary properties )

properties 服务的属性。参阅Constants[p.153]中的标准服务属性键。调用这个方法之后,就不能再做这个对象修改了。如果要更新服务属性,那么应该重新调用这个方法。
更新相关服务的属性。
这个方法不能修改属性:Constants.OBJECTCLASS[p.162] 和Constants.SERVICE_ID[p.163]。在OSGi环境中注册服务时,由框架来设置这两个属性。
修改服务属性的步骤如下:
1. 根据提供的属性替换服务属性。
2. 发出类型为ServiceEvent.MODIFIED[p.174]的服务事件。
Throws IllegalStateException – 如果已经取消注册了这个ServiceRegistration 对象。
IllegalArgumentException – 如果属性中存在只有大小写不同的同名的键。

6.1.24.3. public void unregister( )

取消注册一个服务。从框架的服务注册中心删除一个ServiceRegistration对象。不能再使用和这个ServiceRegistration对象相关的ServiceReference对象来访问服务了。
按照如下步骤来取消注册一个服务:
1. 从框架的服务注册中心删除这个服务,这样就不能再使用这个服务了。也不能再使用这个服务的ServiceRegistration对象来获得这个服务的服务对象。
2. 发出事件ServiceEvent.UNREGISTERING[p.174],这样使用这个服务的bundle就可以释放对服务的使用。
3. 对于每一个对这个服务的使用计数要大于0的bundle,进行如下操作: bundle对这个服务的使用计数清零。
如果注册的是服务工厂对象(ServiceFactory[p.175]),调用服务工厂对象的ServiceFactory.ungetService方法来释放bundle使用的服务对象。
Throws IllegalStateException – 如果已经取消注册了这个ServiceRegistration对象。
See Also BundleContext.ungetService[p.147] ,
ServiceFactory.ungetService[p.175]

6.1.25. public interface SynchronousBundleListener extends BundleListener

一个同步的bundle事件监听器(BundleEvent)。当发出了bundle事件,将事件同步发送到监听器。
SynchronousBundleListener是一个监听器接口,bundle的开发人员可以实现这个接口。
框架使用BundleContext.addBundleListener[p.137]方法来注册一个同步监听器对象。当对bundle执行如下操作:安装、解析、开始启动、启动完毕、开始停止、停止完毕、更新、取消解析或者卸载的时候,将BundleEvent发送到BundleListener对象,调用这个BundleListener对象。
和一般的BundleListener监听器对象不一样的是,SynchronousBundleListeners监听器是和bundle的生命周期操作处理同步调用的。如果监听器还没有处理完毕,那么对生命周期的操作也就没有结束。对SynchronousBundleListeners对象的调用的优先级要高于BundleListener对象。
为了删除SynchronousBundleListeners对象,需要有如下权限:
AdminPermission[bundle,LISTENER]
See Also BundleEvent[p.148]
Returns 1.1

6.1.26. public class Version implements Comparable

Version标识了bundle和包。
Version具有四部分:
1. 主版本号:非负整数
2. 子版本号:非负整数
3. 微版本号:非负整数
4. 限定符:文本字符串。参考Version(String)获得关于字符串的格式说明。
Version对象是不可变的。
Since 1.3

6.1.26.1. public static final Version emptyVersion

空版本号0.0.0。等价于调用new Version(0,0,0)。

6.1.26.2. public Version( int major, int minor, int micro )

major 版本的主要部分标识
minor 版本的次要部分标识
micro 版本的微部分标识
根据指定的数字来创建一个版本标识。其中限定符为一个空字符串。
Throws IllegalArgumentException – 如果参数中存在负数。

6.1.26.3. public Version( int major, int minor, int micro, String qualifier )

major 版本的主要部分标识
minor 版本的次要部分标识
micro 版本的微部分标识
qualifier 限定符
根据指定的数字来创建一个版本标识。
Throws IllegalArgumentException – 如果参数中存在负数,或者限定符非法。

6.1.26.4. public Version( String version )

version 表示版本限定符的字符串
根据指定字符串创建一个版本标志。 下面是版本字符串中的语法格式: version ::= major(’.’minor(’.’micro(’.’qualifier)?)?)? major ::= digit+ minor ::= digit+ micro ::= digit+ qualifier ::= (alpha|digit|’_’|’-’)+ digit ::= [0..9] alpha ::= [a..zA..Z] 在版本中不能存在空格。
Throws IllegalArgumentException – 如果限定符格式不正确。

6.1.26.5. public int compareTo( Object object )

object 待比较的Version对象
将这个Version对象和传入的object对象进行比较。 如果一个Version对象的主版本号要小,那么这个Version对象的版本就要小于另外一个Version对象的版本;如果主版本号相等,子版本号要小,那么这个Version对象的版本要小于另外一个Version对象的版本;如果主版本号和子版本号都相等,那么就比较微版本号;如果这三者都相等,就比较限定符。限定符的比较使用String.compareTo方法。
Returns 如果这个object对象要小于次Version对象,返回一个负整数
相等返回0
大于责返回一个正整数

6.1.26.6. public boolean equals( Object object )

object 待比较的Version对象。
将这个Version对象和另外一个object对象进行比较。 只有当两个Version对象的四部分都相等的时候,才返回true。 限定符的比较使用String.equals方法。
Returns 如果这个Version对象和object对象相等,返回true;
否则返回false。

6.1.26.7 public int getMajor( )

返回Version对象的主版本号
ReturnsVersion对象的主版本号

6.1.26.8 public int getMicro( )

返回Version对象的子版本号
ReturnsVersion对象的子版本号

6.1.26.9 public int getMinor( )

返回Version对象的微版本号
ReturnsVersion对象的微版本号

6.1.26.10 public String getQualifier( )

返回Version对象的限定符
Returns一个整数,即为这个对象的哈希码

6.1.26.11 public int hashCode( )

返回这个对象的哈希码
Returns一个整数,即为这个对象的哈希码

6.1.26.12 public static Version parseVersion( String version )

version描述这个版本标记的字符串。不考虑起始和结束的空格。分析传入的字符串。
参考Version(String)中关于字符串格式的描述。
Returns这个字符串描述的Version对象。如果参数version为null或者是一个空串,返回一个emptyVersion对象。
ThrowsIllegalArgumentException – 如果参数version的格式不正确。

6.1.26.13 public String toString( )

返回这个Version对象的字符串表示。 如果限定符为一个空串,那么字符串格式为:主版本号.子版本号.微版本号 否则,格式为:主版本号.子版本号.微版本号.限定符
Returns这个Version对象的字符串表示
查看评论