/*

 * Copyright 1999-2004 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code 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

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.sound.midi;

/**

 * A <code>SoundbankResource</code> represents any audio resource stored

 * in a <code>{@link Soundbank}</code>.  Common soundbank resources include:

 * <ul>

 * <li>Instruments.  An instrument may be specified in a variety of

 * ways.  However, all soundbanks have some mechanism for defining

 * instruments.  In doing so, they may reference other resources

 * stored in the soundbank.  Each instrument has a <code>Patch</code>

 * which specifies the MIDI program and bank by which it may be

 * referenced in MIDI messages.  Instrument information may be

 * stored in <code>{@link Instrument}</code> objects.

 * <li>Audio samples.  A sample typically is a sampled audio waveform

 * which contains a short sound recording whose duration is a fraction of

 * a second, or at most a few seconds.  These audio samples may be

 * used by a <code>{@link Synthesizer}</code> to synthesize sound in response to MIDI

 * commands, or extracted for use by an application.

 * (The terminology reflects musicians' use of the word "sample" to refer

 * collectively to a series of contiguous audio samples or frames, rather than

 * to a single, instantaneous sample.)

 * The data class for an audio sample will be an object

 * that encapsulates the audio sample data itself and information

 * about how to interpret it (the format of the audio data), such

 * as an <code>{@link javax.sound.sampled.AudioInputStream}</code>.     </li>

 * <li>Embedded sequences.  A sound bank may contain built-in

 * song data stored in a data object such as a <code>{@link Sequence}</code>.

 * </ul>

 * <p>

 * Synthesizers that use wavetable synthesis or related

 * techniques play back the audio in a sample when

 * synthesizing notes, often when emulating the real-world instrument that

 * was originally recorded.  However, there is not necessarily a one-to-one

 * correspondence between the <code>Instruments</code> and samples

 * in a <code>Soundbank</code>.  A single <code>Instrument</code> can use

 * multiple SoundbankResources (typically for notes of dissimilar pitch or

 * brightness).  Also, more than one <code>Instrument</code> can use the same

 * sample.

 *

 * @author Kara Kytle

 */

public abstract class SoundbankResource {

    /**

     * The sound bank that contains the <code>SoundbankResources</code>

     */

    private final Soundbank soundBank;

    /**

     * The name of the <code>SoundbankResource</code>

     */

    private final String name;

    /**

     * The class used to represent the sample's data.

     */

    private final Class dataClass;

    /**

     * The wavetable index.

     */

    //private final int index;

    /**

     * Constructs a new <code>SoundbankResource</code> from the given sound bank

     * and wavetable index.  (Setting the <code>SoundbankResource's</code> name,

     * sampled audio data, and instruments is a subclass responsibility.)

     * @param soundBank the sound bank containing this <code>SoundbankResource</code>

     * @param name the name of the sample

     * @param dataClass the class used to represent the sample's data

     *

     * @see #getSoundbank

     * @see #getName

     * @see #getDataClass

     * @see #getData

     */

    protected SoundbankResource(Soundbank soundBank, String name, Class<?> dataClass) {

        this.soundBank = soundBank;

        this.name = name;

        this.dataClass = dataClass;

    }

    /**

     * Obtains the sound bank that contains this <code>SoundbankResource</code>.

     * @return the sound bank in which this <code>SoundbankResource</code> is stored

     */

    public Soundbank getSoundbank() {

        return soundBank;

    }

    /**

     * Obtains the name of the resource.  This should generally be a string

     * descriptive of the resource.

     * @return the instrument's name

     */

    public String getName() {

        return name;

    }

    /**

     * Obtains the class used by this sample to represent its data.

     * The object returned by <code>getData</code> will be of this

     * class.  If this <code>SoundbankResource</code> object does not support

     * direct access to its data, returns <code>null</code>.

     * @return the class used to represent the sample's data, or

     * null if the data is not accessible

     */

    public Class<?> getDataClass() {

        return dataClass;

    }

    /**

     * Obtains the sampled audio that is stored in this <code>SoundbankResource</code>.

     * The type of object returned depends on the implementation of the

     * concrete class, and may be queried using <code>getDataClass</code>.

     * @return an object containing the sampled audio data

     * @see #getDataClass

     */

    public abstract Object getData();

    /**

     * Obtains the index of this <code>SoundbankResource</code> into the

     * <code>Soundbank's</code> set of <code>SoundbankResources</code>.

     * @return the wavetable index

     */

    //public int getIndex() {

    //  return index;

    //}

    /**

     * Obtains a list of the instruments in the sound bank that use the

     * <code>SoundbankResource</code> for sound synthesis.

     * @return an array of <code>Instruments</code> that reference this

     * <code>SoundbankResource</code>

     *

     * @see Instrument#getSamples

     */

    //public abstract Instrument[] getInstruments();

}