UnboundID Server SDK

Working with Arguments

Although it is possible to hard-code all of the information needed for an extension to operate directly into the code for that extension, this is not a recommended practice because it means that changes in the environment could require the code to be updated and the extension re-deployed. Similarly, it may be necessary for an extension to operate with different settings in different servers, or even with different settings across multiple instances in the same server. In order to address this, when creating extensions (whether Java-based or scripted), you should use arguments to provide any information that may change based on the contexts in which the extension may be invoked.

Both Java-based and scripted extensions use the argument parsing functionality provided in the com.unboundid.util.args package of the UnboundID LDAP SDK for Java. Each type of extension includes the following abstract methods for defining and interacting with the set of allowed arguments:

• defineConfigArguments – This method is used to update a provided ArgumentParser object to specify the arguments which are allowed for use with the extension. At this point, you can mark which requirements are required and optional, provide constraints and default values if appropriate, and optionally define relationships between arguments.
  
  
• initialize{ExtensionType} – This method is used to initialize the extension from the configuration. An ArgumentParser parameter is provided to the method after having been initialized by the defineConfigArguments method and updated with content from the associated configuration object (the extension‑argument property for Java-based extensions, and the script‑argument property for scripted extensions). This method will be invoked at startup if the extension was already defined and enabled in the configuration, or at the time that the extension is enabled if it is newly-created or was previously disabled.
  
  
• isConfigurationAcceptable – This method is used to determine whether the provided configuration is acceptable for use. It will be provided with an ArgumentParser object that was initialized from the defineConfigArguments method and updated with the proposed configuration for the extension. This method will be used both at the time the extension is enabled and at the time that an attempt is made to alter the configuration for the extension. If the configuration is determined to be unacceptable, then the configuration add or modify operation will be rejected.
  
  
• applyConfiguration – This method may be used to dynamically apply a new configuration for the extension made while it was already defined and enabled. This can be used to respond to configuration changes without the need to restart the server or disable and re-enable the extension.
  
  

Arguments for Java-based extensions will be provided in the extension‑argument property of the configuration object. For scripted extensions, arguments will be provided in the script‑argument property. In either case, arguments should generally be in the form "name=value", where "name" is the long identifier for the corresponding argument (as created in the defineConfigArguments method), and "value" is the value to provide for that argument. If a given argument should have multiple values, then they should be provided to the extension‑argument property as separate "name=value" pairs.

Some additional notes about using arguments in extensions:

• The LDAP SDK argument parser will be used to perform as much validation as possible based on the configuration it has been provided. This includes ensuring that all of the arguments provided are allowed, that all required arguments have been provided, that all argument values conform to the constraints of the associated argument types, and that all defined relationships between arguments (including required argument sets, dependent argument sets, and exclusive argument sets) have been satisfied. If any additional validation is required, then it should be performed in the isConfigurationAcceptable method.
  
  
• If you wish to have arguments which represent Boolean states of either true or false, then you should use the BooleanValueArgument type rather than the BooleanArgument type. BooleanValueArgument objects take a value of either "true" or "false" and are therefore well-suited for use in this context, while BooleanArgument objects do not take a value and are therefore not as well-suited for use in the "name=value" format.
  
  
• Values for FileArgument arguments may be provided as either absolute paths or relative paths (or a mixture of the two). Unless otherwise specified by the FileArgument.setRelativeBaseDirectory method, relative paths will be considered relative to the server root.