/*
 This file is part of the software framework JStatCom, 
 a library for building applications for data based analysis.

 Copyright (C) 2000-2005  Markus Kraetzig

 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as
 published by the Free Software Foundation; either version 2.1 of the
 License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 USA
 */

package com.jstatcom.model;

/**
 * Defines the contract for all data types to be used with Engine,
 * Symbol and SymbolTable. It extends
 * com.dautelle.xml.Representable to ensure that all data objects
 * can be serialized with their XML representation that has to be defined in
 * toXML.
 * 

 * JSCData objects should notify listeners about changes in the
 * underlying value via a JSCDataEvent. There are several event
 * types defined in JSCDataEventTypes for the most common
 * changes, but different types may be defined by extending this enumeration.
 * This is most preferably done by defining a static inner class for the
 * respective JSCData implementation.
 * 

 * A further requirement for implementations of this interface is that all
 * setter methods should copy mutable data before it is set and all getter
 * methods should only return a copy of mutable objects. References should only
 * be passed if the underlying objects are immutable, see (Joshua Bloch,
 * "Effective Java", Item 13) .
 * 

 * Design Note:  

 * Implementations of JSCData should in general act as wrapper to
 * other types by providing additional functionality, like notification of
 * listeners. Implementations should provide basic adapter methods to modify the
 * underlying values, but the idea is, to keep them thin. For example the the
 * JSCNArray class acts as a wrapper for double[][],
 * but it is not designed as a general purpose matrix class for linear algebra.
 * Instead this should be delegated to classes especially designed for these
 * purposes. The wrapper can provide accessor methods that get the underlying
 * value as instances of these special classes.
 * 

 * Usage Note:  

 * To make sure that a JSCData object can be deserialized from
 * its XML representation, every data class must also implement a public static
 * field with the respective implementation of javolution37.javolution.xml.XmlFormat. See the
 * API documentation of this class for how to do this.
 * 
 * @author Markus Kraetzig 
 */
public interface JSCData {

    /**
     * Gets the value for a property type.
     * 
     * @param type
     *            the property type
     * @return the value or null if the property has not been set
     */
    Object getJSCProperty(JSCPropertyTypes type);

    /**
     * Set the value for a property type. Values are not serialized. The
     * properties can be used to store runtime information associated with a
     * data object.
     * 
     * @param type
     *            the property type
     * @param val
     *            the associated property value
     */
    void setJSCProperty(JSCPropertyTypes type, Object val);

    /**
     * Removes the property value for type.
     * 
     * @param type
     */
    void removeJSCProperty(JSCPropertyTypes type);

    /**
     * Adds a listener that is notified when changes of type
     * evtType occur in this object. All other events that are
     * fired by this object are not dispatched to evtListener.
     * 
     * @param evtListener
     *            the listener object that gets notified when an event of type
     *            evtType gets fired
     * @param evtType
     *            the type of event that evtListener wants to
     *            listen to
     */
    void addJSCDataListener(JSCDataListener evtListener,
            JSCDataEventTypes evtType);

    /**
     * After applying this method, isEmpty returns
     * true. Implementations should fire a
     * JSCDataEventTypes.EMPTY_STATE event if the data object was
     * not empty before.
     */
    void clear();

    /**
     * Gets a copy of the current object. Implementations of this method must
     * fulfil the two conditions:
     * 

     * 
a.isEqual(a.copy())- compares values
     * 
a.getName().equals(a.copy().getName())- compares
     * name
     * 
     * 
     * JSCDataListeners attached to the original object should
     * not be copied.
     * 
     * @return a clonelike copy of the original object
     */
    JSCData copy();

    /**
     * Gets a formatted string representing the value stored in this
     * JSCData object.
     * 
     * @return a formatted string
     */
    String display();

    /**
     * Gets whether this data object contains any data. Implementations of this
     * method should document precisely, when the respective object is
     * considered to be empty.
     * 
     * @return true if no data is contained
     */
    boolean isEmpty();

    /**
     * Gets whether the values of this data object and other are
     * logically equal.
     * 
     * @return true if considered equal according to the logic of
     *         the representation
     */
    boolean isEqual(JSCData other);

    /**
     * Gets the name of the data object. It must fulfil the requirements for
     * variable names defined in JSCConstants.
     * 
     * @return the name
     * @see com.jstatcom.model.JSCConstants#isValidName
     */
    String name();

    /**
     * Removes a JSCDataListener from all different listener
     * lists.
     * 
     * @param evtListener
     *            the listener object to be removed
     */
    void removeJSCDataListener(JSCDataListener evtListener);

    /**
     * Gets the type of the data object.
     * 
     * @return data type
     * @see com.jstatcom.model.JSCTypes
     */
    JSCTypes type();

    /**
     * Gets the value stored in this data object.
     * 
     * @return object that can be cast to a certain type depending on the
     *         JSCType
     */
    Object value();
}