KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > sound > midi > MidiFileFormat


1 /*
2  * @(#)MidiFileFormat.java 1.17 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.sound.midi;
9
10 import java.io.InputStream JavaDoc;
11 import java.io.IOException JavaDoc;
12 import java.util.Collections JavaDoc;
13 import java.util.HashMap JavaDoc;
14 import java.util.Map JavaDoc;
15
16
17 /**
18  * A <code>MidiFileFormat</code> object encapsulates a MIDI file's
19  * type, as well as its length and timing information.
20  *
21  * <p>A <code>MidiFileFormat</code> object can
22  * include a set of properties. A property is a pair of key and value:
23  * the key is of type <code>String</code>, the associated property
24  * value is an arbitrary object.
25  * Properties specify additional informational
26  * meta data (like a author, or copyright).
27  * Properties are optional information, and file reader and file
28  * writer implementations are not required to provide or
29  * recognize properties.
30  *
31  * <p>The following table lists some common properties that should
32  * be used in implementations:
33  *
34  * <table border=1>
35  * <tr>
36  * <th>Property key</th>
37  * <th>Value type</th>
38  * <th>Description</th>
39  * </tr>
40  * <tr>
41  * <td>&quot;author&quot;</td>
42  * <td>{@link java.lang.String String}</td>
43  * <td>name of the author of this file</td>
44  * </tr>
45  * <tr>
46  * <td>&quot;title&quot;</td>
47  * <td>{@link java.lang.String String}</td>
48  * <td>title of this file</td>
49  * </tr>
50  * <tr>
51  * <td>&quot;copyright&quot;</td>
52  * <td>{@link java.lang.String String}</td>
53  * <td>copyright message</td>
54  * </tr>
55  * <tr>
56  * <td>&quot;date&quot;</td>
57  * <td>{@link java.util.Date Date}</td>
58  * <td>date of the recording or release</td>
59  * </tr>
60  * <tr>
61  * <td>&quot;comment&quot;</td>
62  * <td>{@link java.lang.String String}</td>
63  * <td>an arbitrary text</td>
64  * </tr>
65  * </table>
66  *
67  * @see MidiSystem#getMidiFileFormat(java.io.File)
68  * @see Sequencer#setSequence(java.io.InputStream stream)
69  *
70  * @version 1.17, 03/12/19
71  * @author Kara Kytle
72  * @author Florian Bomers
73  */
74
75 public class MidiFileFormat {
76
77
78     /**
79      * Represents unknown length.
80      * @see #getByteLength
81      * @see #getMicrosecondLength
82      */
83     public static final int UNKNOWN_LENGTH = -1;
84
85
86     /**
87      * The type of MIDI file.
88      */
89     protected int type;
90
91     /**
92      * The division type of the MIDI file.
93      *
94      * @see Sequence#PPQ
95      * @see Sequence#SMPTE_24
96      * @see Sequence#SMPTE_25
97      * @see Sequence#SMPTE_30DROP
98      * @see Sequence#SMPTE_30
99      */
100     protected float divisionType;
101
102     /**
103      * The timing resolution of the MIDI file.
104      */
105     protected int resolution;
106
107     /**
108      * The length of the MIDI file in bytes.
109      */
110     protected int byteLength;
111
112     /**
113      * The duration of the MIDI file in microseconds.
114      */
115     protected long microsecondLength;
116
117
118     /** The set of properties */
119     private HashMap JavaDoc<String JavaDoc, Object JavaDoc> properties;
120
121
122     /**
123      * Constructs a <code>MidiFileFormat</code>.
124      *
125      * @param type the MIDI file type (0, 1, or 2)
126      * @param divisionType the timing division type (PPQ or one of the SMPTE types)
127      * @param resolution the timing resolution
128      * @param bytes the length of the MIDI file in bytes, or UNKNOWN_LENGTH if not known
129      * @param microseconds the duration of the file in microseconds, or UNKNOWN_LENGTH if not known
130      * @see #UNKNOWN_LENGTH
131      * @see Sequence#PPQ
132      * @see Sequence#SMPTE_24
133      * @see Sequence#SMPTE_25
134      * @see Sequence#SMPTE_30DROP
135      * @see Sequence#SMPTE_30
136      */
137     public MidiFileFormat(int type, float divisionType, int resolution, int bytes, long microseconds) {
138
139     this.type = type;
140     this.divisionType = divisionType;
141     this.resolution = resolution;
142     this.byteLength = bytes;
143     this.microsecondLength = microseconds;
144     this.properties = null;
145     }
146
147
148     /**
149      * Construct a <code>MidiFileFormat</code> with a set of properties.
150      *
151      * @param type the MIDI file type (0, 1, or 2)
152      * @param divisionType the timing division type
153      * (PPQ or one of the SMPTE types)
154      * @param resolution the timing resolution
155      * @param bytes the length of the MIDI file in bytes,
156      * or UNKNOWN_LENGTH if not known
157      * @param microseconds the duration of the file in microseconds,
158      * or UNKNOWN_LENGTH if not known
159      * @param properties a <code>Map&lt;String,Object&gt;</code> object
160      * with properties
161      *
162      * @see #UNKNOWN_LENGTH
163      * @see Sequence#PPQ
164      * @see Sequence#SMPTE_24
165      * @see Sequence#SMPTE_25
166      * @see Sequence#SMPTE_30DROP
167      * @see Sequence#SMPTE_30
168      * @since 1.5
169      */
170     public MidiFileFormat(int type, float divisionType,
171               int resolution, int bytes,
172               long microseconds, Map JavaDoc<String JavaDoc, Object JavaDoc> properties) {
173     this(type, divisionType, resolution, bytes, microseconds);
174     this.properties = new HashMap JavaDoc<String JavaDoc, Object JavaDoc>(properties);
175     }
176
177
178
179     /**
180      * Obtains the MIDI file type.
181      * @return the file's type (0, 1, or 2)
182      */
183     public int getType() {
184     return type;
185     }
186
187     /**
188      * Obtains the timing division type for the MIDI file.
189      *
190      * @return the division type (PPQ or one of the SMPTE types)
191      *
192      * @see Sequence#Sequence(float, int)
193      * @see Sequence#PPQ
194      * @see Sequence#SMPTE_24
195      * @see Sequence#SMPTE_25
196      * @see Sequence#SMPTE_30DROP
197      * @see Sequence#SMPTE_30
198      * @see Sequence#getDivisionType()
199      */
200     public float getDivisionType() {
201     return divisionType;
202     }
203
204
205     /**
206      * Obtains the timing resolution for the MIDI file.
207      * If the division type is PPQ, the resolution is specified in ticks per beat.
208      * For SMTPE timing, the resolution is specified in ticks per frame.
209      *
210      * @return the number of ticks per beat (PPQ) or per frame (SMPTE)
211      * @see #getDivisionType
212      * @see Sequence#getResolution()
213      */
214     public int getResolution() {
215     return resolution;
216     }
217
218
219     /**
220      * Obtains the length of the MIDI file, expressed in 8-bit bytes.
221      * @return the number of bytes in the file, or UNKNOWN_LENGTH if not known
222      * @see #UNKNOWN_LENGTH
223      */
224     public int getByteLength() {
225     return byteLength;
226     }
227
228     /**
229      * Obtains the length of the MIDI file, expressed in microseconds.
230      * @return the file's duration in microseconds, or UNKNOWN_LENGTH if not known
231      * @see Sequence#getMicrosecondLength()
232      * @see #getByteLength
233      * @see #UNKNOWN_LENGTH
234      */
235     public long getMicrosecondLength() {
236     return microsecondLength;
237     }
238
239     /**
240      * Obtain an unmodifiable map of properties.
241      * The concept of properties is further explained in
242      * the {@link MidiFileFormat class description}.
243      *
244      * @return a <code>Map&lt;String,Object&gt;</code> object containing
245      * all properties. If no properties are recognized, an empty map is
246      * returned.
247      *
248      * @see #getProperty(String)
249      * @since 1.5
250      */
251     public Map JavaDoc<String JavaDoc,Object JavaDoc> properties() {
252     Map JavaDoc<String JavaDoc,Object JavaDoc> ret;
253     if (properties == null) {
254         ret = new HashMap JavaDoc<String JavaDoc,Object JavaDoc>(0);
255     } else {
256         ret = (Map JavaDoc<String JavaDoc,Object JavaDoc>) (properties.clone());
257     }
258     return (Map JavaDoc<String JavaDoc,Object JavaDoc>) Collections.unmodifiableMap(ret);
259     }
260
261
262     /**
263      * Obtain the property value specified by the key.
264      * The concept of properties is further explained in
265      * the {@link MidiFileFormat class description}.
266      *
267      * <p>If the specified property is not defined for a
268      * particular file format, this method returns
269      * <code>null</code>.
270      *
271      * @param key the key of the desired property
272      * @return the value of the property with the specified key,
273      * or <code>null</code> if the property does not exist.
274      *
275      * @see #properties
276      * @since 1.5
277      */
278     public Object JavaDoc getProperty(String JavaDoc key) {
279     if (properties == null) {
280         return null;
281     }
282     return properties.get(key);
283     }
284
285
286 }
287
288
Popular Tags