jdk/src/share/classes/javax/sound/midi/SoundbankResource.java
author darcy
Thu, 05 Jun 2014 23:17:05 -0700
changeset 25131 49006bd0e69d
parent 5506 202f599c92aa
child 26003 d630c97424bd
permissions -rw-r--r--
8044553: Fix raw and unchecked lint warnings in javax.sound.* Reviewed-by: prr
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
25131
49006bd0e69d 8044553: Fix raw and unchecked lint warnings in javax.sound.*
darcy
parents: 5506
diff changeset
     2
 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    23
 * questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
package javax.sound.midi;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
 * A <code>SoundbankResource</code> represents any audio resource stored
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
 * in a <code>{@link Soundbank}</code>.  Common soundbank resources include:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
 * <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
 * <li>Instruments.  An instrument may be specified in a variety of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
 * ways.  However, all soundbanks have some mechanism for defining
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
 * instruments.  In doing so, they may reference other resources
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
 * stored in the soundbank.  Each instrument has a <code>Patch</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
 * which specifies the MIDI program and bank by which it may be
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
 * referenced in MIDI messages.  Instrument information may be
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
 * stored in <code>{@link Instrument}</code> objects.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
 * <li>Audio samples.  A sample typically is a sampled audio waveform
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
 * which contains a short sound recording whose duration is a fraction of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
 * a second, or at most a few seconds.  These audio samples may be
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
 * used by a <code>{@link Synthesizer}</code> to synthesize sound in response to MIDI
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
 * commands, or extracted for use by an application.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
 * (The terminology reflects musicians' use of the word "sample" to refer
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
 * collectively to a series of contiguous audio samples or frames, rather than
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
 * to a single, instantaneous sample.)
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
 * The data class for an audio sample will be an object
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
 * that encapsulates the audio sample data itself and information
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
 * about how to interpret it (the format of the audio data), such
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
 * as an <code>{@link javax.sound.sampled.AudioInputStream}</code>.     </li>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
 * <li>Embedded sequences.  A sound bank may contain built-in
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
 * song data stored in a data object such as a <code>{@link Sequence}</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
 * </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
 * Synthesizers that use wavetable synthesis or related
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
 * techniques play back the audio in a sample when
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
 * synthesizing notes, often when emulating the real-world instrument that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
 * was originally recorded.  However, there is not necessarily a one-to-one
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
 * correspondence between the <code>Instruments</code> and samples
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
 * in a <code>Soundbank</code>.  A single <code>Instrument</code> can use
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
 * multiple SoundbankResources (typically for notes of dissimilar pitch or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
 * brightness).  Also, more than one <code>Instrument</code> can use the same
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
 * sample.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
 * @author Kara Kytle
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
public abstract class SoundbankResource {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
     * The sound bank that contains the <code>SoundbankResources</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
    private final Soundbank soundBank;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
     * The name of the <code>SoundbankResource</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
    private final String name;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
     * The class used to represent the sample's data.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
     */
25131
49006bd0e69d 8044553: Fix raw and unchecked lint warnings in javax.sound.*
darcy
parents: 5506
diff changeset
    86
    private final Class<?> dataClass;
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
     * The wavetable index.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
    //private final int index;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
     * Constructs a new <code>SoundbankResource</code> from the given sound bank
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
     * and wavetable index.  (Setting the <code>SoundbankResource's</code> name,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
     * sampled audio data, and instruments is a subclass responsibility.)
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
     * @param soundBank the sound bank containing this <code>SoundbankResource</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
     * @param name the name of the sample
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
     * @param dataClass the class used to represent the sample's data
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
     * @see #getSoundbank
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
     * @see #getName
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
     * @see #getDataClass
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
     * @see #getData
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
    protected SoundbankResource(Soundbank soundBank, String name, Class<?> dataClass) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
        this.soundBank = soundBank;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
        this.name = name;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
        this.dataClass = dataClass;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
     * Obtains the sound bank that contains this <code>SoundbankResource</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
     * @return the sound bank in which this <code>SoundbankResource</code> is stored
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
    public Soundbank getSoundbank() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
        return soundBank;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
     * Obtains the name of the resource.  This should generally be a string
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
     * descriptive of the resource.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
     * @return the instrument's name
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
    public String getName() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
        return name;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
     * Obtains the class used by this sample to represent its data.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
     * The object returned by <code>getData</code> will be of this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
     * class.  If this <code>SoundbankResource</code> object does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
     * direct access to its data, returns <code>null</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
     * @return the class used to represent the sample's data, or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
     * null if the data is not accessible
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
    public Class<?> getDataClass() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
        return dataClass;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
     * Obtains the sampled audio that is stored in this <code>SoundbankResource</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
     * The type of object returned depends on the implementation of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
     * concrete class, and may be queried using <code>getDataClass</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
     * @return an object containing the sampled audio data
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
     * @see #getDataClass
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
    public abstract Object getData();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
     * Obtains the index of this <code>SoundbankResource</code> into the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
     * <code>Soundbank's</code> set of <code>SoundbankResources</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
     * @return the wavetable index
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
    //public int getIndex() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
    //  return index;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
    //}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
     * Obtains a list of the instruments in the sound bank that use the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
     * <code>SoundbankResource</code> for sound synthesis.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
     * @return an array of <code>Instruments</code> that reference this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
     * <code>SoundbankResource</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
     * @see Instrument#getSamples
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
    //public abstract Instrument[] getInstruments();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
}