001/**
002 * DataSet -- A collection of cases that make up a data set.
003 *
004 * Copyright (C) 2003-2015, by Joseph A. Huwaldt. All rights reserved.
005 *
006 * This library is free software; you can redistribute it and/or modify it under the terms
007 * of the GNU Lesser General Public License as published by the Free Software Foundation;
008 * either version 2 of the License, or (at your option) any later version.
009 *
010 * This library is distributed in the hope that it will be useful, but WITHOUT ANY
011 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
012 * PARTICULAR PURPOSE. See the GNU Library General Public License for more details.
013 *
014 * You should have received a copy of the GNU Lesser General Public License along with
015 * this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place -
016 * Suite 330, Boston, MA 02111-1307, USA. Or visit: http://www.gnu.org/licenses/lgpl.html
017 */
018package jahuwaldt.js.datareader;
019
020import java.util.Collection;
021import javolution.context.ObjectFactory;
022
023/**
024 * Defines a data element called a set. A data set is a collection of runs or
025 * {@link DataCase cases} that make up a single test or set of associated data. Any number
026 * of cases may be added to a set.
027 *
028 * <p> Modified by: Joseph A. Huwaldt </p>
029 *
030 * @author Joseph A. Huwaldt, Date: March 5, 2003
031 * @version October 13, 2015
032 */
033public final class DataSet extends DataElementList<DataCase> {
034
035    //////////////////////
036    // Factory Creation //
037    //////////////////////
038    /**
039     * Returns a new, preallocated or recycled <code>DataSet</code> instance (on the stack
040     * when executing in a <code>StackContext</code>) with the specified name, that can
041     * store a list of {@link DataCase} objects and any associated user data.
042     *
043     * @param name The name to be assigned to this set (may not be <code>null</code>).
044     */
045    public static DataSet newInstance(CharSequence name) {
046        DataSet o = FACTORY.object();
047        try {
048            o.setName(name);
049        } catch (NullPointerException e) {
050            FACTORY.recycle(o);
051            throw e;
052        }
053        return o;
054    }
055
056    private static final ObjectFactory<DataSet> FACTORY = new ObjectFactory<DataSet>() {
057        @Override
058        protected DataSet create() {
059            return new DataSet();
060        }
061
062        @Override
063        protected void cleanup(DataSet obj) {
064            obj.reset();
065        }
066    };
067
068    /**
069     * Recycles a set instance immediately (on the stack when executing in a
070     * StackContext).
071     */
072    public static void recycle(DataSet instance) {
073        FACTORY.recycle(instance);
074    }
075
076    /**
077     * Do not allow the default constructor to be used.
078     */
079    private DataSet() { }
080
081    /**
082     * Return a data set made up of any {@link DataCase cases} found in the specified
083     * collection. Any objects that are not {@link DataCase} objects in the specified
084     * collection will be ignored. If you pass a <code>DataSet</code> object, all the
085     * cases found in it will be added to the new set.
086     *
087     * @param name  The name to be assigned to this set (may not be <code>null</code>).
088     * @param cases A collection that contains a set of cases.
089     */
090    public static DataSet valueOf(String name, Collection<?> cases) {
091
092        DataSet set = DataSet.newInstance(name);
093
094        if (cases instanceof DataSet) {
095            set.addAll((DataSet)cases);
096
097        } else {
098            for (Object obj : cases) {
099                if (obj instanceof DataCase) {
100                    set.add((DataCase)obj);
101                }
102            }
103        }
104
105        return set;
106    }
107}