PropertyMap.java

/*
Copyright (c) 2013 James Ahlborn

Licensed under the Apache 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.apache.org/licenses/LICENSE-2.0

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 com.healthmarketscience.jackcess;

import java.io.IOException;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;

/**
 * Map of properties for a database object.
 *
 * @author James Ahlborn
 * @usage _general_class_
 */
public interface PropertyMap extends Iterable<PropertyMap.Property>
{
  ////
  // database and summary properties
  public static final String ACCESS_VERSION_PROP = "AccessVersion";
  public static final String BUILD_PROP = "Build";
  public static final String PROJ_VER_PROP = "ProjVer";
  public static final String HAS_OFFLINE_LISTS_PROP = "HasOfflineLists";
  public static final String ANSI_QUERY_MODE_PROP = "ANSI Query Mode";
  public static final String AUTO_COMPACT_PROP = "Auto Compact";
  public static final String TRACK_NAME_AUTO_CORRECT_PROP =
    "Track Name AutoCorrect Info";
  public static final String PERFORM_NAME_AUTO_CORRECT_PROP =
    "Perform Name AutoCorrect";
  public static final String CHECK_TRUNCATED_NUM_FIELDS_PROP =
    "CheckTruncatedNumFields";
  public static final String PICTURE_STORAGE_FORMAT_PROP =
    "Picture Property Storage Format";
  public static final String THEME_RESOURCE_NAME_PROP = "Theme Resource Name";
  public static final String THEMED_FORM_CONTROLS_PROP = "Themed Form Controls";
  public static final String SHOW_DOCUMENT_TABS_PROP = "ShowDocumentTabs";
  public static final String USE_MDI_MODE_PROP = "UseMDIMode";
  public static final String WEB_DESIGN_MODE_PROP = "WebDesignMode";
  public static final String DESIGN_WITH_DATA_PROP = "DesignWithData";
  public static final String ALLOW_BUILT_IN_TOOLBARS_PROP =
    "AllowBuiltInToolbars";
  public static final String ALLOW_DATASHEET_SCHEMA_PROP =
    "AllowDatasheetSchema";
  public static final String ALLOW_FULL_MENUS_PROP = "AllowFullMenus";
  public static final String ALLOW_SHORTCUT_MENUS_PROP = "AllowShortcutMenus";
  public static final String ALLOW_SPECIAL_KEYS_PROP = "AllowSpecialKeys";
  public static final String ALLOW_TOOLBAR_CHANGES_PROP = "AllowToolbarChanges";
  public static final String START_UP_SHOW_DB_WINDOW_PROP =
    "StartUpShowDBWindow";
  public static final String START_UP_SHOW_STATUS_BAR_PROP =
    "StartUpShowStatusBar";
  public static final String USE_APP_ICON_FOR_FRM_RPT_PROP =
    "UseAppIconForFrmRpt";
  public static final String NAV_PANE_CATEGORY_PROP = "NavPane Category";
  public static final String NAV_PANE_CLOSED_PROP = "NavPane Closed";
  public static final String NAV_PANE_SORT_BY_PROP = "NavPane Sort By";
  public static final String NAV_PANE_VIEW_BY_PROP = "NavPane View By";
  public static final String NAV_PANE_WIDTH_PROP = "NavPane Width";
  public static final String NAV_PANE_SEARCH_BAR_PROP =
    "Show Navigation Pane Search Bar";
  public static final String SHOW_VALUES_LIMIT_PROP = "Show Values Limit";
  public static final String SHOW_VALUES_IN_INDEXED_PROP =
    "Show Values in Indexed";
  public static final String SHOW_VALUES_IN_NON_INDEXED_PROP =
    "Show Values in Non-Indexed";
  public static final String SHOW_VALUES_IN_REMOTE_PROP =
    "Show Values in Remote";
  public static final String REPLICATE_PROJECT_PROP = "ReplicateProject";
  public static final String TITLE_PROP = "Title";
  public static final String AUTHOR_PROP = "Author";
  public static final String COMPANY_PROP = "Company";

  ////
  // column properties
  public static final String DEFAULT_VALUE_PROP = "DefaultValue";
  public static final String REQUIRED_PROP = "Required";
  public static final String ALLOW_ZERO_LEN_PROP = "AllowZeroLength";
  public static final String DECIMAL_PLACES_PROP = "DecimalPlaces";
  public static final String FORMAT_PROP = "Format";
  public static final String INPUT_MASK_PROP = "InputMask";
  public static final String CAPTION_PROP = "Caption";
  public static final String VALIDATION_RULE_PROP = "ValidationRule";
  public static final String VALIDATION_TEXT_PROP = "ValidationText";
  public static final String GUID_PROP = "GUID";
  public static final String DESCRIPTION_PROP = "Description";
  public static final String RESULT_TYPE_PROP = "ResultType";
  public static final String EXPRESSION_PROP = "Expression";
  public static final String ALLOW_MULTI_VALUE_PROP = "AllowMultipleValues";
  public static final String ROW_SOURCE_TYPE_PROP = "RowSourceType";
  public static final String ROW_SOURCE_PROP = "RowSource";
  public static final String BOUND_COLUMN_PROP = "BoundColumn";
  public static final String COLUMN_COUNT_PROP = "ColumnCount";
  public static final String COLUMN_WIDTHS_PROP = "ColumnWidths";
  public static final String LIMIT_TO_LIST_PROP = "LimitToList";
  public static final String DISPLAY_CONTROL_PROP = "DisplayControl";
  public static final String TEXT_FORMAT_PROP = "TextFormat";
  public static final String IME_MODE_PROP = "IMEMode";
  public static final String IME_SENTENCE_MODE_PROP = "IMESentenceMode";
  public static final String UNICODE_COMPRESSION_PROP = "UnicodeCompression";
  public static final String APPEND_ONLY_PROP = "AppendOnly";
  public static final String TEXT_ALIGN_PROP = "TextAlign";
  public static final String AGGREGATE_TYPE_PROP = "AggregateType";
  public static final String CURRENCY_LCID_PROP = "CurrencyLCID";
  public static final String COLUMN_HIDDEN_PROP = "ColumnHidden";
  public static final String COLUMN_ORDER_PROP = "ColumnOrder";
  public static final String COLUMN_WIDTH_PROP = "ColumnWidth";

  ////
  // table and query properties
  public static final String NAME_MAP_PROP = "NameMap";
  public static final String DEFAULT_VIEW_PROP = "DefaultView";
  public static final String ORIENTATION_PROP = "Orientation";
  public static final String ORDER_BY_ON_PROP = "OrderByOn";
  public static final String ORDER_BY_ON_LOAD_PROP = "OrderByOnLoad";
  public static final String FILTER_ON_LOAD_PROP = "FilterOnLoad";
  public static final String TOTALS_ROW_PROP = "TotalsRow";
  public static final String HIDE_NEW_FIELD_PROP = "HideNewField";
  public static final String PUBLISH_TO_WEB_PROP = "PublishToWeb";
  public static final String READ_ONLY_WHEN_DISCONNECTED_PROP =
    "ReadOnlyWhenDisconnected";
  public static final String DISPLAY_VIEWS_ON_SHAREPOINT_PROP =
    "DisplayViewsOnSharePointSite";
  public static final String BACK_TINT_PROP = "BackTint";
  public static final String BACK_SHADE_PROP = "BackShade";
  public static final String ALTERNATE_BACK_TINT_PROP = "AlternateBackTint";
  public static final String ALTERNATE_BACK_SHADE_PROP = "AlternateBackShade";
  public static final String ALTERNATE_BACK_THEME_COLOR_INDEX_PROP =
    "AlternateBackThemeColorIndex";
  public static final String DATASHEET_FORE_THEME_COLOR_INDEX_PROP =
    "DatasheetForeThemeColorIndex";
  public static final String DATASHEET_GRIDLINES_THEME_COLOR_INDEX_PROP =
    "DatasheetGridlinesThemeColorIndex";
  public static final String THEME_FONT_INDEX_PROP = "ThemeFontIndex";

  public static final String QUERY_NAME_MAP_PROP = "DOL";
  public static final String ODBC_TIMEOUT_PROP = "ODBCTimeout";
  public static final String RECORD_LOCKS_PROP = "RecordLocks";
  public static final String RECORDSET_TYPE_PROP = "RecordsetType";
  public static final String USE_TRANSACTION_PROP = "UseTransaction";
  public static final String FAIL_ON_ERROR_PROP = "FailOnError";
  public static final String LOG_MESSAGES_PROP = "LogMessages";


  public String getName();

  public int getSize();

  public boolean isEmpty();

  /**
   * @return the property with the given name, if any
   */
  public Property get(String name);

  /**
   * @return the value of the property with the given name, if any
   */
  public Object getValue(String name);

  /**
   * @return the value of the property with the given name, if any, otherwise
   *         the given defaultValue
   */
  public Object getValue(String name, Object defaultValue);

  /**
   * Creates a new (or updates an existing) property in the map.  Attempts to
   * determine the type of the property based on the name and value (the
   * property names listed above have their types builtin, otherwise the type
   * of the value is used).
   * <p>
   * Note, this change will not be persisted until the {@link #save} method
   * has been called.
   *
   * @return the newly created (or updated) property
   * @throws IllegalArgumentException if the type of the property could not be
   *                                  determined automatically
   */
  public Property put(String name, Object value);

  /**
   * Creates a new (or updates an existing) property in the map.
   * <p>
   * Note, this change will not be persisted until the {@link #save} method
   * has been called.
   *
   * @return the newly created (or updated) property
   */
  public Property put(String name, DataType type, Object value);

  /**
   * Creates a new (or updates an existing) property in the map.
   * <p>
   * Note, this change will not be persisted until the {@link #save} method
   * has been called.
   *
   * @return the newly created (or updated) property
   */
  public Property put(String name, DataType type, Object value, boolean isDdl);

  /**
   * Creates a new (or updates an existing) property in the map, setting both
   * of the flag bits ms access defines.
   * <p>
   * Note, this change will not be persisted until the {@link #save} method
   * has been called.
   *
   * @return the newly created (or updated) property
   */
  public Property put(String name, DataType type, Object value, boolean isDdl,
                      boolean isSkipHandler);

  /**
   * Puts all the given properties into this map.
   *
   * @param props the properties to put into this map ({@code null} is
   *              tolerated and ignored).
   */
  public void putAll(Iterable<? extends Property> props);

  /**
   * Removes the property with the given name
   *
   * @return the removed property, or {@code null} if none found
   */
  public Property remove(String name);

  /**
   * Saves the current state of this map.
   */
  public void save() throws IOException;

  /**
   * @return a Stream using the default Iterator.
   */
  default public Stream<PropertyMap.Property> stream() {
    return StreamSupport.stream(spliterator(), false);
  }

  /**
   * Info about a property defined in a PropertyMap.
   */
  public interface Property
  {
    public String getName();

    public DataType getType();

    /**
     * Whether or not this property is a DDL object.  If {@code true}, users
     * can't change or delete the property in access without the dbSecWriteDef
     * permission.  Additionally, certain properties must be flagged correctly
     * or ms access may not recognize them correctly.
     */
    public boolean isDdl();

    /**
     * Whether or not ms access stores this property without running the
     * handler bound to the property name, so that writing the property
     * records a state rather than bringing it about.  The bit is one ms
     * access sets on its own account, and no DAO call produces it.
     */
    public boolean isSkipHandler();

    public Object getValue();

    /**
     * Sets the new value for this property.
     * <p>
     * Note, this change will not be persisted until the {@link
     * PropertyMap#save} method has been called.
     */
    public void setValue(Object newValue);
  }

  /**
   * Interface for enums which can be used as property values.
   */
  public interface EnumValue
  {
    /**
     * @return the property value which should be stored in the db
     */
    public Object getValue();
  }

  /**
   * Enum value constants for the DisplayControl property
   */
  public enum DisplayControl implements EnumValue
  {
    BOUND_OBJECT_FRAME(108),
    CHECK_BOX(106),
    COMBO_BOX(111),
    COMMAND_BUTTON(104),
    CUSTOM_CONTROL(119),
    EMPTY_CELL(127),
    IMAGE(103),
    LABEL(100),
    LINE(102),
    LIST_BOX(110),
    NAVIGATION_BUTTON(130),
    NAVIGATION_CONTROL(129),
    OBJECT_FRAME(114),
    OPTION_BUTTON(105),
    OPTION_GROUP(107),
    PAGE(124),
    PAGE_BREAK(118),
    RECTANGLE(101),
    SUB_FORM(112),
    TAB_CTL(123),
    TEXT_BOX(109),
    TOGGLE_BUTTON(122),
    WEB_BROWSER(128);

    private final Short _value;

    private DisplayControl(int value) {
      _value = (short)value;
    }

    @Override
    public Short getValue() {
      return _value;
    }

    @Override
    public String toString() {
      return name() + "[" + _value + "]";
    }
  }

  /**
   * Enum value constants for the TextFormat property
   */
  public enum TextFormat implements EnumValue
  {
    HTMLRICHTEXT(1),
    PLAIN(0);

    private final Byte _value;

    private TextFormat(int value) {
      _value = (byte)value;
    }

    @Override
    public Byte getValue() {
      return _value;
    }

    @Override
    public String toString() {
      return name() + "[" + _value + "]";
    }
  }

  /**
   * Enum value constants for the IMEMode property
   */
  public enum IMEMode implements EnumValue
  {
    NOCONTROL(0),
    ON(1),
    OFF(2),
    DISABLE(3),
    HIRAGANA(4),
    KATAKANA(5),
    KATAKANAHALF(6),
    ALPHAFULL(7),
    ALPHA(8),
    HANGULFULL(9),
    HANGUL(10);

    private final Byte _value;

    private IMEMode(int value) {
      _value = (byte)value;
    }

    @Override
    public Byte getValue() {
      return _value;
    }

    @Override
    public String toString() {
      return name() + "[" + _value + "]";
    }
  }

  /**
   * Enum value constants for the IMESentenceMode property
   */
  public enum IMESentenceMode implements EnumValue
  {
    NORMAL(0),
    PLURAL(1),
    SPEAKING(2),
    NONE(3);

    private final Byte _value;

    private IMESentenceMode(int value) {
      _value = (byte)value;
    }

    @Override
    public Byte getValue() {
      return _value;
    }

    @Override
    public String toString() {
      return name() + "[" + _value + "]";
    }
  }

}