org.osgi.framework

Class FrameworkUtil

java.lang.Object

org.osgi.framework.FrameworkUtil

public class FrameworkUtil
extends java.lang.Object

Framework Utility class.

This class contains utility methods which access Framework functions that may be useful to bundles.

Since:

1.3

"ThreadSafe"

Method Summary

Modifier and Type	Method and Description
static <K,V> java.util.Dictionary<K,V>	asDictionary(java.util.Map<? extends K,? extends V> map) Return a Dictionary wrapper around a Map.
static <K,V> java.util.Map<K,V>	asMap(java.util.Dictionary<? extends K,? extends V> dictionary) Return a Map wrapper around a Dictionary.
static Filter	createFilter(java.lang.String filter) Creates a Filter object.
static Bundle	getBundle(java.lang.Class<?> classFromBundle) Return a Bundle for the specified bundle class.
static java.util.Optional<Bundle>	getBundle(java.lang.ClassLoader bundleClassLoader) Return a Bundle for the specified bundle class loader.
static boolean	matchDistinguishedNameChain(java.lang.String matchPattern, java.util.List<java.lang.String> dnChain) Match a Distinguished Name (DN) chain against a pattern.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createFilter

public static Filter createFilter(java.lang.String filter)
                           throws InvalidSyntaxException

Creates a Filter object. This Filter object may be used to match a ServiceReference object or a Dictionary object.

If the filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

This method returns a Filter implementation which may not perform as well as the framework implementation-specific Filter implementation returned by BundleContext.createFilter(String).

Parameters:

filter - The filter string.

Returns:

A Filter object encapsulating the filter string.

Throws:

InvalidSyntaxException - If filter contains an invalid filter string that cannot be parsed.

java.lang.NullPointerException - If filter is null.

See Also:

Filter

matchDistinguishedNameChain

public static boolean matchDistinguishedNameChain(java.lang.String matchPattern,
                                                  java.util.List<java.lang.String> dnChain)

Match a Distinguished Name (DN) chain against a pattern. DNs can be matched using wildcards. A wildcard ('*' \u002A) replaces all possible values. Due to the structure of the DN, the comparison is more complicated than string-based wildcard matching.

A wildcard can stand for zero or more DNs in a chain, a number of relative distinguished names (RDNs) within a DN, or the value of a single RDN. The DNs in the chain and the matching pattern are canonicalized before processing. This means, among other things, that spaces must be ignored, except in values.

The format of a wildcard match pattern is:

 matchPattern ::= dn-match ( ';' dn-match ) *
 dn-match     ::= ( '*' | rdn-match ) ( ',' rdn-match ) * | '-'
 rdn-match    ::= name '=' value-match
 value-match  ::= '*' | value-star
 value-star   ::= < value, requires escaped '*' and '-' >
 

The most simple case is a single wildcard; it must match any DN. A wildcard can also replace the first list of RDNs of a DN. The first RDNs are the least significant. Such lists of matched RDNs can be empty.

For example, a match pattern with a wildcard that matches all DNs that end with RDNs of o=ACME and c=US would look like this:

 *, o=ACME, c=US
 

This match pattern would match the following DNs:

 cn = Bugs Bunny, o = ACME, c = US
 ou = Carrots, cn=Daffy Duck, o=ACME, c=US
 street = 9C\, Avenue St. Drézéry, o=ACME, c=US
 dc=www, dc=acme, dc=com, o=ACME, c=US
 o=ACME, c=US
 

The following DNs would not match:

 street = 9C\, Avenue St. Drézéry, o=ACME, c=FR
 dc=www, dc=acme, dc=com, c=US
 

If a wildcard is used for a value of an RDN, the value must be exactly *. The wildcard must match any value, and no substring matching must be done. For example:

 cn=*,o=ACME,c=*
 

This match pattern with wildcard must match the following DNs:

 cn=Bugs Bunny,o=ACME,c=US
 cn = Daffy Duck , o = ACME , c = US
 cn=Road Runner, o=ACME, c=NL
 

But not:

 o=ACME, c=NL
 dc=acme.com, cn=Bugs Bunny, o=ACME, c=US
 

A match pattern may contain a chain of DN match patterns. The semicolon( ';' \u003B) must be used to separate DN match patterns in a chain. Wildcards can also be used to match against a complete DN within a chain.

The following example matches a certificate signed by Tweety Inc. in the US.

 * ; ou=S & V, o=Tweety Inc., c=US
 

The wildcard ('*') matches zero or one DN in the chain, however, sometimes it is necessary to match a longer chain. The minus sign ( '-' \u002D) represents zero or more DNs, whereas the asterisk only represents a single DN. For example, to match a DN where the Tweety Inc. is in the DN chain, use the following expression:

 - ; *, o=Tweety Inc., c=US
 

Parameters:

matchPattern - The pattern against which to match the DN chain.

dnChain - The DN chain to match against the specified pattern. Each element of the chain must be of type String and use the format defined in RFC 2253.

Returns:

true If the pattern matches the DN chain; otherwise false is returned.

Throws:

java.lang.IllegalArgumentException - If the specified match pattern or DN chain is invalid.

Since:

1.5

getBundle

public static java.util.Optional<Bundle> getBundle(java.lang.ClassLoader bundleClassLoader)

Return a Bundle for the specified bundle class loader.

Parameters:

bundleClassLoader - A bundle class loader.

Returns:

An Optional containing Bundle for the specified bundle class loader or an empty Optional if the specified class loader is not associated with a specific bundle.

Since:

1.10

getBundle

public static Bundle getBundle(java.lang.Class<?> classFromBundle)

Return a Bundle for the specified bundle class.

Parameters:

classFromBundle - A class defined by a bundle.

Returns:

A Bundle for the specified bundle class or null if the specified class was not defined by a bundle.

Since:

1.5

asMap

public static <K,V> java.util.Map<K,V> asMap(java.util.Dictionary<? extends K,? extends V> dictionary)

Return a Map wrapper around a Dictionary.

Type Parameters:

K - The type of the key.

V - The type of the value.

Parameters:

dictionary - The dictionary to wrap.

Returns:

A Map object which wraps the specified dictionary. If the specified dictionary can be cast to a Map, then the specified dictionary is returned.

Since:

1.10

asDictionary

public static <K,V> java.util.Dictionary<K,V> asDictionary(java.util.Map<? extends K,? extends V> map)

Return a Dictionary wrapper around a Map.

Type Parameters:

K - The type of the key.

V - The type of the value.

Parameters:

map - The map to wrap.

Returns:

A Dictionary object which wraps the specified map. If the specified map can be cast to a Dictionary, then the specified map is returned.

Since:

1.10