diff options
author | serb <none@none> | 2014-03-21 16:51:53 +0400 |
---|---|---|
committer | serb <none@none> | 2014-03-21 16:51:53 +0400 |
commit | d75348d6ec07d62d87b34b1afd3f7ef515fa9850 (patch) | |
tree | 894178fe8d5424e8c229b641ba4df95927ab24db | |
parent | 150b4c295972016dd2914116ed2d0d1836fcb98a (diff) |
8037117: Javadoc cleanup of javax.sound.midi.spi package
Reviewed-by: art, pchelko
4 files changed, 158 insertions, 154 deletions
diff --git a/src/share/classes/javax/sound/midi/spi/MidiDeviceProvider.java b/src/share/classes/javax/sound/midi/spi/MidiDeviceProvider.java index 4146d3d9f..b4c95a1ec 100644 --- a/src/share/classes/javax/sound/midi/spi/MidiDeviceProvider.java +++ b/src/share/classes/javax/sound/midi/spi/MidiDeviceProvider.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 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 @@ -26,26 +26,24 @@ package javax.sound.midi.spi; import javax.sound.midi.MidiDevice; -import javax.sound.midi.MidiUnavailableException; /** - * A <code>MidiDeviceProvider</code> is a factory or provider for a particular - * type of MIDI device. - * This mechanism allows the implementation to determine - * how resources are managed in the creation and management of - * a device. + * A {@code MidiDeviceProvider} is a factory or provider for a particular type + * of MIDI device. This mechanism allows the implementation to determine how + * resources are managed in the creation and management of a device. * * @author Kara Kytle */ public abstract class MidiDeviceProvider { - /** * Indicates whether the device provider supports the device represented by * the specified device info object. - * @param info an info object that describes the device for which support is queried - * @return <code>true</code> if the specified device is supported, - * otherwise <code>false</code> + * + * @param info an info object that describes the device for which support + * is queried + * @return {@code true} if the specified device is supported, otherwise + * {@code false} */ public boolean isDeviceSupported(MidiDevice.Info info) { @@ -59,21 +57,22 @@ public abstract class MidiDeviceProvider { return false; } - /** - * Obtains the set of info objects representing the device - * or devices provided by this <code>MidiDeviceProvider</code>. + * Obtains the set of info objects representing the device or devices + * provided by this {@code MidiDeviceProvider}. + * * @return set of device info objects */ public abstract MidiDevice.Info[] getDeviceInfo(); - /** * Obtains an instance of the device represented by the info object. - * @param info an info object that describes the desired device + * + * @param info an info object that describes the desired device * @return device instance * @throws IllegalArgumentException if the info object specified does not - * match the info object for a device supported by this <code>MidiDeviceProvider</code>. + * match the info object for a device supported by this + * {@code MidiDeviceProvider} */ public abstract MidiDevice getDevice(MidiDevice.Info info); } diff --git a/src/share/classes/javax/sound/midi/spi/MidiFileReader.java b/src/share/classes/javax/sound/midi/spi/MidiFileReader.java index 2c050b800..ecb72b32d 100644 --- a/src/share/classes/javax/sound/midi/spi/MidiFileReader.java +++ b/src/share/classes/javax/sound/midi/spi/MidiFileReader.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 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 @@ -35,9 +35,10 @@ import javax.sound.midi.Sequence; import javax.sound.midi.InvalidMidiDataException; /** - * A <code>MidiFileReader</code> supplies MIDI file-reading services. Classes implementing this - * interface can parse the format information from one or more types of - * MIDI file, and can produce a <code>Sequence</code> object from files of these types. + * A {@code MidiFileReader} supplies MIDI file-reading services. Classes + * implementing this interface can parse the format information from one or more + * types of MIDI file, and can produce a {@link Sequence} object from files of + * these types. * * @author Kara Kytle * @since 1.3 @@ -45,98 +46,102 @@ import javax.sound.midi.InvalidMidiDataException; public abstract class MidiFileReader { /** - * Obtains the MIDI file format of the input stream provided. The stream must - * point to valid MIDI file data. In general, MIDI file readers may + * Obtains the MIDI file format of the input stream provided. The stream + * must point to valid MIDI file data. In general, MIDI file readers may * need to read some data from the stream before determining whether they - * support it. These parsers must - * be able to mark the stream, read enough data to determine whether they - * support the stream, and, if not, reset the stream's read pointer to its original - * position. If the input stream does not support this, this method may fail - * with an <code>IOException</code>. - * @param stream the input stream from which file format information should be - * extracted - * @return a <code>MidiFileFormat</code> object describing the MIDI file format - * @throws InvalidMidiDataException if the stream does not point to valid MIDI - * file data recognized by the system + * support it. These parsers must be able to mark the stream, read enough + * data to determine whether they support the stream, and, if not, reset the + * stream's read pointer to its original position. If the input stream does + * not support this, this method may fail with an {@code IOException}. + * + * @param stream the input stream from which file format information + * should be extracted + * @return a {@code MidiFileFormat} object describing the MIDI file format + * @throws InvalidMidiDataException if the stream does not point to valid + * MIDI file data recognized by the system * @throws IOException if an I/O exception occurs * @see InputStream#markSupported * @see InputStream#mark */ - public abstract MidiFileFormat getMidiFileFormat(InputStream stream) throws InvalidMidiDataException, IOException; - + public abstract MidiFileFormat getMidiFileFormat(InputStream stream) + throws InvalidMidiDataException, IOException; /** - * Obtains the MIDI file format of the URL provided. The URL must - * point to valid MIDI file data. - * @param url the URL from which file format information should be - * extracted - * @return a <code>MidiFileFormat</code> object describing the MIDI file format + * Obtains the MIDI file format of the URL provided. The URL must point to + * valid MIDI file data. + * + * @param url the URL from which file format information should be + * extracted + * @return a {@code MidiFileFormat} object describing the MIDI file format * @throws InvalidMidiDataException if the URL does not point to valid MIDI - * file data recognized by the system + * file data recognized by the system * @throws IOException if an I/O exception occurs */ - public abstract MidiFileFormat getMidiFileFormat(URL url) throws InvalidMidiDataException, IOException; - + public abstract MidiFileFormat getMidiFileFormat(URL url) + throws InvalidMidiDataException, IOException; /** - * Obtains the MIDI file format of the <code>File</code> provided. - * The <code>File</code> must point to valid MIDI file data. - * @param file the <code>File</code> from which file format information should be - * extracted - * @return a <code>MidiFileFormat</code> object describing the MIDI file format - * @throws InvalidMidiDataException if the <code>File</code> does not point to valid MIDI - * file data recognized by the system + * Obtains the MIDI file format of the {@code File} provided. The + * {@code File} must point to valid MIDI file data. + * + * @param file the {@code File} from which file format information should + * be extracted + * @return a {@code MidiFileFormat} object describing the MIDI file format + * @throws InvalidMidiDataException if the {@code File} does not point to + * valid MIDI file data recognized by the system * @throws IOException if an I/O exception occurs */ - public abstract MidiFileFormat getMidiFileFormat(File file) throws InvalidMidiDataException, IOException; - + public abstract MidiFileFormat getMidiFileFormat(File file) + throws InvalidMidiDataException, IOException; /** - * Obtains a MIDI sequence from the input stream provided. The stream must - * point to valid MIDI file data. In general, MIDI file readers may - * need to read some data from the stream before determining whether they - * support it. These parsers must - * be able to mark the stream, read enough data to determine whether they - * support the stream, and, if not, reset the stream's read pointer to its original - * position. If the input stream does not support this, this method may fail - * with an IOException. - * @param stream the input stream from which the <code>Sequence</code> should be - * constructed - * @return a <code>Sequence</code> object based on the MIDI file data contained - * in the input stream. - * @throws InvalidMidiDataException if the stream does not point to valid MIDI - * file data recognized by the system + * Obtains a MIDI sequence from the input stream provided. The stream must + * point to valid MIDI file data. In general, MIDI file readers may need to + * read some data from the stream before determining whether they support + * it. These parsers must be able to mark the stream, read enough data to + * determine whether they support the stream, and, if not, reset the + * stream's read pointer to its original position. If the input stream does + * not support this, this method may fail with an IOException. + * + * @param stream the input stream from which the {@code Sequence} should + * be constructed + * @return a {@code Sequence} object based on the MIDI file data contained + * in the input stream. + * @throws InvalidMidiDataException if the stream does not point to valid + * MIDI file data recognized by the system * @throws IOException if an I/O exception occurs * @see InputStream#markSupported * @see InputStream#mark */ - public abstract Sequence getSequence(InputStream stream) throws InvalidMidiDataException, IOException; - + public abstract Sequence getSequence(InputStream stream) + throws InvalidMidiDataException, IOException; /** - * Obtains a MIDI sequence from the URL provided. The URL must - * point to valid MIDI file data. - * @param url the URL for which the <code>Sequence</code> should be - * constructed - * @return a <code>Sequence</code> object based on the MIDI file data pointed - * to by the URL + * Obtains a MIDI sequence from the URL provided. The URL must point to + * valid MIDI file data. + * + * @param url the URL for which the {@code Sequence} should be constructed + * @return a {@code Sequence} object based on the MIDI file data pointed to + * by the URL * @throws InvalidMidiDataException if the URL does not point to valid MIDI - * file data recognized by the system + * file data recognized by the system * @throws IOException if an I/O exception occurs */ - public abstract Sequence getSequence(URL url) throws InvalidMidiDataException, IOException; - + public abstract Sequence getSequence(URL url) + throws InvalidMidiDataException, IOException; /** - * Obtains a MIDI sequence from the <code>File</code> provided. The <code>File</code> must - * point to valid MIDI file data. - * @param file the <code>File</code> from which the <code>Sequence</code> should be - * constructed - * @return a <code>Sequence</code> object based on the MIDI file data pointed - * to by the <code>File</code> - * @throws InvalidMidiDataException if the <code>File</code> does not point to valid MIDI - * file data recognized by the system + * Obtains a MIDI sequence from the {@code File} provided. The {@code File} + * must point to valid MIDI file data. + * + * @param file the {@code File} from which the {@code Sequence} should be + * constructed + * @return a {@code Sequence} object based on the MIDI file data pointed to + * by the {@code File} + * @throws InvalidMidiDataException if the {@code File} does not point to + * valid MIDI file data recognized by the system * @throws IOException if an I/O exception occurs */ - public abstract Sequence getSequence(File file) throws InvalidMidiDataException, IOException; + public abstract Sequence getSequence(File file) + throws InvalidMidiDataException, IOException; } diff --git a/src/share/classes/javax/sound/midi/spi/MidiFileWriter.java b/src/share/classes/javax/sound/midi/spi/MidiFileWriter.java index 531c54852..a1800f7f7 100644 --- a/src/share/classes/javax/sound/midi/spi/MidiFileWriter.java +++ b/src/share/classes/javax/sound/midi/spi/MidiFileWriter.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2002, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 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 @@ -30,45 +30,44 @@ import java.io.IOException; import java.io.OutputStream; import javax.sound.midi.Sequence; -import javax.sound.midi.MidiFileFormat; /** - * A <code>MidiFileWriter</code> supplies MIDI file-writing services. Classes - * that implement this interface can write one or more types of MIDI file from - * a <code>{@link Sequence}</code> object. + * A {@code MidiFileWriter} supplies MIDI file-writing services. Classes that + * implement this interface can write one or more types of MIDI file from a + * {@link Sequence} object. * * @author Kara Kytle * @since 1.3 */ public abstract class MidiFileWriter { - /** * Obtains the set of MIDI file types for which file writing support is * provided by this file writer. - * @return array of file types. If no file types are supported, - * an array of length 0 is returned. + * + * @return array of file types. If no file types are supported, an array of + * length 0 is returned. */ public abstract int[] getMidiFileTypes(); - /** - * Obtains the file types that this file writer can write from the - * sequence specified. - * @param sequence the sequence for which MIDI file type support - * is queried - * @return array of file types. If no file types are supported, - * returns an array of length 0. + * Obtains the file types that this file writer can write from the sequence + * specified. + * + * @param sequence the sequence for which MIDI file type support is + * queried + * @return array of file types. If no file types are supported, returns an + * array of length 0. */ public abstract int[] getMidiFileTypes(Sequence sequence); - /** * Indicates whether file writing support for the specified MIDI file type * is provided by this file writer. - * @param fileType the file type for which write capabilities are queried - * @return <code>true</code> if the file type is supported, - * otherwise <code>false</code> + * + * @param fileType the file type for which write capabilities are queried + * @return {@code true} if the file type is supported, otherwise + * {@code false} */ public boolean isFileTypeSupported(int fileType) { @@ -81,14 +80,14 @@ public abstract class MidiFileWriter { return false; } - /** * Indicates whether a MIDI file of the file type specified can be written * from the sequence indicated. - * @param fileType the file type for which write capabilities are queried - * @param sequence the sequence for which file writing support is queried - * @return <code>true</code> if the file type is supported for this sequence, - * otherwise <code>false</code> + * + * @param fileType the file type for which write capabilities are queried + * @param sequence the sequence for which file writing support is queried + * @return {@code true} if the file type is supported for this sequence, + * otherwise {@code false} */ public boolean isFileTypeSupported(int fileType, Sequence sequence) { @@ -101,35 +100,38 @@ public abstract class MidiFileWriter { return false; } - /** * Writes a stream of bytes representing a MIDI file of the file type * indicated to the output stream provided. - * @param in sequence containing MIDI data to be written to the file - * @param fileType type of the file to be written to the output stream - * @param out stream to which the file data should be written + * + * @param in sequence containing MIDI data to be written to the file + * @param fileType type of the file to be written to the output stream + * @param out stream to which the file data should be written * @return the number of bytes written to the output stream * @throws IOException if an I/O exception occurs * @throws IllegalArgumentException if the file type is not supported by - * this file writer + * this file writer * @see #isFileTypeSupported(int, Sequence) - * @see #getMidiFileTypes(Sequence) + * @see #getMidiFileTypes(Sequence) */ - public abstract int write(Sequence in, int fileType, OutputStream out) throws IOException; - + public abstract int write(Sequence in, int fileType, OutputStream out) + throws IOException; /** * Writes a stream of bytes representing a MIDI file of the file type * indicated to the external file provided. - * @param in sequence containing MIDI data to be written to the external file - * @param fileType type of the file to be written to the external file - * @param out external file to which the file data should be written + * + * @param in sequence containing MIDI data to be written to the external + * file + * @param fileType type of the file to be written to the external file + * @param out external file to which the file data should be written * @return the number of bytes written to the file * @throws IOException if an I/O exception occurs * @throws IllegalArgumentException if the file type is not supported by - * this file writer + * this file writer * @see #isFileTypeSupported(int, Sequence) - * @see #getMidiFileTypes(Sequence) + * @see #getMidiFileTypes(Sequence) */ - public abstract int write(Sequence in, int fileType, File out) throws IOException; + public abstract int write(Sequence in, int fileType, File out) + throws IOException; } diff --git a/src/share/classes/javax/sound/midi/spi/SoundbankReader.java b/src/share/classes/javax/sound/midi/spi/SoundbankReader.java index fec137851..c7e82d996 100644 --- a/src/share/classes/javax/sound/midi/spi/SoundbankReader.java +++ b/src/share/classes/javax/sound/midi/spi/SoundbankReader.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 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 @@ -25,60 +25,58 @@ package javax.sound.midi.spi; -import java.io.InputStream; -import java.io.IOException; import java.io.File; - +import java.io.IOException; +import java.io.InputStream; import java.net.URL; -import javax.sound.midi.Soundbank; import javax.sound.midi.InvalidMidiDataException; - +import javax.sound.midi.Soundbank; /** - * A <code>SoundbankReader</code> supplies soundbank file-reading services. - * Concrete subclasses of <code>SoundbankReader</code> parse a given - * soundbank file, producing a {@link javax.sound.midi.Soundbank} - * object that can be loaded into a {@link javax.sound.midi.Synthesizer}. + * A {@code SoundbankReader} supplies soundbank file-reading services. Concrete + * subclasses of {@code SoundbankReader} parse a given soundbank file, producing + * a {@link javax.sound.midi.Soundbank} object that can be loaded into a + * {@link javax.sound.midi.Synthesizer}. * * @since 1.3 * @author Kara Kytle */ public abstract class SoundbankReader { - /** * Obtains a soundbank object from the URL provided. - * @param url URL representing the soundbank. + * + * @param url URL representing the soundbank. * @return soundbank object - * @throws InvalidMidiDataException if the URL does not point to - * valid MIDI soundbank data recognized by this soundbank reader + * @throws InvalidMidiDataException if the URL does not point to valid MIDI + * soundbank data recognized by this soundbank reader * @throws IOException if an I/O error occurs */ - public abstract Soundbank getSoundbank(URL url) throws InvalidMidiDataException, IOException; - + public abstract Soundbank getSoundbank(URL url) + throws InvalidMidiDataException, IOException; /** - * Obtains a soundbank object from the <code>InputStream</code> provided. - * @param stream <code>InputStream</code> representing the soundbank + * Obtains a soundbank object from the {@code InputStream} provided. + * + * @param stream {@code InputStream} representing the soundbank * @return soundbank object - * @throws InvalidMidiDataException if the stream does not point to - * valid MIDI soundbank data recognized by this soundbank reader + * @throws InvalidMidiDataException if the stream does not point to valid + * MIDI soundbank data recognized by this soundbank reader * @throws IOException if an I/O error occurs */ - public abstract Soundbank getSoundbank(InputStream stream) throws InvalidMidiDataException, IOException; - + public abstract Soundbank getSoundbank(InputStream stream) + throws InvalidMidiDataException, IOException; /** - * Obtains a soundbank object from the <code>File</code> provided. - * @param file the <code>File</code> representing the soundbank + * Obtains a soundbank object from the {@code File} provided. + * + * @param file the {@code File} representing the soundbank * @return soundbank object - * @throws InvalidMidiDataException if the file does not point to - * valid MIDI soundbank data recognized by this soundbank reader + * @throws InvalidMidiDataException if the file does not point to valid MIDI + * soundbank data recognized by this soundbank reader * @throws IOException if an I/O error occurs */ - public abstract Soundbank getSoundbank(File file) throws InvalidMidiDataException, IOException; - - - + public abstract Soundbank getSoundbank(File file) + throws InvalidMidiDataException, IOException; } |