001/**
002 * DataSet -- A collection of cases that make up a data set.
003 *
004 * Copyright (C) 2003-2025, 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 February 23, 2025
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     * @return A new instance of a DateSet with the specified name.
045     */
046    public static DataSet newInstance(CharSequence name) {
047        DataSet o = FACTORY.object();
048        try {
049            o.setName(name);
050        } catch (NullPointerException e) {
051            FACTORY.recycle(o);
052            throw e;
053        }
054        return o;
055    }
056
057    private static final ObjectFactory<DataSet> FACTORY = new ObjectFactory<DataSet>() {
058        @Override
059        protected DataSet create() {
060            return new DataSet();
061        }
062
063        @Override
064        protected void cleanup(DataSet obj) {
065            obj.reset();
066        }
067    };
068
069    /**
070     * Recycles a set instance immediately (on the stack when executing in a
071     * StackContext).
072     *
073     * @param instance The instance of this class to recycle.
074     */
075    public static void recycle(DataSet instance) {
076        FACTORY.recycle(instance);
077    }
078
079    /**
080     * Do not allow the default constructor to be used.
081     */
082    private DataSet() { }
083
084    /**
085     * Return a data set made up of any {@link DataCase cases} found in the specified
086     * collection. Any objects that are not {@link DataCase} objects in the specified
087     * collection will be ignored. If you pass a <code>DataSet</code> object, all the
088     * cases found in it will be added to the new set.
089     *
090     * @param name  The name to be assigned to this set (may not be <code>null</code>).
091     * @param cases A collection that contains a set of cases.
092     * @return A new DataSet with the specified name and collection of cases.
093     */
094    public static DataSet valueOf(String name, Collection<?> cases) {
095
096        DataSet set = DataSet.newInstance(name);
097
098        if (cases instanceof DataSet) {
099            set.addAll((DataSet)cases);
100
101        } else {
102            for (Object obj : cases) {
103                if (obj instanceof DataCase) {
104                    set.add((DataCase)obj);
105                }
106            }
107        }
108
109        return set;
110    }
111}