/*
 * Copyright (c) 1998, 2014, Oracle and/or its affiliates. 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.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.sound.midi;

/**
 * A {@code Soundbank} contains a set of {@code Instruments} that can be loaded
 * into a {@code Synthesizer}. Note that a Java Sound {@code Soundbank} is
 * different from a MIDI bank. MIDI permits up to 16383 banks, each containing
 * up to 128 instruments (also sometimes called programs, patches, or timbres).
 * However, a {@code Soundbank} can contain 16383 times 128 instruments, because
 * the instruments within a {@code Soundbank} are indexed by both a MIDI program
 * number and a MIDI bank number (via a {@code Patch} object). Thus, a
 * {@code Soundbank} can be thought of as a collection of MIDI banks.
 * <p>
 * {@code Soundbank} includes methods that return {@code String} objects
 * containing the sound bank's name, manufacturer, version number, and
 * description. The precise content and format of these strings is left to the
 * implementor.
 * <p>
 * Different synthesizers use a variety of synthesis techniques. A common one is
 * wavetable synthesis, in which a segment of recorded sound is played back,
 * often with looping and pitch change. The Downloadable Sound (DLS) format uses
 * segments of recorded sound, as does the Headspace Engine. {@code Soundbanks}
 * and {@code Instruments} that are based on wavetable synthesis (or other uses
 * of stored sound recordings) should typically implement the
 * {@code getResources()} method to provide access to these recorded segments.
 * This is optional, however; the method can return an zero-length array if the
 * synthesis technique doesn't use sampled sound (FM synthesis and physical
 * modeling are examples of such techniques), or if it does but the implementor
 * chooses not to make the samples accessible.
 *
 * @author David Rivas
 * @author Kara Kytle
 * @see Synthesizer#getDefaultSoundbank
 * @see Synthesizer#isSoundbankSupported
 * @see Synthesizer#loadInstruments(Soundbank, Patch[])
 * @see Patch
 * @see Instrument
 * @see SoundbankResource
 */
public interface Soundbank {

    /**
     * Obtains the name of the sound bank.
     *
     * @return a {@code String} naming the sound bank
     */
    String getName();

    /**
     * Obtains the version string for the sound bank.
     *
     * @return a {@code String} that indicates the sound bank's version
     */
    String getVersion();

    /**
     * Obtains a {@code string} naming the company that provides the sound bank.
     *
     * @return the vendor string
     */
    String getVendor();

    /**
     * Obtains a textual description of the sound bank, suitable for display.
     *
     * @return a {@code String} that describes the sound bank
     */
    String getDescription();

    /**
     * Extracts a list of non-Instrument resources contained in the sound bank.
     *
     * @return an array of resources, excluding instruments. If the sound bank
     *         contains no resources (other than instruments), returns an array
     *         of length 0.
     */
    SoundbankResource[] getResources();

    /**
     * Obtains a list of instruments contained in this sound bank.
     *
     * @return an array of the {@code Instruments} in this {@code SoundBank}. If
     *         the sound bank contains no instruments, returns an array of
     *         length 0.
     * @see Synthesizer#getLoadedInstruments
     * @see #getInstrument(Patch)
     */
    Instrument[] getInstruments();

    /**
     * Obtains an {@code Instrument} from the given {@code Patch}.
     *
     * @param  patch a {@code Patch} object specifying the bank index and
     *         program change number
     * @return the requested instrument, or {@code null} if the sound bank
     *         doesn't contain that instrument
     * @see #getInstruments
     * @see Synthesizer#loadInstruments(Soundbank, Patch[])
     */
    Instrument getInstrument(Patch patch);
}