Repository /Debellor/debellor-1.0.jar:org.debellor.core.DataObject

/*
 *  Debellor
 *
 *  Copyright (C) 2008-2009 by Marcin Wojnarski
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program 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 General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see http://www.gnu.org/licenses/.
 */
package org.debellor.core;

import org.debellor.core.data.DataVector;
import org.debellor.core.data.NumericFeature;
import org.debellor.core.data.SymbolicFeature;
import org.debellor.core.exception.data.DataCastException;

/**
 * A data object, i.e., a piece of data that can be processed by cells.
 * Data objects may be nested, like in {@link DataVector},
 * which contains a number of data objects and itself is a data object.
 * Basically, all {@link Sample Samples} are data objects,
 * which are composed of other more elementary data objects.
 * 
 * <p>DataObject instances are <i>value objects</i>.
 * They are <i>immutable</i>, so they can be freely shared between cells 
 * without risk of accidental modification.
 * They implement methods {@link Object#equals(Object)} and {@link Object#hashCode()},
 * so they can be compared with each other and stored in collections.
 * 
 * <p>Authors of new DataObject subclasses must ensure that the new classes
 * are immutable and correctly implement the above methods.
 * It is also highly recommended to override {@link Object#toString()}
 * to print out the value held by the data object.  
 *  
 * <p>The most important classes of data objects:
 * <ul> 
 * <li> Simple feature: {@link NumericFeature} or {@link SymbolicFeature}.
 * <li> Vector of data objects ({@link DataVector}), usually vector of features.
 * <li> {@link Sample}
 * </ul>
 * In the future: images, time series, special types of decisions, ...
 * 
 * <p> Data objects represent both input data 
 * ({@link Sample#data}) and decisions ({@link Sample#decision}) of samples.
 * 
 * @author Marcin Wojnarski
 *
 */
public abstract class DataObject {
	
	/** Must be implemented by every subclass. */
	@Override
	public abstract boolean equals(Object obj);
	
	/** Must be implemented by every subclass. */
	@Override
	public abstract int hashCode();


	/** Returns this DataObject casted to {@link DataVector}. 
	 * @throws DataCastException */
	public final DataVector asDataVector() throws DataCastException {
		try {
			return (DataVector) this;
		}
		catch(Exception e) {
			throw new DataCastException(this, DataVector.class);
		}
	}
	
	/** Returns this DataObject casted to {@link NumericFeature}. 
	 * @throws DataCastException */
	public final NumericFeature asNumericFeature() throws DataCastException {
		try {
			return (NumericFeature) this;
		}
		catch(Exception e) {
			throw new DataCastException(this, NumericFeature.class);
		}
	}
	
	/** Returns this DataObject casted to {@link SymbolicFeature}. 
	 * @throws DataCastException */
	public final SymbolicFeature asSymbolicFeature() throws DataCastException {
		try {
			return (SymbolicFeature) this;
		}
		catch(Exception e) {
			throw new DataCastException(this, SymbolicFeature.class);
		}
	}
	
}