ExtensionLoader (Apache OpenNLP :: API 3.0.0-M4 API)
Description: declaration: package: opennlp.tools.util.ext, class: ExtensionLoader

Package opennlp.tools.util.ext

# Class ExtensionLoader

java.lang.Object
opennlp.tools.util.ext.ExtensionLoader

@Internal public class ExtensionLoader extends Object
The `ExtensionLoader` is responsible to load extensions to the OpenNLP library.

Only classes whose fully-qualified name starts with a registered package prefix are permitted. The default allowed prefix is `opennlp.`, which covers all built-in factories and serializers.

To allow custom extension classes from other packages, either:

- Call `registerAllowedPackage(String)` programmatically before loading any model that uses the custom class.
- Set the system property `OPENNLP_EXT_ALLOWED_PACKAGES` to a comma-separated list of package prefixes at JVM startup, e.g. `-DOPENNLP_EXT_ALLOWED_PACKAGES=com.acme.nlp.,com.other.`.

Note: Do not use this class, internal use only!

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ALLOWED_PACKAGES_PROPERTY`
  System property for supplying additional allowed package prefixes.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> T`
  `instantiateExtension(Class<T> clazz, String extensionClassName)`
  Instantiates a user provided extension to OpenNLP.
  `static void`
  `registerAllowedPackage(String packagePrefix)`
  Registers an additional package prefix whose classes are permitted to be loaded as OpenNLP extensions.
  `static void`
  `unregisterAllowedPackage(String packagePrefix)`
  Removes a previously registered package prefix.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### ALLOWED_PACKAGES_PROPERTY

    public static final String ALLOWED_PACKAGES_PROPERTY
    System property for supplying additional allowed package prefixes. Value is a comma-separated list, e.g. `com.acme.nlp.,com.other.`.

    This property is read once at class-load time. If it cannot be set via `-D` at JVM startup (e.g. in embedded or test scenarios), call `registerAllowedPackage(String)` before loading any model that uses a custom factory or serializer.

    See Also:
      - Constant Field Values

- ## Method Details

  - ### registerAllowedPackage

    public static void registerAllowedPackage(String packagePrefix)
    Registers an additional package prefix whose classes are permitted to be loaded as OpenNLP extensions. Call this once at application startup, before loading any model that uses a custom factory or serializer from that package.

    The prefix is normalized to end with `'.'` to prevent collision attacks (e.g. registering `"com.acme"` cannot be exploited via `"com.acmeevil.*"`).

    Parameters:
      `packagePrefix` - The package prefix to allow, e.g. `"com.example.nlp"`. Must not be `null` or blank.
    Throws:
      `NullPointerException` - if `packagePrefix` is `null`.
      `IllegalArgumentException` - if `packagePrefix` is blank.

  - ### unregisterAllowedPackage

    public static void unregisterAllowedPackage(String packagePrefix)
    Removes a previously registered package prefix. Has no effect if the prefix was not registered. The default `opennlp.` prefix can also be removed, though this is not recommended.

    The prefix is normalized to end with `'.'` before removal, matching the normalization applied in `registerAllowedPackage(String)`.

    Parameters:
      `packagePrefix` - The package prefix to remove, e.g. `"com.example.nlp"`. Must not be `null`.
    Throws:
      `NullPointerException` - if `packagePrefix` is `null`.

  - ### instantiateExtension

    public static <T> T instantiateExtension(Class<T> clazz, String extensionClassName)
    Instantiates a user provided extension to OpenNLP.

    The extension is loaded from the class path.

    Initially, the load is conducted using the public no-arg constructor. If no such constructor is not found, it is checked if the class follows the `Singleton` pattern: a static field named `INSTANCE` that returns an object of the type `ExtensionLoader`.

    Parameters:
      `clazz` - A reference to `Class<T>`.
      `extensionClassName` - The (fully-qualified) name of the class by which the extension shall be loaded.
    Returns:
      the instance of the extension class
    Throws:
      `ExtensionNotLoadedException` - Thrown if the load operation failed or the class is not in an allowed package.