Difference between revisions of "Talk:SMILA/Documentation/2011.Simplification/Data Model and Serialization Formats"

/**
 * The Interface Any.
 * Counter proposal for simplification of smila.
 */
interface Any extends Iterable<Any>, List<Any> {
 
  // #################################################################################
  // literal
  /**
   * this models that the Any is also a Literal. another flavor is to model the Literal as a seperate value object and
   * move all the following methods to that object.
   * 
   * TODO | TM |
   * 
   * <pre>
   * the asXXX methods will always return null in case of a miss or error, while the toXXX will throw an exception if the type doesnt fit.
   * asXXX()
   * asXXX(T defaultValue)
   * toXXX()
   * toXXX(T defaultValue)  //NOTE: this will overwrite the Object.toString() and is not so nice but i think i can live with that
   * </pre>
   * 
   * | TM @ Mar 11, 2011
   *
   * @return the string
   */
  // #################################################################################
  /**
   * @return The string representation
   */
  String asString();
 
  /**
   * As double.
   *
   * @return The double representation, an InvalidValueTypeException is thrown if the value is not of type double.
   */
  Double asDouble();
 
  /**
   * As long.
   *
   * @return The long representation, an InvalidValueTypeException is thrown if the value is not of type long.
   */
  Long asLong();
 
  /**
   * As boolean.
   *
   * @return The boolean representation, an InvalidValueTypeException is thrown if the value is not of type boolean.
   */
  Boolean asBoolean();
 
  /**
   * As date.
   *
   * @return The date representation, an InvalidValueTypeException is thrown if the value is not of type date.
   */
  Date asDate();
 
  /**
   * As date time.
   *
   * @return The date time representation, an InvalidValueTypeException is thrown if the value is not of type date time.
   */
  Date asDateTime();
 
  /**
   * Enumeration with the possible value types.
   * 
   */
  enum LiteralType {
 
    /** The STRING. */
    STRING, 
 /** The DOUBLE. */
 DOUBLE, 
 /** The BOOLEAN. */
 BOOLEAN, 
 /** The LONG. */
 LONG, 
 /** The DATE. */
 DATE, 
 /** The DATETIME. */
 DATETIME
  };
 
  /**
   * sets the value, the type is deducted must be one of the allowed ones.
   * 
   * @param <T>
   *          the generic type
   * @param literal
   *          the literal
   * @return the a possibly previosly set literal
   * @throws ClassCastException
   *           the class cast exception
   * @throws InvalidValueTypeException
   *           in case the given literal is not an allowed type
   * @note there might be the rare case where one wants to set another type. in this case one just would have to work
   *       with castsa like so:<br/>
   *       <code>Date date = (Date) _any.setLiteral((Object) "Tue 1st, Dec");</code>
   */
  <T> T setLiteral(T literal) throws ClassCastException, InvalidValueTypeException;
 
  /**
   * Gets the literal type.
   *
   * @return value type
   */
  LiteralType getLiteralType();
 
  /**
   * Checks for literal.
   * 
   * @return true, if this Any's literal is not null
   */
  boolean hasLiteral();
 
  /**
   * Checks if is string.
   *
   * @return true if value is of type string
   */
  boolean isString();
 
  /**
   * Checks if is double.
   *
   * @return true if value is of type double
   */
  boolean isDouble();
 
  /**
   * Checks if is boolean.
   *
   * @return true if value is of type boolean
   */
  boolean isBoolean();
 
  /**
   * Checks if is long.
   *
   * @return true if value is of type long
   */
  boolean isLong();
 
  /**
   * Checks if is date.
   *
   * @return true if value is of type date
   */
  boolean isDate();
 
  /**
   * Checks if is date time.
   *
   * @return true if value is of type date time
   */
  boolean isDateTime();
 
  /**
   * Gets the factory.
   *
   * @return data factory to create Anys of the same kind.
   */
  DataFactory getFactory();
 
  /**
   * Size.
   *
   * @return size of Any. For {@link Value} this is always 1.
   */
  int size();
 
  // #################################################################################
  // name
  // #################################################################################
 
  /**
   * Gets the name of this AnyValue. Note that it may be empty ("")! Any objects created with a blank String are trimmed
   * to empty. Any objects with an empty name are called anonymous children
   * 
   * @return the name
   */
  String getName();
 
  /**
   * Checks if is anonymous name.
   *
   * @return true, if is anonymous name
   */
  boolean isAnonymousName();
 
  // #################################################################################
  // child accessors
  /**
   * the children are held in a list and that is the primary form of their keeping. that is: they mantain their order
   * when retrieved (get, iterator). The Any object has a name which may be used to access the child item(s). However,
   * the name needs not be unique and hence there can be >1 children with the same name (Bag semantic).
   *
   * @return the iterator
   */
  // #################################################################################
  /**
   * @return iterates over underlying list in order.
   */
  @Override
  Iterator<Any> iterator();
 
  /** {@inheritDoc}
   * @see java.util.List#get(int)
   */
  Any get(int index);
 
  /**
   * Gets the first.
   *
   * @param name the name
   * @return the first
   */
  Any getFirst(String name);
 
  /**
   * Gets the.
   *
   * @param name the name
   * @return the list
   */
  List<Any> get(String name);
 
  /**
   * Gets the as array.
   *
   * @param name the name
   * @return the as array
   */
  Any[] getAsArray(String name);
 
  /**
   * Gets the all.
   *
   * @return the all
   */
  Map<String, List<Any>> getAll();
 
  /**
   * inserts the values at the given position.
   *
   * @param index the index
   * @param value the value
   */
  void add(int index, Any... value);
 
  /**
   * replaces the same amount of Any values with the given ones. If there are less to be replaced than to be added then
   * the excess will be appended.
   * 
   * @param index
   *          the index
   * @param value
   *          the value
   * @return the replaced any values
   */
  List<Any> set(int index, Any... value);
 
  /**
   * appends the new value.
   * 
   * @param value
   *          the value
   */
  void add(Any... value);
 
  /**
   * replaces existing values with the same name at their index position; given values for which no replacement exists
   * are appended.
   * 
   * @param value
   *          the value
   * @return the replaced values
   */
  List<Any> set(Any... value);
 
}