Package se.conciliate.extensions.attribute

Interface RefinementElement

public interface RefinementElement
A refinement element contains the actual meta data that a refinement has. Each "unit" of meta data corresponds to an element. For example, a refinement that describes a number with a max value of 20 and a min value of 10 has 2 units of metadata and thus 2 refinement elements.
To understand a refinement element, think of it as a table of values. A refinement element has a dynamic number of rows, the current number of rows being expressed by getRowSize(). It also has a static number of columns expressed by getColumnSize(). If a client can add more rows to the element, canAdd() returns true and add() will append a new row with default values set.
Most implementations will likely be 1 column wide with 1 row, where the number of rows cannot increase (nor decrease). This is controlled by canAdd and canRemove.
To illustrate why this is not always enough, consider for example a data type called Date. A date can be displayed in a number of different formats. The default format might be "mm-dd-yyyy", so the refinement returns this for getValueAt(0, 0). Now, when a client asks canAdd(), the refinement returns true and when add() is called it adds a new row with the same default value. A user can now overwrite the defaults saying that the allowed date formats should be, say, "dd-mm-yyyy" and "yy-mm-dd". When displayed to a user, the refinement might be rendered (different views may do differently!) as:
Example
Format 1: mm-dd-yyyy
Format 2: yy-mm-dd
This is explains why rows can be added. Columns can't be added, but some data types might contain "rows" that are key-value pairs or even a list of values. As an example, think of a data type called Option where the user can create its own drop-down menu. The user will now want to add a label that is connected to a value. The refinement to describe this would look like:
Example
Label: RedValue: 0
Label: GreenValue: 1
This would be a refinement currently having 2 rows (that can grow) where each row always has 2 columns (since columns are static). The first column has the name "Label" and the second column the name "Value". On the first row, the first column has the value "Red" and the second column the value "0".
Author:
Per-Erik

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    RefinementElement.ColumnMapper
     
    static enum 
    RefinementElement.Type
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add()
    Adds default values at the last row.
    boolean
    canAdd()
    Returns true if a new row can be added to this element, false otherwise.
    boolean
    canRemoveAt(int row)
    Returns true if the values at the given row can be removed, false otherwise.
    boolean
    canReorder()
    Returns true if the rows of this element can be reordered, false otherwise
    boolean
    canSetAt(int row, int column, String value, boolean isNew)
    Returns true if the given value can be set at the given row and index.
    RefinementElement.ColumnMapper
    dependencyMapper(String hidden, String visible)
    Returns the function mapping values from the visible column to the hidden column or null if no mapping exists or if hidden isn't a hidden column or if hidden isn't a mapping of the visible column.
    String
    getCause(int row, int column, String value, boolean isNew, Locale locale)
    Returns the cause of a failure if canSetAt(index, value) returns false.
    String
    getColumnID(int column)
    Returns a "refinement unique" id of the column at the given index.
    int
    getColumnIndex(String id)
    Returns the column index of the column with the given id.
    String
    getColumnName(int column, Locale locale)
    Returns the name of the column at the given index in the given locale.
    int
    getColumnSize()
    Returns the number of columns that this element has.
    String
    getDescription(Locale locale)
    Returns the description of this element in the given locale.
    String
    getID()
    Returns the "refinement unique" id of this element.
    List<RefinementOption>
    getOptions(int column)
    Returns a list of options for the given column.
    String
    getRemoveHint(int row)
    Returns a string that lets the user identify which row is about to be removed.
    int
    getRowSize()
    Returns the number of rows that this element currently has.
    RefinementElement.Type
    getType(int column)
    Returns the raw type of the column at the given index.
    String
    getValueAt(int row, int column)
    Returns the value at the specified row and column.
    Optional<String>
    hasDependent(String visible)
    Returns the column id of the hidden column that the given visible column has as its dependent.
    Optional<String>
    isDependent(String hidden)
    If the given columnID is hidden, returns the column id that it depends on, otherwise returns empty (if hidden is not a valid column id or if it is not a hidden column).
    void
    remove(int row)
    Removes the values (columns) at the specified row.
    void
    setRowOrder(int currentRow, int newRow)
    Sets the row at index currentRow to the index newRow if canReorder returns true.
    void
    setValueAt(int row, int column, String value, boolean isNew)
    Sets the specified value at the specified row and column.

  • Method Details

    • getType

      RefinementElement.Type getType(int column)
      Returns the raw type of the column at the given index. The column parameter must be in the range 0 <= column < getColumnSize() or the result of this method is undefined.
      Parameters:
      column - The column that the raw type should be returned for.
      Returns:
      The raw type of the column at the given index.

    • getColumnName

      String getColumnName(int column, Locale locale)
      Returns the name of the column at the given index in the given locale. If no name is available in the given locale, a default name is returned. The column parameter must be in the range 0 <= column < getColumnSize() or the result of this method is undefined.
      Parameters:
      column - The column to return the name for.
      locale - The locale to return a name in.
      Returns:
      The name of the given column in the given locale.

    • getID

      String getID()
      Returns the "refinement unique" id of this element.
      Returns:
      The "refinement unique" id of this element.

    • getColumnID

      String getColumnID(int column)
      Returns a "refinement unique" id of the column at the given index. The column parameter must be in the range 0 <= column < getColumnSize() or the result of this method is undefined.
      Parameters:
      column - The column whose id is sought.
      Returns:
      An id for the given column where the id is unique for this refinement.

    • getColumnIndex

      int getColumnIndex(String id)
      Returns the column index of the column with the given id.
      Parameters:
      id - The id of the column
      Returns:
      The index of the column or -1 if no such column exists.

    • getDescription

      String getDescription(Locale locale)
      Returns the description of this element in the given locale. If no description is available in the given locale, a default description is returned.
      Parameters:
      locale - The locale to return a description in.
      Returns:
      The description of this element in the given locale.

    • getRowSize

      int getRowSize()
      Returns the number of rows that this element currently has.
      Returns:
      The number of rows that this element currently has.

    • getColumnSize

      int getColumnSize()
      Returns the number of columns that this element has.
      Returns:
      The number of columns that this element has.

    • getValueAt

      String getValueAt(int row, int column)
      Returns the value at the specified row and column. If the row or column is out of bounds, the result is undefined.
      Parameters:
      row - The row.
      column - The column.
      Returns:
      The value at the specified row and column.

    • getOptions

      List<RefinementOption> getOptions(int column)
      Returns a list of options for the given column. A list of options will be used to let a user pick among the given options instead of freely setting a value an that cell. An empty list indicates that the user can input anything to the cell as long as canSetAt returns true for the specific row. Note that no row parameter is used since the options cannot be different on different rows.
      Note: All values of the refinement options must be unique in the list. That is, no two refinement options in the list may have the same value as returned from getValue().
      Parameters:
      column - The column where the cell is that will show the options.
      Returns:
      A list of options (possibly empty to indicate free input).

    • remove

      void remove(int row)
      Removes the values (columns) at the specified row. If the row is out of bounds, the result is undefined. If canRemoveAt(row) returns false, the result is undefined.
      Parameters:
      row - The row.

    • add

      void add()
      Adds default values at the last row. If canAdd returns false, the result is undefined. If one or more columns are dependent on any other columns in the row, those columns also get the appropriate default values.

    • setValueAt

      void setValueAt(int row, int column, String value, boolean isNew)
      Sets the specified value at the specified row and column. The result is undefined if canSetAt(int, int, java.lang.String, boolean) canSetAt returns false for the given parameters. If row or column are out of bounds, the results are undefined.
      Parameters:
      row - The row.
      column - The column
      value - The value to set at the given row and column.
      isNew - True if the row is a newly added row that has yet to be persisted. Note that if the row is new (as in, "not yet persisted"), so are the column and value.

    • getCause

      String getCause(int row, int column, String value, boolean isNew, Locale locale)
      Returns the cause of a failure if canSetAt(index, value) returns false. If canSetAt(index, value) returns true, an empty string is returned. The cause of the failure will be localized to the given locale if such localization is available. Otherwise the returned string will contain a default error description. If row or column are out of bounds, the results are undefined.
      Parameters:
      row - The row where the value would be set.
      column - The column where the value would be set.
      value - The value to set.
      isNew - True if the row is a newly added row that has yet to be persisted. Note that if the row is new (as in, "not yet persisted"), so are the column and value.
      locale - The local in which the cause should be returned.
      Returns:
      An empty string if the given value can be set at the row and column or an error message explaining why the value cannot be set, localized in a best-effort manner.

    • canSetAt

      boolean canSetAt(int row, int column, String value, boolean isNew)
      Returns true if the given value can be set at the given row and index. If the index is out of bounds, the behaviour of this method is undefined.
      Parameters:
      row - The row to set the value at.
      column - The column to set the value at.
      value - The value to set.
      isNew - True if the row is a newly added row that has yet to be persisted. Note that if the row is new (as in, "not yet persisted"), so are the column and value.
      Returns:
      True if the given value can be set at the given row and column, false otherwise.

    • canAdd

      boolean canAdd()
      Returns true if a new row can be added to this element, false otherwise.
      Returns:
      True if a new row can be added to this element, false otherwise.

    • canRemoveAt

      boolean canRemoveAt(int row)
      Returns true if the values at the given row can be removed, false otherwise.
      Parameters:
      row - The row to remove.
      Returns:
      True if the values at the given row can be removed, false otherwise.

    • getRemoveHint

      String getRemoveHint(int row)
      Returns a string that lets the user identify which row is about to be removed. For RefinementElements with only one column, this will typically be the value returned by getValueAt(row, 0). The returned value is used to display a warning message similar to "Do you really want to remove %s" where %s is the result of invoking this method.
      This method may not return null.
      If canRemoveAt(row) returns false, this method throws IllegalArgumentException.
      Parameters:
      row - The row to get a remove hint for.
      Returns:
      see method description.
      Throws:
      IllegalArgumentException - if canRemoveAt(row) returns false.
      IndexOutOfBoundsException - if row < 0 || row >= getRowSize().

    • canReorder

      boolean canReorder()
      Returns true if the rows of this element can be reordered, false otherwise
      Returns:
      true if the rows of this element can be reordered, false otherwise

    • setRowOrder

      void setRowOrder(int currentRow, int newRow)
      Sets the row at index currentRow to the index newRow if canReorder returns true. If canReorder returns false, then this does nothing. If any of the indices are out of bounds (index < 0 || index >= getRowSize()) and IndexOutOfBoundsException is thrown. For example, if an element with 4 rows looking like
      1. A
      2. B
      3. C
      4. D
      gets sent setRowOrder(1, 0) then the resulting element will look like
      1. B
      2. A
      3. C
      4. D
      If that in turn gets set setRowOrder(0, 3) the result would be
      1. A
      2. C
      3. D
      4. B
      Thus, the result is equivalent with the following sequence of operation on a java.util.List
      • Object row = list.remove(currentRow)
      • list.add(newRow, row)
      Parameters:
      currentRow - The current row index (the row to move)
      newRow - The new row index (where the row to move should end up)

    • isDependent

      Optional<String> isDependent(String hidden)
      If the given columnID is hidden, returns the column id that it depends on, otherwise returns empty (if hidden is not a valid column id or if it is not a hidden column).
      Parameters:
      hidden - A column id.
      Returns:
      The column id of the visible column that the hidden column depends on or empty.

    • hasDependent

      Optional<String> hasDependent(String visible)
      Returns the column id of the hidden column that the given visible column has as its dependent. That is, if the given column id 'visible' has a column that depends on it, returns the column id of that column. Otherwise empty is returned.
      Parameters:
      visible - Ye
      Returns:
      I gave up right about here. Have a nice day!

    • dependencyMapper

      RefinementElement.ColumnMapper dependencyMapper(String hidden, String visible)
      Returns the function mapping values from the visible column to the hidden column or null if no mapping exists or if hidden isn't a hidden column or if hidden isn't a mapping of the visible column. That is, if isDependent returns empty, this method returns null, otherwise it returns a function.
      Parameters:
      hidden - A column ID for a hidden column.
      visible - A column ID for a visible column.
      Returns:
      A mapping function to invoke when the column 'visible' changes. The function returns a value to set on the 'hidden' column (on the same row).