FrameworkUtil
Date: 2016-06-24

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

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 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 Bundle getBundle(java.lang.Class<?> classFromBundle)

      Return a `Bundle` for the specified bundle class. The returned `Bundle` is the bundle associated with the bundle class loader which defined the specified class.
      Parameters:
        `classFromBundle` - A class defined by a bundle class loader.
      Returns:
        A `Bundle` for the specified bundle class or `null` if the specified class was not defined by a bundle class loader.
      Since:
        1.5