ConfigAttribute.java revision 63f448170875fbc69cfd9496507eab923535e07d
* The contents of this file are subject to the terms of the * Common Development and Distribution License, Version 1.0 only * (the "License"). You may not use this file except in compliance * See the License for the specific language governing permissions * and limitations under the License. * When distributing Covered Code, include this CDDL HEADER in each * If applicable, add the following below this CDDL HEADER, with the * fields enclosed by brackets "[]" replaced with your own identifying * Portions Copyright [yyyy] [name of copyright owner] * Copyright 2006-2008 Sun Microsystems, Inc. * Portions Copyright 2014-2015 ForgeRock AS * This class defines a configuration attribute, which can hold zero or more * values associated with a configurable property within the Directory Server. * Subclasses should define and enforce actual data types. * Indicates whether this configuration attribute has pending changes that * will be applied after appropriate administrative action has been performed. /** Indicates whether this configuration attribute may have multiple values. */ /** Indicates whether this configuration attribute is required to have a value. */ * Indicates whether changes to this attribute require administrative action * before they will take effect. * The value or set of values that are currently in effect for this * configuration attribute. * The value or set of values that will be in effect once the appropriate * administrative action has been taken. /** The description for this configuration attribute. */ /** The name for this configuration attribute. */ * Creates a new configuration attribute stub with the provided information * but no values. The values will be set using the * <CODE>setInitialValue</CODE> method. * @param name The name for this configuration attribute. * @param description The description for this configuration * @param isRequired Indicates whether this configuration attribute * is required to have at least one value. * @param isMultiValued Indicates whether this configuration attribute * may have multiple values. * @param requiresAdminAction Indicates whether changes to this * configuration attribute require administrative * action before they will take effect. * Creates a new configuration attribute with the provided information. * @param name The name for this configuration attribute. * @param description The description for this configuration * @param isRequired Indicates whether this configuration attribute * is required to have at least one value. * @param isMultiValued Indicates whether this configuration attribute * may have multiple values. * @param requiresAdminAction Indicates whether changes to this * configuration attribute require administrative * action before they will take effect. * @param activeValues The set of values for this attribute that are * Creates a new configuration attribute with the provided information. * @param name The name for this configuration attribute. * @param description The description for this configuration * @param isRequired Indicates whether this configuration attribute * is required to have at least one value. * @param isMultiValued Indicates whether this configuration attribute * may have multiple values. * @param requiresAdminAction Indicates whether changes to this * configuration attribute require administrative * action before they will take effect. * @param activeValues The set of values for this attribute that are * @param hasPendingValues Indicates whether this attribute has any * pending values that will take effect after * appropriate administrative action. * @param pendingValues The set of values for this attribute that will * be in effect after the appropriate * administrative action is taken. This may be * <CODE>null</CODE> if changes will take effect * Retrieves the name for this configuration attribute. * @return The name for this configuration attribute. * Retrieves the description for this configuration attribute. * @return The description for this configuration attribute, or * <CODE>null</CODE> if there is no description. * Retrieves the name of the data type for this configuration attribute. This * is for informational purposes (e.g., inclusion in method signatures and * other kinds of descriptions) and does not necessarily need to map to an * @return The name of the data type for this configuration attribute. * Retrieves the attribute syntax for this configuration attribute. * @return The attribute syntax for this configuration attribute. * Indicates whether this configuration attribute is required to have at least * @return <CODE>true</CODE> if this configuration attribute is required to * have at least one value, or <CODE>false</CODE> if not. * Indicates whether this configuration attribute may have multiple values. * @return <CODE>true</CODE> if this configuration attribute may have * multiple values, or <CODE>false</CODE> if not. * Indicates whether changes to this configuration attribute require * administrative action before they will take effect. * @return <CODE>true</CODE> if changes to this configuration attribute * require administrative action before they will take effect, or * <CODE>false</CODE> if changes will take effect immediately. * Retrieves the set of active values for this configuration attribute. This * must not be modified by the caller. * @return The set of active values for this configuration attribute. * Indicates whether this attribute has been altered and that there are a set * of pending values that will take effect after appropriate administrative * @return <CODE>true</CODE> if this attribute has pending values, or * <CODE>false</CODE> if not. * Retrieves the set of values that this configuration attribute will have on * restart or after any necessary administrative action is performed. For * attributes whose changes take effect immediately, this will always be the * same as the set of active values. This must not be modified by the caller. * @return The set of values that this configuration attribute will have * after any appropriate administrative action is taken. * Indicates whether the provided value is acceptable for use in this * attribute. If it is not acceptable, then the reason should be written into * @param value The value for which to make the determination. * @param rejectReason A buffer into which a human-readable reason for the * @return <CODE>true</CODE> if the provided value is acceptable for use in * this attribute, or <CODE>false</CODE> if not. * Specifies the set of values for this configuration attribute. Each value * will be validated using the <CODE>valueIsAcceptable</CODE> method, and * only a single value will be allowed unless <CODE>isMultiValued</CODE> * returns <CODE>true</CODE>. If the set of values is acceptable, then it * will be set either as the active set of values if changes are to take * effect immediately, or if not then it will be applied to the set of * @param values The set of values to apply to this attribute. * @throws ConfigException If the provided set of values is not acceptable // If no values are provided, then check to see if this is a required // attribute. If it is, then reject the change. // We know that we have at least one value, so get it and see if it is OK. // If this is not a multivalued attribute but there were more values // provided, then reject it. // Iterate through the remaining values to see if they are acceptable. // If we've gotten here, then everything is OK. Make this the new active or // pending value set depending on the configuration. * Specifies the set of active values for this configuration attribute. No * validation will be performed, and no checks will be made to determine if * administrative action is required. * @param values The set of active values for this configuration attribute. * Specifies the set of pending values for this configuration attribute. No * validation will be performed, and no checks will be made to determine if * administrative action is required. * @param values The set of pending values for this configuration attribute. * Attempts to add the provided set of values to this configuration attribute. * All of the appropriate validity checks will be performed, and the changes * will be applied to either the active or pending values, depending on the * configuration of this attribute. * @param values The set of values to add to this configuration attribute. * @throws ConfigException If a problem occurs while attempting to add the * provided set of values to this configuration // If there are no values provided, then do nothing. // Make sure that the value limit will not be exceeded for a single-valued // Create a temporary set of values that we will use for this change. It // may not actually be applied if an error occurs for some reason. // Iterate through all of the provided values. Make sure that each is // acceptable for use and that it is not already contained in the value set. // If we have gotten here, then everything is OK, so go ahead and assign // the temporary value set to either the active or pending lists. * Attempts to remove the set of values from this configuration attribute. * @param values The set of values to remove from this configuration * @throws ConfigException If any of the provided values are not in the * value set, or if this is a required attribute and * the resulting value list would be empty. // Create a temporary set of values that we will use for this change. It // may not actually be applied if an error occurs for some reason. // Iterate through all the provided values and make sure that they are // contained in the list. If not, then throw an exception. If so, then // If this is a required attribute, then make sure that it will have at // If we have gotten here, then everything is OK, so go ahead and assign // the temporary value set to either the active or pending lists. * Removes all values from this configuration attribute. * @throws ConfigException If this is a required attribute that must have at * Assigns the initial values to this configuration attribute. This will wipe * out any previous active or pending values that may have been assigned, and * it will not perform any validation on those values. This method must only * be used to set the initial values for this attribute from the configuration * repository and must not be called any other time. * @param values The initial set of values to assign to this configuration * Applies the set of pending values, making them the active values for this * configuration attribute. This will not take any action if there are no * Converts the provided set of strings to a corresponding set of attribute * @param valueStrings The set of strings to be converted into attribute * @param allowFailures Indicates whether the decoding process should allow * any failures in which one or more values could be * decoded but at least one could not. If this is * <CODE>true</CODE> and such a condition is acceptable * for the underlying attribute type, then the returned * set of values should simply not include those * @return The set of attribute values converted from the provided strings. * @throws ConfigException If an unrecoverable problem occurs while * performing the conversion. * Converts the set of active values for this configuration attribute into a * set of strings that may be stored in the configuration or represented over * protocol. The string representation used by this method should be * compatible with the decoding used by the <CODE>stringsToValues</CODE> * @return The string representations of the set of active values for this * configuration attribute. * Converts the set of pending values for this configuration attribute into a * set of strings that may be stored in the configuration or represented over * protocol. The string representation used by this method should be * compatible with the decoding used by the <CODE>stringsToValues</CODE> * @return The string representations of the set of pending values for this * configuration attribute, or <CODE>null</CODE> if there are no * Retrieves a new configuration attribute of this type that will contain the * values from the provided attribute. * @param attributeList The list of attributes to use to create the config * attribute. The list must contain either one or two * elements, with both attributes having the same base * name and the only option allowed is ";pending" and * only if this attribute is one that requires admin * action before a change may take effect. * @return The generated configuration attribute. * @throws ConfigException If the provided attribute cannot be treated as a * configuration attribute of this type (e.g., if * one or more of the values of the provided * attribute are not suitable for an attribute of * this type, or if this configuration attribute is * single-valued and the provided attribute has * Retrieves a JMX attribute containing the active value set for this * configuration attribute. * @return A JMX attribute containing the active value set for this * configuration attribute. * Retrieves a JMX attribute containing the pending value set for this * configuration attribute. * @return A JMX attribute containing the pending value set for this * configuration attribute. * Adds information about this configuration attribute to the provided JMX * attribute list. If this configuration attribute requires administrative * action before changes take effect and it has a set of pending values, then * two attributes should be added to the list -- one for the active value * and one for the pending value. The pending value should be named with * @param attributeList The attribute list to which the JMX attribute(s) * Adds information about this configuration attribute to the provided list in * the form of a JMX <CODE>MBeanAttributeInfo</CODE> object. If this * configuration attribute requires administrative action before changes take * effect and it has a set of pending values, then two attribute info objects * should be added to the list -- one for the active value (which should be * read-write) and one for the pending value (which should be read-only). The * pending value should be named with the pending option. * @param attributeInfoList The list to which the attribute information * Retrieves a JMX <CODE>MBeanParameterInfo</CODE> object that describes this * configuration attribute. * @return A JMX <CODE>MBeanParameterInfo</CODE> object that describes this * configuration attribute. * Attempts to set the value of this configuration attribute based on the * information in the provided JMX attribute. * @param jmxAttribute The JMX attribute to use to attempt to set the value * of this configuration attribute. * @throws ConfigException If the provided JMX attribute does not have an * acceptable value for this configuration * Creates a duplicate of this configuration attribute. * @return A duplicate of this configuration attribute. * Creates the appropriate value set with the provided value. * The value to use to create the value set. * @return The value set constructed from the provided value. * Creates the appropriate value set with the provided values. * The values to use to create the value set. * @return The constructed value set.