opennlp.tools.util.ext

## Class ExtensionLoader

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

-     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 and Description
    --- | ---
    `static String` | `ALLOWED_PACKAGES_PROPERTY` System property for supplying additional allowed package prefixes.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> T` | `instantiateExtension(Class<T> clazz, String extensionClassName)` Instantiates an 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 Detail

    - #### 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 Detail

    - #### 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 an user provided extension to OpenNLP.

      The extension is either loaded from the class path or if running inside an OSGi environment via an OSGi service.

      Initially it tries using the public default constructor. If it is not found, it will check if the class follows the singleton pattern: a static field named `INSTANCE` that returns an object of the type `T`.

      Parameters:
        `clazz` -
        `extensionClassName` -
      Returns:
        the instance of the extension class
      Throws:
        `ExtensionNotLoadedException` - Thrown if the load operation failed or the class is not in an allowed package.

Copyright © 2026 The Apache Software Foundation. All rights reserved.