/**
    * Copyright 2005-2014 The Kuali Foundation
    *
    * Licensed under the Educational Community License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    *
    * http://www.opensource.org/licenses/ecl2.php
    *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.kuali.rice.krad.uif.field;
  
  import java.beans.PropertyEditor;
  import java.util.List;
  
  import org.kuali.rice.krad.datadictionary.AttributeDefinition;
  import org.kuali.rice.krad.datadictionary.mask.MaskFormatter;
  import org.kuali.rice.krad.datadictionary.validator.ValidationTrace;
  import org.kuali.rice.krad.uif.component.ComponentSecurity;
  import org.kuali.rice.krad.uif.component.DataBinding;
  import org.kuali.rice.krad.uif.widget.Helpable;
  import org.kuali.rice.krad.uif.widget.Inquiry;
  import org.kuali.rice.krad.valuefinder.ValueFinder;
  
  /**
   * Component interface for data fields. 
   * 
   * @author Kuali Rice Team (rice.collab@kuali.org)
   */
  public interface DataField extends DataBinding, Helpable, Field {
  
      /**
       * Defaults the properties of the <code>DataField</code> to the
       * corresponding properties of its <code>AttributeDefinition</code>
       * retrieved from the dictionary (if such an entry exists). If the field
       * already contains a value for a property, the definitions value is not
       * used.
       *
       * @param attributeDefinition AttributeDefinition instance the property values should be
       * copied from
       */
      void copyFromAttributeDefinition(AttributeDefinition attributeDefinition);
  
      /**
       * Indicates whether the data field instance allows input, subclasses should override and set to
       * true if input is allowed
       *
       * @return true if input is allowed, false if read only
       */
      boolean isInputAllowed();
  
      /**
       * Setter for the component's property name
       *
       * @param propertyName
       */
      void setPropertyName(String propertyName);
  
      /**
       * Performs formatting of the field value for display and then converting the value back to its
       * expected type from a string
       *
       * <p>
       * Note property editors exist and are already registered for the basic Java types and the
       * common Kuali types such as [@link KualiDecimal}. Registration with this property is only
       * needed for custom property editors
       * </p>
       *
       * @return PropertyEditor property editor instance to use for this field
       */
      PropertyEditor getPropertyEditor();
  
      /**
       * Setter for the custom property editor to use for the field
       *
       * @param propertyEditor
       */
      void setPropertyEditor(PropertyEditor propertyEditor);
  
      /**
       * Convenience setter for configuring a property editor by class
       *
       * @param propertyEditorClass
       */
      void setPropertyEditorClass(Class<? extends PropertyEditor> propertyEditorClass);
  
      /**
       * Returns the full binding path (the path used in the name attribute of the input).
       * This differs from propertyName in that it uses BindingInfo to determine the path.
       *
       * @return full binding path name
       */
      String getName();
  
     /**
      * Name of the attribute within the data dictionary the attribute field is
      * associated with
      *
      * <p>
      * During the initialize phase for the <code>View</code>, properties for
      * attribute fields are defaulted from a corresponding
      * <code>AttributeDefinition</code> in the data dictionary. Based on the
      * propertyName and parent object class the framework attempts will
      * determine the attribute definition that is associated with the field and
      * set this property. However this property can also be set in the fields
      * configuration to use another dictionary attribute.
      * </p>
      *
      * <p>
      * The attribute name is used along with the dictionary object entry to find
      * the <code>AttributeDefinition</code>
      * </p>
      *
      * @return attribute name
      */
     String getDictionaryAttributeName();
 
     /**
      * Setter for the dictionary attribute name
      *
      * @param dictionaryAttributeName
      */
     void setDictionaryAttributeName(String dictionaryAttributeName);
 
     /**
      * Object entry name in the data dictionary the associated attribute is
      * apart of
      *
      * <p>
      * During the initialize phase for the <code>View</code>, properties for
      * attribute fields are defaulted from a corresponding
      * <code>AttributeDefinition</code> in the data dictionary. Based on the
      * parent object class the framework will determine the object entry for the
      * associated attribute. However the object entry can be set in the field's
      * configuration to use another object entry for the attribute
      * </p>
      *
      * <p>
      * The attribute name is used along with the dictionary object entry to find
      * the <code>AttributeDefinition</code>
      * </p>
      *
      * @return String
      */
     String getDictionaryObjectEntry();
 
     /**
      * Setter for the dictionary object entry
      *
      * @param dictionaryObjectEntry
      */
     void setDictionaryObjectEntry(String dictionaryObjectEntry);
 
     /**
      * Default value for the model property the field points to
      *
      * <p>
      * When a new <code>View</code> instance is requested, the corresponding
      * model will be newly created. During this initialization process the value
      * for the model property will be set to the given default value, if it was null.
      * This will only work on properties which can be determined to be null.
      * Therefore a String property with an empty string value will
      * not be ovewritten with the defaultValue set here.
      * </p>
      *
      * <p>
      * In addition, int, boolean, and other primitive types
      * will not use this default value because they inherently have a value in Java (0 for int, false for boolean, etc).
      * To use such types either using a primitive wrapper type (Integer, Boolean, etc) so an unset variable can
      * be determined to be null, or explicitly set the default value on the form/object itself for these types and
      * not through this property.
      * </p>
      *
      * @return default value
      */
     Object getDefaultValue();
 
     /**
      * Setter for the fields default value
      *
      * @param defaultValue
      */
     void setDefaultValue(Object defaultValue);
 
     /**
      * Gives Class that should be invoked to produce the default value for the
      * field
      *
      * @return default value finder class
      */
     Class<? extends ValueFinder> getDefaultValueFinderClass();
 
     /**
      * Setter for the default value finder class
      *
      * @param defaultValueFinderClass
      */
     void setDefaultValueFinderClass(Class<? extends ValueFinder> defaultValueFinderClass);
 
     /**
      * Array of default values for the model property the field points to
      *
      * <p>
      * When a new <code>View</code> instance is requested, the corresponding
      * model will be newly created. During this initialization process the value
      * for the model property will be set to the given default values (if set)
      * </p>
      *
      * @return default value
      */
     Object[] getDefaultValues();
 
     /**
      * Setter for the fields default values
      *
      * @param defaultValues
      */
     void setDefaultValues(Object[] defaultValues);
 
     String getForcedValue();
 
     void setForcedValue(String forcedValue);
 
     /**
      * Summary help text for the field
      *
      * @return summary help text
      */
     String getHelpSummary();
 
     /**
      * Setter for the summary help text
      *
      * @param helpSummary
      */
     void setHelpSummary(String helpSummary);
 
     /**
      * Data Field Security object that indicates what authorization (permissions) exist for the field
      *
      * @return DataFieldSecurity instance
      */
     DataFieldSecurity getDataFieldSecurity();
 
     /**
      * Override to assert a {@link DataFieldSecurity} instance is set
      *
      * @param componentSecurity instance of DataFieldSecurity
      */
     void setComponentSecurity(ComponentSecurity componentSecurity);
 
     /**
      * Indicates the field should be read-only but also a hidden should be generated for the field
      *
      * <p>
      * Useful for when a value is just displayed but is needed by script
      * </p>
      *
      * @return true if field should be readOnly hidden, false if not
      */
     boolean isAddHiddenWhenReadOnly();
 
     /**
      * Setter for the read-only hidden indicator
      *
      * @param addHiddenWhenReadOnly
      */
     void setAddHiddenWhenReadOnly(boolean addHiddenWhenReadOnly);
 
     /**
      * Inquiry widget for the field
      *
      * <p>
      * The inquiry widget will render a link for the field value when read-only
      * that points to the associated inquiry view for the field. The inquiry can
      * be configured to point to a certain <code>InquiryView</code>, or the
      * framework will attempt to associate the field with a inquiry based on its
      * metadata (in particular its relationships in the model)
      * </p>
      *
      * @return Inquiry field inquiry
      */
     Inquiry getInquiry();
 
     /**
      * Setter for the inquiry widget
      *
      * @param inquiry
      */
     void setInquiry(Inquiry inquiry);
 
     /**
      * Indicates whether inquiries should be automatically set when a relationship for the field's property
      * is found
      *
      * <p>
      * Note this only applies when the {@link #getInquiry()} widget has not been configured (is null)
      * and is set to true by default
      * </p>
      *
      * @return true if auto inquiries are enabled, false if not
      */
     boolean isEnableAutoInquiry();
 
     /**
      * Setter for enabling automatic inquiries
      *
      * @param enableAutoInquiry
      */
     void setEnableAutoInquiry(boolean enableAutoInquiry);
 
     /**
      * When true, render the info message span which contains can contain additional information
      * about the field (used by Field Query functionality)
      *
      * @return true if the span will be rendered, false otherwise
      */
     boolean isRenderInfoMessageSpan();
 
     /**
      * @see org.kuali.rice.krad.uif.field.DataField#isRenderInfoMessageSpan()
      * @param renderInfoMessageSpan
      */
     void setRenderInfoMessageSpan(boolean renderInfoMessageSpan);
 
     /**
      * When true, render the marker icon span to show icons related to the field (used by CompareFieldCreateModifier on
      * maintenance documetnts to mark editted fields)
      *
      * @return true if the the marker icon span will be rendered, false otherwise
      */
     boolean isRenderMarkerIconSpan();
 
     /**
      * @see org.kuali.rice.krad.uif.field.DataField#isRenderMarkerIconSpan()
      * @param renderMarkerIconSpan
      */
     void setRenderMarkerIconSpan(boolean renderMarkerIconSpan);
 
     /**
      * Additional display attribute name, which will be displayed next to the actual field value
      * when the field is readonly with hyphen in between like PropertyValue - AdditionalPropertyValue
      *
      * @param readOnlyDisplaySuffixPropertyName name of the additional display property
      */
     void setReadOnlyDisplaySuffixPropertyName(String readOnlyDisplaySuffixPropertyName);
 
     /**
      * Returns the additional display attribute name to be displayed when the field is readonly
      *
      * @return additional display attribute name
      */
     String getReadOnlyDisplaySuffixPropertyName();
 
     /**
      * Sets the alternate display attribute name to be displayed when the field is readonly.
      * This properties value will be displayed instead of actual fields value when the field is readonly.
      *
      * @param readOnlyDisplayReplacementPropertyName alternate display property name
      */
     void setReadOnlyDisplayReplacementPropertyName(String readOnlyDisplayReplacementPropertyName);
 
     /**
      * Returns the alternate display attribute name to be displayed when the field is readonly.
      *
      * @return alternate Display Property Name
      */
     String getReadOnlyDisplayReplacementPropertyName();
 
     /**
      * Returns the alternate display value
      *
      * @return the alternate display value set for this field
      */
     String getReadOnlyDisplayReplacement();
 
     /**
      * Setter for the alternative display value
      *
      * @param value
      */
     void setReadOnlyDisplayReplacement(String value);
 
     /**
      * Returns the additional display value.
      *
      * @return the additional display value set for this field
      */
     String getReadOnlyDisplaySuffix();
 
     /**
      * Setter for the additional display value
      *
      * @param value
      */
     void setReadOnlyDisplaySuffix(String value);
 
     /**
      * Gets the readOnlyListDisplayType.
      *
      * <p>When this is not set, the list will default to the delimited list display with a default of comma and space
      * (", ") - if readOnlyListDelimiter is not set as well.  The type can be set as the following:
      * <ul>
      * <li>"DELIMITED" - list will be output with delimiters between each item defined by readOnlyListDelimiter</li>
      * <li>"BREAK" - list will be output with breaks between each item</li>
      * <li>"OL" - list will be output in ordered list format (numbered)</li>
      * <li>"UL" - list will be output in unordered list format (bulleted)</li>
      * </ul>
      * </p>
      *
      * @return the display type to use
      */
     String getReadOnlyListDisplayType();
 
     /**
      * Set the readOnlyListDisplayType
      *
      * @param readOnlyListDisplayType
      */
     void setReadOnlyListDisplayType(String readOnlyListDisplayType);
 
     /**
      * The readOnlyListDelimiter is used to set the delimiter used when "DELIMITED" type is set for
      * readOnlyListDisplayType
      *
      * @return the delimiter to use in readOnly list output with "DELIMITED" type set
      */
     String getReadOnlyListDelimiter();
 
     /**
      * Set the readOnlyListDelimiter
      *
      * @param readOnlyListDelimiter
      */
     void setReadOnlyListDelimiter(String readOnlyListDelimiter);
 
     /**
      * Indicates whether the value for the field should be masked (or partially masked) on display
      *
      * <p>
      * If set to true, the field value will be masked by applying the configured {@link #getMaskFormatter()}
      * </p>
      *
      * <p>
      * If a KIM permission exists that should be checked to determine whether the value should be masked or not,
      * this value should not be set but instead the mask or partialMask property on {@link #getComponentSecurity()}
      * should be set to true. This indicates there is a mask permission that should be consulted. If the user
      * does not have the permission, this flag will be set to true by the framework and the value masked using
      * the mask formatter configured on the security object
      * </p>
      *
      * @return true if the field value should be masked, false if not
      */
     boolean isApplyMask();
 
     /**
      * Setter for the apply value mask flag
      *
      * @param applyMask
      */
     void setApplyMask(boolean applyMask);
 
     /**
      * MaskFormatter instance that will be used to mask the field value when {@link #isApplyMask()} is true
      *
      * <p>
      * Note in cases where the mask is applied due to security (KIM permissions), the mask or partial mask formatter
      * configured on {@link #getComponentSecurity()} will be used instead of this mask formatter
      * </p>
      *
      * @return MaskFormatter instance
      */
     MaskFormatter getMaskFormatter();
 
     /**
      * Setter for the MaskFormatter instance to apply when the value is masked
      *
      * @param maskFormatter
      */
     void setMaskFormatter(MaskFormatter maskFormatter);
 
     /**
      * Allows specifying hidden property names without having to specify as a
      * field in the group config (that might impact layout)
      *
      * @return hidden property names
      */
     List<String> getAdditionalHiddenPropertyNames();
 
     /**
      * Setter for the hidden property names
      *
      * @param additionalHiddenPropertyNames
      */
     void setAdditionalHiddenPropertyNames(List<String> additionalHiddenPropertyNames);
 
     /**
      * List of property names whose values should be displayed read-only under this field
      *
      * <p>
      * In the attribute field template for each information property name given its values is
      * outputted read-only. Informational property values can also be updated dynamically with
      * the use of field attribute query
      * </p>
      *
      * <p>
      * Simple property names can be given if the property has the same binding parent as this
      * field, in which case the binding path will be adjusted by the framework. If the property
      * names starts with org.kuali.rice.krad.uif.UifConstants#NO_BIND_ADJUST_PREFIX, no binding
      * prefix will be added.
      * </p>
      *
      * @return informational property names
      */
     List<String> getPropertyNamesForAdditionalDisplay();
 
     /**
      * Setter for the list of informational property names
      *
      * @param propertyNamesForAdditionalDisplay
      */
     void setPropertyNamesForAdditionalDisplay(List<String> propertyNamesForAdditionalDisplay);
 
     /**
      * Sets HTML escaping for this property value. HTML escaping will be handled in alternate and additional fields
      * also.
      */
     void setEscapeHtmlInPropertyValue(boolean escapeHtmlInPropertyValue);
 
     /**
      * Returns true if HTML escape allowed for this field
      *
      * @return true if escaping allowed
      */
     boolean isEscapeHtmlInPropertyValue();
 
     /**
      * Returns true if this field is of type {@code TextAreaControl}.
      *
      * <p>
      * Used to preserve text formatting in a textarea when the view
      * is readOnly by enclosing the text in a </pre> tag.
      * </p>
      *
      * @return true if the field is of type {@code TextAreaControl}
      */
     boolean isMultiLineReadOnlyDisplay();
 
     /**
      * Setter for multiLineReadOnlyDisplay
      *
      * @param multiLineReadOnlyDisplay
      */
     void setMultiLineReadOnlyDisplay(boolean multiLineReadOnlyDisplay);
 
     /**
      * Indicates whether the value for the field is secure.
      *
      * <p>
      * A value will be secured if masking has been applied (by configuration or a failed KIM permission) or the field
      * has been marked as hidden due to a required KIM permission check failing.
      * </p>
      *
      * @return true if value is secure, false if not
      */
     boolean hasSecureValue();
 
     boolean isRenderFieldset();
 
     /**
      * @see org.kuali.rice.krad.uif.component.Component#completeValidation
      */
     void completeValidation(ValidationTrace tracer);
 
 }