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 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:
  • 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:
      IllegalArgumentException - if packagePrefix is null or 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:
      IllegalArgumentException - if packagePrefix is null.
    • loadExtensionClass

      public static <T> Class<? extends T> loadExtensionClass(Class<T> clazz, String extensionClassName) throws ClassNotFoundException
      Resolves the class with the given name as a subtype of clazz without instantiating it.

      The class name is checked against the allowed package prefixes before the class is looked up. The class is located without being initialized, so its static initializers only run once the caller creates an instance of it. This allows callers that need a constructor with arguments to apply the same package check as instantiateExtension(Class, String).

      Like instantiateExtension(Class, String), the class is resolved through the class loader that loaded ExtensionLoader, so it must be visible to that loader.

      Type Parameters:
      T - The expected super type.
      Parameters:
      clazz - A reference to the expected super type Class<T>. Must not be null.
      extensionClassName - The (fully-qualified) name of the class to resolve.
      Returns:
      The resolved class, typed as a subclass of clazz.
      Throws:
      ExtensionNotLoadedException - Thrown if extensionClassName is null, is not in an allowed package, or does not denote a subtype of clazz.
      ClassNotFoundException - Thrown if the class is in an allowed package but could not be located on the class path.
      IllegalArgumentException - Thrown if clazz is null.
      Since:
      3.0.0
    • 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 T.

      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.