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

/*
 *  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.Cell.Stream;
import org.debellor.core.Sample.SampleType;
import org.debellor.core.data.DataVector;
import org.debellor.core.data.SymbolicFeature;
import org.debellor.core.data.DataVector.DataVectorType;
import org.debellor.core.data.SymbolicFeature.SymbolicFeatureType;
import org.debellor.core.exception.data.DataCastException;

/** 
 * Subclasses of <code>DataType</code> describe common properties 
 * of all {@link DataObject DataObjects}
 * generated by a given data {@link Stream}.
 * For example, may contain information about number and types of features
 * of a <code>DataVector</code>.
 * Contain also information necessary for correct interpretation
 * of data values, e.g. a dictionary of symbols that should be put
 * in the place of numeric codes in {@link SymbolicFeature}.
 * 
 * <p>Usually, every new subclass of DataObject has
 * its corresponding DataType subclass which provides
 * type information specific to this DataObject subclass.
 * For example, common properties of {@link DataVector} objects
 * are described by an instance of {@link DataVectorType} class.
 * Similarly to DataObject subclasses, also DataType subclasses can be nested.
 * Usually, the nesting structure of DataType objects
 * exactly mirrors the nesting structure of corresponding data objects. 
 * 
 * <p>Like DataObjects, {@code DataType} objects are also <i>immutable</i>,
 * so they can be freely shared by cells without risk of accidental modification.
 */
public class DataType {
	

	/** Marks that type of a given part of data is unknown and consumer should expect everything. */
	public static final DataType UNKNOWN = null;
	
	/** Marks that a given part of data does not exist and the corresponding field 
	 * will always have <code>null</code> value, in all samples of the data stream.
	 * Consumer of the data should treat this part of data as <i>non-existent</i>,
	 * not only as all-nulls. For example, if {@link SampleType#decision} is NOT_PRESENT
	 * it means that there is no decision attribute, which is something different than <code>null</code> decisions
	 * (<code>null</code> might be treated as an unknown value of a decision). */
	public static final DataType NOT_PRESENT = new DataType(DataObject.class);
	
	/** Marks that a given part of data does exist (as opposite to {@link #NOT_PRESENT})
	 * but is always <code>null</code>,
	 * e.g., a decision attribute generally exists in all samples,
	 * but its concrete values are unknown, for some reason. */
	//public static final DataType ALL_NULLS = new DataType(DataObject.class);
	
	
	/** If {@code dataClass} is not null, corresponding data objects in all samples
	 * of the data set will be instances of the {@code dataClass} class
	 * or will be missing (null references).
	 * <p> Otherwise, class of corresponding data objects is unknown.
	 * Note that null {@code dataClass} does <i>not</i> mean that all corresponding 
	 * data objects will be missing! */
	public final Class<? extends DataObject> dataClass;
	
	public DataType(Class<? extends DataObject> dataClass) {
		this.dataClass = dataClass;
	}

	/** Returns this DataType casted to {@link DataVectorType}. 
	 * @throws DataCastException */
	public DataVectorType asDataVectorType() throws DataCastException {
		try {
			return (DataVectorType) this;
		}
		catch(Exception e) {
			throw new DataCastException(this, DataVectorType.class);
		}
	}

	/** Returns this DataType casted to {@link SymbolicFeatureType}. 
	 * @throws DataCastException */
	public final SymbolicFeatureType asSymbolicFeatureType() throws DataCastException {
		try {
			return (SymbolicFeatureType) this;
		}
		catch(Exception e) {
			throw new DataCastException(this, SymbolicFeatureType.class);
		}
	}

}