server/config/ConfigAttribute.java

/*
 * CDDL HEADER START
 *
 * 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
 * with the License.
 *
 * You can obtain a copy of the license at
 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Copyright 2006-2008 Sun Microsystems, Inc.
 */
package org.opends.server.config;
import org.opends.messages.Message;


import java.util.Iterator;
import java.util.LinkedHashSet;
import java.util.List;
import javax.management.AttributeList;
import javax.management.MBeanAttributeInfo;
import javax.management.MBeanParameterInfo;

import org.opends.server.api.AttributeSyntax;
import org.opends.server.types.Attribute;
import org.opends.server.types.AttributeValue;

import static org.opends.messages.ConfigMessages.*;
/**
 * 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.
 */
@org.opends.server.types.PublicAPI(
     stability=org.opends.server.types.StabilityLevel.VOLATILE,
     mayInstantiate=true,
     mayExtend=true,
     mayInvoke=true)
public abstract class ConfigAttribute
{
  // Indicates whether this configuration attribute has pending changes that
  // will be applied after appropriate administrative action has been performed.
  private boolean hasPendingValues;

  // Indicates whether this configuration attribute may have multiple values.
  private boolean isMultiValued;

  // Indicates whether this configuration attribute is required to have a value.
  private boolean isRequired;

  // Indicates whether changes to this attribute require administrative action
  // before they will take effect.
  private boolean requiresAdminAction;

  // The value or set of values that are currently in effect for this
  // configuration attribute.
  private LinkedHashSet<AttributeValue> activeValues;

  // The value or set of values that will be in effect once the appropriate
  // administrative action has been taken.
  private LinkedHashSet<AttributeValue> pendingValues;

  // The description for this configuration attribute.
  private Message description;

  // The name for this configuration attribute.
  private String name;


  /**
   * 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
   *                              attribute.
   * @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.
   */
  protected ConfigAttribute(String name, Message description,
                            boolean isRequired, boolean isMultiValued,
                            boolean requiresAdminAction)
  {
    this.name                = name;
    this.description         = description;
    this.isRequired          = isRequired;
    this.isMultiValued       = isMultiValued;
    this.requiresAdminAction = requiresAdminAction;

    hasPendingValues = false;
    activeValues     = new LinkedHashSet<AttributeValue>();
    pendingValues    = activeValues;
  }


  /**
   * Creates a new configuration attribute with the provided information.
   *
   * @param  name                 The name for this configuration attribute.
   * @param  description          The description for this configuration
   *                              attribute.
   * @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
   *                              currently active.
   */
  protected ConfigAttribute(String name, Message description,
                            boolean isRequired, boolean isMultiValued,
                            boolean requiresAdminAction,
                            LinkedHashSet<AttributeValue> activeValues)
  {
    this.name                = name;
    this.description         = description;
    this.isRequired          = isRequired;
    this.isMultiValued       = isMultiValued;
    this.requiresAdminAction = requiresAdminAction;
    this.hasPendingValues    = false;

    if (activeValues == null)
    {
      this.activeValues = new LinkedHashSet<AttributeValue>();
    }
    else
    {
      this.activeValues = activeValues;
    }

    this.pendingValues = this.activeValues;
  }


  /**
   * Creates a new configuration attribute with the provided information.
   *
   * @param  name                 The name for this configuration attribute.
   * @param  description          The description for this configuration
   *                              attribute.
   * @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
   *                              currently active.
   * @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
   *                              immediately.
   */
  protected ConfigAttribute(String name, Message description,
                            boolean isRequired, boolean isMultiValued,
                            boolean requiresAdminAction,
                            LinkedHashSet<AttributeValue> activeValues,
                            boolean hasPendingValues,
                            LinkedHashSet<AttributeValue> pendingValues)
  {
    this.name                = name;
    this.description         = description;
    this.isRequired          = isRequired;
    this.isMultiValued       = isMultiValued;
    this.requiresAdminAction = requiresAdminAction;
    this.hasPendingValues    = hasPendingValues;

    if (activeValues == null)
    {
      this.activeValues = new LinkedHashSet<AttributeValue>();
    }
    else
    {
      this.activeValues = activeValues;
    }

    if (! hasPendingValues)
    {
      this.pendingValues = this.activeValues;
    }
    else
    {
      if (pendingValues == null)
      {
        this.pendingValues = new LinkedHashSet<AttributeValue>();
      }
      else
      {
        this.pendingValues = pendingValues;
      }
    }
  }


  /**
   * Retrieves the name for this configuration attribute.
   *
   * @return  The name for this configuration attribute.
   */
  public String getName()
  {
    return name;
  }


  /**
   * Retrieves the description for this configuration attribute.
   *
   * @return  The description for this configuration attribute, or
   *          <CODE>null</CODE> if there is no description.
   */
  public Message getDescription()
  {
    return 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
   * actual Java type.
   *
   * @return  The name of the data type for this configuration attribute.
   */
  public abstract String getDataType();


  /**
   * Retrieves the attribute syntax for this configuration attribute.
   *
   * @return  The attribute syntax for this configuration attribute.
   */
  public abstract AttributeSyntax<?> getSyntax();


  /**
   * Indicates whether this configuration attribute is required to have at least
   * one value.
   *
   * @return  <CODE>true</CODE> if this configuration attribute is required to
   *          have at least one value, or <CODE>false</CODE> if not.
   */
  public boolean isRequired()
  {
    return isRequired;
  }


  /**
   * 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.
   */
  public boolean isMultiValued()
  {
    return isMultiValued;
  }


  /**
   * 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.
   */
  public boolean requiresAdminAction()
  {
    return requiresAdminAction;
  }


  /**
   * 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.
   */
  public LinkedHashSet<AttributeValue> getActiveValues()
  {
    return activeValues;
  }


  /**
   * Indicates whether this attribute has been altered and that there are a set
   * of pending values that will take effect after appropriate administrative
   * action.
   *
   * @return  <CODE>true</CODE> if this attribute has pending values, or
   *          <CODE>false</CODE> if not.
   */
  public boolean hasPendingValues()
  {
    return hasPendingValues;
  }


  /**
   * 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.
   */
  public LinkedHashSet<AttributeValue> getPendingValues()
  {
    if (requiresAdminAction)
    {
      return pendingValues;
    }
    else
    {
      return activeValues;
    }
  }


  /**
   * 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.
   *
   * @param  value         The value for which to make the determination.
   * @param  rejectReason  A buffer into which a human-readable reason for the
   *                       reject may be written.
   *
   * @return  <CODE>true</CODE> if the provided value is acceptable for use in
   *          this attribute, or <CODE>false</CODE> if not.
   */
  public abstract boolean valueIsAcceptable(AttributeValue value,
                                            StringBuilder rejectReason);


  /**
   * 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
   * pending values.
   *
   * @param  values  The set of values to apply to this attribute.
   *
   * @throws  ConfigException  If the provided set of values is not acceptable
   *                           for some reason.
   */
  protected void setValues(LinkedHashSet<AttributeValue> values)
         throws ConfigException
  {
    // If no values are provided, then check to see if this is a required
    // attribute.  If it is, then reject the change.
    if ((values == null) || values.isEmpty())
    {
      if (isRequired)
      {
        Message message = ERR_CONFIG_ATTR_IS_REQUIRED.get(name);
        throw new ConfigException(message);
      }
      else
      {
        if (requiresAdminAction)
        {
          if (values == null)
          {
            pendingValues = new LinkedHashSet<AttributeValue>();
          }
          else
          {
            pendingValues = values;
          }

          hasPendingValues = true;
        }
        else
        {
          if (values == null)
          {
            activeValues = new LinkedHashSet<AttributeValue>();
          }
          else
          {
            activeValues = values;
          }

          pendingValues    = activeValues;
          hasPendingValues = false;
        }

        return;
      }
    }


    // We know that we have at least one value, so get it and see if it is OK.
    Iterator<AttributeValue> iterator     = values.iterator();
    AttributeValue           value        = iterator.next();
    StringBuilder            rejectReason = new StringBuilder();

    if (! valueIsAcceptable(value, rejectReason))
    {
      Message message = ERR_CONFIG_ATTR_REJECTED_VALUE.get(
          value.getValue().toString(), name, rejectReason.toString());
      throw new ConfigException(message);
    }


    // If this is not a multivalued attribute but there were more values
    // provided, then reject it.
    if ((! isMultiValued) && iterator.hasNext())
    {
      Message message = ERR_CONFIG_ATTR_SET_VALUES_IS_SINGLE_VALUED.get(name);
      throw new ConfigException(message);
    }


    // Iterate through the remaining values to see if they are acceptable.
    while (iterator.hasNext())
    {
      value = iterator.next();
      if (! valueIsAcceptable(value, rejectReason))
      {
        Message message = ERR_CONFIG_ATTR_REJECTED_VALUE.get(
            value.getValue().toString(), name, rejectReason.toString());
        throw new ConfigException(message);
      }
    }


    // If we've gotten here, then everything is OK.  Make this the new active or
    // pending value set depending on the configuration.
    if (requiresAdminAction)
    {
      pendingValues    = values;
      hasPendingValues = true;
    }
    else
    {
      activeValues     = values;
      pendingValues    = activeValues;
      hasPendingValues = false;

    }
  }


  /**
   * 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.
   */
  protected void setActiveValues(LinkedHashSet<AttributeValue> values)
  {
    activeValues = 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.
   *
   * @param  values  The set of pending values for this configuration attribute.
   */
  protected void setPendingValues(LinkedHashSet<AttributeValue> values)
  {
    pendingValues    = values;
    hasPendingValues = true;
  }


  /**
   * 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
   *                           attribute.
   */
  protected void addValues(List<AttributeValue> values)
         throws ConfigException
  {
    // If there are no values provided, then do nothing.
    if (values == null)
    {
      return;
    }

    int numValues = values.size();
    if (numValues == 0)
    {
      return;
    }


    // Make sure that the value limit will not be exceeded for a single-valued
    // attribute.
    if (! isMultiValued)
    {
      if ((numValues > 1) || (hasPendingValues && (pendingValues.size() > 0)) ||
          ((! hasPendingValues) && (activeValues.size() > 0)))
      {
        Message message = ERR_CONFIG_ATTR_ADD_VALUES_IS_SINGLE_VALUED.get(name);
        throw new ConfigException(message);
      }
    }


    // 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.
    LinkedHashSet<AttributeValue> tempValues;
    if (requiresAdminAction && hasPendingValues)
    {
      tempValues =
           new LinkedHashSet<AttributeValue>(pendingValues.size() + numValues);
      tempValues.addAll(pendingValues);
    }
    else
    {
      tempValues =
           new LinkedHashSet<AttributeValue>(activeValues.size() + numValues);
      tempValues.addAll(activeValues);
    }


    // 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.
    StringBuilder rejectReason = new StringBuilder();
    for (AttributeValue value : values)
    {
      if (tempValues.contains(value))
      {
        Message message = ERR_CONFIG_ATTR_ADD_VALUES_ALREADY_EXISTS.get(
            name, value.getValue().toString());
        throw new ConfigException(message);
      }

      if (! valueIsAcceptable(value, rejectReason))
      {
        Message message = ERR_CONFIG_ATTR_REJECTED_VALUE.get(
            value.getValue().toString(), name, rejectReason.toString());
        throw new ConfigException(message);
      }
    }


    // 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.
    if (requiresAdminAction)
    {
      pendingValues    = tempValues;
      hasPendingValues = true;
    }
    else
    {
      activeValues     = tempValues;
      pendingValues    = tempValues;
      hasPendingValues = false;
    }
  }


  /**
   * Attempts to remove the set of values from this configuration attribute.
   *
   * @param  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.
   */
  protected void removeValues(List<AttributeValue> values)
         throws ConfigException
  {
    // 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.
    LinkedHashSet<AttributeValue> tempValues;
    if (requiresAdminAction && hasPendingValues)
    {
      tempValues =
           new LinkedHashSet<AttributeValue>(pendingValues.size());
      tempValues.addAll(pendingValues);
    }
    else
    {
      tempValues =
           new LinkedHashSet<AttributeValue>(activeValues.size());
      tempValues.addAll(activeValues);
    }


    // 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
    // remove it.
    for (AttributeValue value : values)
    {
      if (! tempValues.remove(value))
      {
        Message message =
           ERR_CONFIG_ATTR_NO_SUCH_VALUE.get(name, value.getValue().toString());
        throw new ConfigException(message);
      }
    }


    // If this is a required attribute, then make sure that it will have at
    // least one value.
    if (isRequired && tempValues.isEmpty())
    {
      Message message = ERR_CONFIG_ATTR_IS_REQUIRED.get(name);
      throw new ConfigException(message);
    }


    // 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.
    if (requiresAdminAction)
    {
      pendingValues    = tempValues;
      hasPendingValues = true;
    }
    else
    {
      activeValues     = tempValues;
      pendingValues    = tempValues;
      hasPendingValues = false;
    }
  }


  /**
   * Removes all values from this configuration attribute.
   *
   * @throws  ConfigException  If this is a required attribute that must have at
   *                           least one value.
   */
  protected void removeAllValues()
         throws ConfigException
  {
    if (isRequired)
    {
      Message message = ERR_CONFIG_ATTR_IS_REQUIRED.get(name);
      throw new ConfigException(message);
    }


    if (requiresAdminAction)
    {
      if (pendingValues == null)
      {
        pendingValues = new LinkedHashSet<AttributeValue>();
      }
      else
      {
        pendingValues.clear();
      }

      hasPendingValues = true;
    }
    else
    {
      activeValues.clear();
      pendingValues = activeValues;
      hasPendingValues = false;
    }
  }


  /**
   * 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
   *                 attribute.
   */
  public void setInitialValues(LinkedHashSet<AttributeValue> values)
  {
    if (values == null)
    {
      values = new LinkedHashSet<AttributeValue>();
    }

    activeValues     = values;
    pendingValues    = values;
    hasPendingValues = false;
  }


  /**
   * 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.
   */
  public void applyPendingValues()
  {
    if (hasPendingValues)
    {
      activeValues     = pendingValues;
      hasPendingValues = false;
    }
  }


  /**
   * Converts the provided set of strings to a corresponding set of attribute
   * values.
   *
   * @param  valueStrings   The set of strings to be converted into attribute
   *                        values.
   * @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
   *                        undecodable values.
   *
   * @return  The set of attribute values converted from the provided strings.
   *
   * @throws  ConfigException  If an unrecoverable problem occurs while
   *                           performing the conversion.
   */
  public abstract LinkedHashSet<AttributeValue>
                       stringsToValues(List<String> valueStrings,
                                       boolean allowFailures)
         throws ConfigException;


  /**
   * 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>
   * method.
   *
   * @return  The string representations of the set of active values for this
   *          configuration attribute.
   */
  public abstract List<String> activeValuesToStrings();


  /**
   * 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>
   * method.
   *
   * @return  The string representations of the set of pending values for this
   *          configuration attribute, or <CODE>null</CODE> if there are no
   *          pending values.
   */
  public abstract List<String> pendingValuesToStrings();


  /**
   * 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
   *                           multiple values).
   */
  public abstract ConfigAttribute getConfigAttribute(List<Attribute>
                                                          attributeList)
         throws ConfigException;


  /**
   * 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.
   */
  public abstract javax.management.Attribute toJMXAttribute();

  /**
   * 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.
   */
  public abstract javax.management.Attribute toJMXAttributePending();


  /**
   * 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.
   *
   * @param  attributeList  The attribute list to which the JMX attribute(s)
   *                        should be added.
   */
  public abstract void toJMXAttribute(AttributeList attributeList);


  /**
   * 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
   *                            should be added.
   */
  public abstract void toJMXAttributeInfo(List<MBeanAttributeInfo>
                                               attributeInfoList);


  /**
   * Retrieves a JMX <CODE>MBeanParameterInfo</CODE> object that describes this
   * configuration attribute.
   *
   * @return  A JMX <CODE>MBeanParameterInfo</CODE> object that describes this
   *          configuration attribute.
   */
  public abstract MBeanParameterInfo toJMXParameterInfo();


  /**
   * 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
   *                           attribute.
   */
  public abstract void setValue(javax.management.Attribute jmxAttribute)
         throws ConfigException;


  /**
   * Creates a duplicate of this configuration attribute.
   *
   * @return  A duplicate of this configuration attribute.
   */
  public abstract ConfigAttribute duplicate();
}