[#1120] Apply a change to plugin-type on an enabled plugin without disabling and enabling it again

opendj-doc-generated-ref/src/main/asciidoc/server-dev-guide/chap-groups.adoc

@@ -539,6 +539,6 @@ member: uid=tmorris,ou=People,dc=example,dc=com
 ----
 By default, the referential integrity plugin is configured to manage `member` and `uniqueMember` attributes. These attributes take values that are DNs, and are indexed for equality by default for the default backend. Before you add an additional attribute to manage, make sure that it has DN syntax and that it is indexed for equality. OpenDJ directory server requires that the attribute be indexed because an unindexed search for integrity would potentially consume too many of the server's resources. Attribute syntax is explained in xref:../admin-guide/chap-schema.adoc#chap-schema["Managing Schema"] in the __Administration Guide__. For instructions on indexing attributes, see xref:../admin-guide/chap-indexing.adoc#configure-indexes["Configuring and Rebuilding Indexes"] in the __Administration Guide__.
 
-You can also configure the referential integrity plugin to check that new entries added to groups actually exist in the directory by setting the `check-references` property to `true`. You can specify additional criteria once you have activated the check. To ensure that entries added must match a filter, set the `check-references-filter-criteria` to identify the attribute and the filter. For example, you can specify that group members must be person entries by setting `check-references-filter-criteria` to `member:(objectclass=person)`. To ensure that entries must be located in the same naming context, set `check-references-scope-criteria` to `naming-context`. The check runs when entries are added and modified, so the plugin must be registered for the `preOperationAdd` and `preOperationModify` plugin types, as the default configuration is. When the plugin is enabled, OpenDJ refuses to set `check-references` to `true` if `plugin-type` lacks either of them, and it refuses to enable a plugin configured that way. A plugin already configured that way when the server starts is loaded with a warning, and it does not check references until the types are added. Plugin types take effect when the plugin is enabled, so add them before enabling the plugin, or disable and re-enable it afterwards.
+You can also configure the referential integrity plugin to check that new entries added to groups actually exist in the directory by setting the `check-references` property to `true`. You can specify additional criteria once you have activated the check. To ensure that entries added must match a filter, set the `check-references-filter-criteria` to identify the attribute and the filter. For example, you can specify that group members must be person entries by setting `check-references-filter-criteria` to `member:(objectclass=person)`. To ensure that entries must be located in the same naming context, set `check-references-scope-criteria` to `naming-context`. The check runs when entries are added and modified, so the plugin must be registered for the `preOperationAdd` and `preOperationModify` plugin types, as the default configuration is. When the plugin is enabled, OpenDJ refuses to set `check-references` to `true` if `plugin-type` lacks either of them, and it refuses to enable a plugin configured that way. A plugin already configured that way when the server starts is loaded with a warning, and it does not check references until the types are added. Added plugin types take effect at once, and the plugin does not need to be disabled and enabled again.
 
 

opendj-doc-generated-ref/src/main/asciidoc/server-dev-guide/chap-writing-plugins.adoc

@@ -373,6 +373,8 @@ Although the example plugin's `isConfigurationChangeAcceptable()` method always
 
 In the `applyConfigurationChange()` method the plugin must modify its configuration as necessary. The example plugin can handle configuration changes without further intervention by the administrator. Other plugins might require administrative intervention because changes can be made that can only be taken into account at plugin initialization.
 
+The plugin types are the exception: a plugin receives them only when it is initialized, so the server does not pass a change to `plugin-type` to the running plugin. When `plugin-type` changes on an enabled plugin, the server creates a new instance of the plugin, initializes it for the new plugin types, registers it in place of the running instance, and then calls the `finalizePlugin()` method of the running instance. If `initializePlugin()` refuses the new plugin types, the change fails and the running instance stays registered for the plugin types it had. The server then calls `finalizePlugin()` of the refused instance, so `finalizePlugin()` must release whatever `initializePlugin()` acquired before it failed, such as a change listener. Until `plugin-type` is changed to types the plugin accepts, every later change of the plugin configuration also fails with the same reason, although the other changes are applied to the running instance. State that the plugin keeps in memory does not carry over to the new instance.
+
 In the example plugin, the method that extends the server's behavior is the `doStartup()` method. Which method is implemented depends on what class the plugin extends. For example, a password validator extending link:../javadoc/index.html?org/opends/server/api/PasswordValidator.html[PasswordValidator, window=\_blank] would implement a `passwordIsAcceptable()` method.
 
 

opendj-maven-plugin/src/main/resources/config/xml/org/forgerock/opendj/server/config/PluginConfiguration.xml

@@ -14,6 +14,7 @@
 
   Copyright 2007-2010 Sun Microsystems, Inc.
   Portions Copyright 2011 ForgeRock AS.
+  Portions Copyright 2026 3A Systems, LLC.
   ! -->
 <adm:managed-object name="plugin" plural-name="plugins"
   package="org.forgerock.opendj.server.config"
@@ -72,11 +73,8 @@
   <adm:property name="plugin-type" mandatory="true"
     multi-valued="true">
     <adm:synopsis>
-      Specifies the set of plug-in types for the plug-in, which specifies the times at which the plug-in is invoked. 
+      Specifies the set of plug-in types for the plug-in, which specifies the times at which the plug-in is invoked.
     </adm:synopsis>
-    <adm:requires-admin-action>
-      <adm:component-restart />
-    </adm:requires-admin-action>
     <adm:syntax>
       <adm:enumeration>
         <adm:value name="startup">

opendj-server-legacy/src/main/java/org/opends/server/api/plugin/DirectoryServerPlugin.java

@@ -13,6 +13,7 @@
  *
  * Copyright 2006-2010 Sun Microsystems, Inc.
  * Portions Copyright 2014-2016 ForgeRock AS.
+ * Portions Copyright 2026 3A Systems, LLC.
  */
 package org.opends.server.api.plugin;
 
@@ -167,7 +168,11 @@ public abstract void initializePlugin(Set<PluginType> pluginTypes,
   /**
    * Performs any necessary finalization for this plugin.  This will
    * be called just after the plugin has been deregistered with the
-   * server but before it has been unloaded.
+   * server but before it has been unloaded.  It is also called when
+   * {@link #initializePlugin} throws, on an instance that was never
+   * registered: it must then release whatever
+   * {@code initializePlugin} acquired before it failed, and must not
+   * assume that it completed.
    */
   public void finalizePlugin()
   {