org.opends.server.config
Class ConfigAttribute

java.lang.Object
  extended by org.opends.server.config.ConfigAttribute
Direct Known Subclasses:
BooleanConfigAttribute, DNConfigAttribute, IntegerConfigAttribute, IntegerWithUnitConfigAttribute, MultiChoiceConfigAttribute, ReadOnlyConfigAttribute, StringConfigAttribute

@PublicAPI(stability=VOLATILE,
           mayInstantiate=true,
           mayExtend=true,
           mayInvoke=true)
public abstract class ConfigAttribute
extends java.lang.Object

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.


Constructor Summary
protected ConfigAttribute(java.lang.String name, Message description, boolean isRequired, boolean isMultiValued, boolean requiresAdminAction)
          Creates a new configuration attribute stub with the provided information but no values.
protected ConfigAttribute(java.lang.String name, Message description, boolean isRequired, boolean isMultiValued, boolean requiresAdminAction, java.util.LinkedHashSet<AttributeValue> activeValues)
          Creates a new configuration attribute with the provided information.
protected ConfigAttribute(java.lang.String name, Message description, boolean isRequired, boolean isMultiValued, boolean requiresAdminAction, java.util.LinkedHashSet<AttributeValue> activeValues, boolean hasPendingValues, java.util.LinkedHashSet<AttributeValue> pendingValues)
          Creates a new configuration attribute with the provided information.
 
Method Summary
abstract  java.util.List<java.lang.String> activeValuesToStrings()
          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.
protected  void addValues(java.util.List<AttributeValue> values)
          Attempts to add the provided set of values to this configuration attribute.
 void applyPendingValues()
          Applies the set of pending values, making them the active values for this configuration attribute.
abstract  ConfigAttribute duplicate()
          Creates a duplicate of this configuration attribute.
 java.util.LinkedHashSet<AttributeValue> getActiveValues()
          Retrieves the set of active values for this configuration attribute.
abstract  ConfigAttribute getConfigAttribute(java.util.List<Attribute> attributeList)
          Retrieves a new configuration attribute of this type that will contain the values from the provided attribute.
abstract  java.lang.String getDataType()
          Retrieves the name of the data type for this configuration attribute.
 Message getDescription()
          Retrieves the description for this configuration attribute.
 java.lang.String getName()
          Retrieves the name for this configuration attribute.
 java.util.LinkedHashSet<AttributeValue> getPendingValues()
          Retrieves the set of values that this configuration attribute will have on restart or after any necessary administrative action is performed.
abstract  AttributeSyntax getSyntax()
          Retrieves the attribute syntax for this configuration attribute.
 boolean hasPendingValues()
          Indicates whether this attribute has been altered and that there are a set of pending values that will take effect after appropriate administrative action.
 boolean isMultiValued()
          Indicates whether this configuration attribute may have multiple values.
 boolean isRequired()
          Indicates whether this configuration attribute is required to have at least one value.
abstract  java.util.List<java.lang.String> pendingValuesToStrings()
          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.
protected  void removeAllValues()
          Removes all values from this configuration attribute.
protected  void removeValues(java.util.List<AttributeValue> values)
          Attempts to remove the set of values from this configuration attribute.
 boolean requiresAdminAction()
          Indicates whether changes to this configuration attribute require administrative action before they will take effect.
protected  void setActiveValues(java.util.LinkedHashSet<AttributeValue> values)
          Specifies the set of active values for this configuration attribute.
 void setInitialValues(java.util.LinkedHashSet<AttributeValue> values)
          Assigns the initial values to this configuration attribute.
protected  void setPendingValues(java.util.LinkedHashSet<AttributeValue> values)
          Specifies the set of pending values for this configuration attribute.
abstract  void setValue(javax.management.Attribute jmxAttribute)
          Attempts to set the value of this configuration attribute based on the information in the provided JMX attribute.
protected  void setValues(java.util.LinkedHashSet<AttributeValue> values)
          Specifies the set of values for this configuration attribute.
abstract  java.util.LinkedHashSet<AttributeValue> stringsToValues(java.util.List<java.lang.String> valueStrings, boolean allowFailures)
          Converts the provided set of strings to a corresponding set of attribute values.
abstract  javax.management.Attribute toJMXAttribute()
          Retrieves a JMX attribute containing the active value set for this configuration attribute.
abstract  void toJMXAttribute(javax.management.AttributeList attributeList)
          Adds information about this configuration attribute to the provided JMX attribute list.
abstract  void toJMXAttributeInfo(java.util.List<javax.management.MBeanAttributeInfo> attributeInfoList)
          Adds information about this configuration attribute to the provided list in the form of a JMX MBeanAttributeInfo object.
abstract  javax.management.Attribute toJMXAttributePending()
          Retrieves a JMX attribute containing the pending value set for this configuration attribute.
abstract  javax.management.MBeanParameterInfo toJMXParameterInfo()
          Retrieves a JMX MBeanParameterInfo object that describes this configuration attribute.
abstract  boolean valueIsAcceptable(AttributeValue value, java.lang.StringBuilder rejectReason)
          Indicates whether the provided value is acceptable for use in this attribute.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ConfigAttribute

protected ConfigAttribute(java.lang.String name,
                          Message description,
                          boolean isRequired,
                          boolean isMultiValued,
                          boolean requiresAdminAction)
Creates a new configuration attribute stub with the provided information but no values. The values will be set using the setInitialValue method.

Parameters:
name - The name for this configuration attribute.
description - The description for this configuration attribute.
isRequired - Indicates whether this configuration attribute is required to have at least one value.
isMultiValued - Indicates whether this configuration attribute may have multiple values.
requiresAdminAction - Indicates whether changes to this configuration attribute require administrative action before they will take effect.

ConfigAttribute

protected ConfigAttribute(java.lang.String name,
                          Message description,
                          boolean isRequired,
                          boolean isMultiValued,
                          boolean requiresAdminAction,
                          java.util.LinkedHashSet<AttributeValue> activeValues)
Creates a new configuration attribute with the provided information.

Parameters:
name - The name for this configuration attribute.
description - The description for this configuration attribute.
isRequired - Indicates whether this configuration attribute is required to have at least one value.
isMultiValued - Indicates whether this configuration attribute may have multiple values.
requiresAdminAction - Indicates whether changes to this configuration attribute require administrative action before they will take effect.
activeValues - The set of values for this attribute that are currently active.

ConfigAttribute

protected ConfigAttribute(java.lang.String name,
                          Message description,
                          boolean isRequired,
                          boolean isMultiValued,
                          boolean requiresAdminAction,
                          java.util.LinkedHashSet<AttributeValue> activeValues,
                          boolean hasPendingValues,
                          java.util.LinkedHashSet<AttributeValue> pendingValues)
Creates a new configuration attribute with the provided information.

Parameters:
name - The name for this configuration attribute.
description - The description for this configuration attribute.
isRequired - Indicates whether this configuration attribute is required to have at least one value.
isMultiValued - Indicates whether this configuration attribute may have multiple values.
requiresAdminAction - Indicates whether changes to this configuration attribute require administrative action before they will take effect.
activeValues - The set of values for this attribute that are currently active.
hasPendingValues - Indicates whether this attribute has any pending values that will take effect after appropriate administrative action.
pendingValues - The set of values for this attribute that will be in effect after the appropriate administrative action is taken. This may be null if changes will take effect immediately.
Method Detail

getName

public java.lang.String getName()
Retrieves the name for this configuration attribute.

Returns:
The name for this configuration attribute.

getDescription

public Message getDescription()
Retrieves the description for this configuration attribute.

Returns:
The description for this configuration attribute, or null if there is no description.

getDataType

public abstract java.lang.String getDataType()
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 actual Java type.

Returns:
The name of the data type for this configuration attribute.

getSyntax

public abstract AttributeSyntax getSyntax()
Retrieves the attribute syntax for this configuration attribute.

Returns:
The attribute syntax for this configuration attribute.

isRequired

public boolean isRequired()
Indicates whether this configuration attribute is required to have at least one value.

Returns:
true if this configuration attribute is required to have at least one value, or false if not.

isMultiValued

public boolean isMultiValued()
Indicates whether this configuration attribute may have multiple values.

Returns:
true if this configuration attribute may have multiple values, or false if not.

requiresAdminAction

public boolean requiresAdminAction()
Indicates whether changes to this configuration attribute require administrative action before they will take effect.

Returns:
true if changes to this configuration attribute require administrative action before they will take effect, or false if changes will take effect immediately.

getActiveValues

public java.util.LinkedHashSet<AttributeValue> getActiveValues()
Retrieves the set of active values for this configuration attribute. This must not be modified by the caller.

Returns:
The set of active values for this configuration attribute.

hasPendingValues

public boolean hasPendingValues()
Indicates whether this attribute has been altered and that there are a set of pending values that will take effect after appropriate administrative action.

Returns:
true if this attribute has pending values, or false if not.

getPendingValues

public java.util.LinkedHashSet<AttributeValue> getPendingValues()
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.

Returns:
The set of values that this configuration attribute will have after any appropriate administrative action is taken.

valueIsAcceptable

public abstract boolean valueIsAcceptable(AttributeValue value,
                                          java.lang.StringBuilder rejectReason)
Indicates whether the provided value is acceptable for use in this attribute. If it is not acceptable, then the reason should be written into the provided buffer.

Parameters:
value - The value for which to make the determination.
rejectReason - A buffer into which a human-readable reason for the reject may be written.
Returns:
true if the provided value is acceptable for use in this attribute, or false if not.

setValues

protected void setValues(java.util.LinkedHashSet<AttributeValue> values)
                  throws ConfigException
Specifies the set of values for this configuration attribute. Each value will be validated using the valueIsAcceptable method, and only a single value will be allowed unless isMultiValued returns true. 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 pending values.

Parameters:
values - The set of values to apply to this attribute.
Throws:
ConfigException - If the provided set of values is not acceptable for some reason.

setActiveValues

protected void setActiveValues(java.util.LinkedHashSet<AttributeValue> values)
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.

Parameters:
values - The set of active values for this configuration attribute.

setPendingValues

protected void setPendingValues(java.util.LinkedHashSet<AttributeValue> values)
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.

Parameters:
values - The set of pending values for this configuration attribute.

addValues

protected void addValues(java.util.List<AttributeValue> values)
                  throws ConfigException
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.

Parameters:
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 attribute.

removeValues

protected void removeValues(java.util.List<AttributeValue> values)
                     throws ConfigException
Attempts to remove the set of values from this configuration attribute.

Parameters:
values - The set of values to remove from this configuration attribute.
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.

removeAllValues

protected void removeAllValues()
                        throws ConfigException
Removes all values from this configuration attribute.

Throws:
ConfigException - If this is a required attribute that must have at least one value.

setInitialValues

public void setInitialValues(java.util.LinkedHashSet<AttributeValue> values)
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.

Parameters:
values - The initial set of values to assign to this configuration attribute.

applyPendingValues

public void applyPendingValues()
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 pending values.


stringsToValues

public abstract java.util.LinkedHashSet<AttributeValue> stringsToValues(java.util.List<java.lang.String> valueStrings,
                                                                        boolean allowFailures)
                                                                 throws ConfigException
Converts the provided set of strings to a corresponding set of attribute values.

Parameters:
valueStrings - The set of strings to be converted into attribute values.
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 true and such a condition is acceptable for the underlying attribute type, then the returned set of values should simply not include those undecodable values.
Returns:
The set of attribute values converted from the provided strings.
Throws:
ConfigException - If an unrecoverable problem occurs while performing the conversion.

activeValuesToStrings

public abstract java.util.List<java.lang.String> activeValuesToStrings()
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 stringsToValues method.

Returns:
The string representations of the set of active values for this configuration attribute.

pendingValuesToStrings

public abstract java.util.List<java.lang.String> pendingValuesToStrings()
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 stringsToValues method.

Returns:
The string representations of the set of pending values for this configuration attribute, or null if there are no pending values.

getConfigAttribute

public abstract ConfigAttribute getConfigAttribute(java.util.List<Attribute> attributeList)
                                            throws ConfigException
Retrieves a new configuration attribute of this type that will contain the values from the provided attribute.

Parameters:
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.
Returns:
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 multiple values).

toJMXAttribute

public abstract javax.management.Attribute toJMXAttribute()
Retrieves a JMX attribute containing the active value set for this configuration attribute.

Returns:
A JMX attribute containing the active value set for this configuration attribute.

toJMXAttributePending

public abstract javax.management.Attribute toJMXAttributePending()
Retrieves a JMX attribute containing the pending value set for this configuration attribute.

Returns:
A JMX attribute containing the pending value set for this configuration attribute.

toJMXAttribute

public abstract void toJMXAttribute(javax.management.AttributeList attributeList)
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 the pending option.

Parameters:
attributeList - The attribute list to which the JMX attribute(s) should be added.

toJMXAttributeInfo

public abstract void toJMXAttributeInfo(java.util.List<javax.management.MBeanAttributeInfo> attributeInfoList)
Adds information about this configuration attribute to the provided list in the form of a JMX MBeanAttributeInfo 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.

Parameters:
attributeInfoList - The list to which the attribute information should be added.

toJMXParameterInfo

public abstract javax.management.MBeanParameterInfo toJMXParameterInfo()
Retrieves a JMX MBeanParameterInfo object that describes this configuration attribute.

Returns:
A JMX MBeanParameterInfo object that describes this configuration attribute.

setValue

public abstract void setValue(javax.management.Attribute jmxAttribute)
                       throws ConfigException
Attempts to set the value of this configuration attribute based on the information in the provided JMX attribute.

Parameters:
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 attribute.

duplicate

public abstract ConfigAttribute duplicate()
Creates a duplicate of this configuration attribute.

Returns:
A duplicate of this configuration attribute.