1 /* 2 * Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sound.midi.spi; 27 28 import java.io.File; 29 import java.io.IOException; 30 import java.io.OutputStream; 31 import java.util.Arrays; 32 33 import javax.sound.midi.Sequence; 34 35 /** 36 * A {@code MidiFileWriter} supplies MIDI file-writing services. Classes that 37 * implement this interface can write one or more types of MIDI file from a 38 * {@link Sequence} object. 39 * 40 * @author Kara Kytle 41 * @since 1.3 42 */ 43 public abstract class MidiFileWriter { 44 45 /** 46 * Constructs a {@code MidiFileWriter}. 47 */ 48 protected MidiFileWriter() {} 49 50 /** 51 * Obtains the set of MIDI file types for which file writing support is 52 * provided by this file writer. 53 * 54 * @return array of file types. If no file types are supported, an array of 55 * length 0 is returned. 56 */ 57 public abstract int[] getMidiFileTypes(); 58 59 /** 60 * Obtains the file types that this file writer can write from the sequence 61 * specified. 62 * 63 * @param sequence the sequence for which MIDI file type support is queried 64 * @return array of file types. If no file types are supported, returns an 65 * array of length 0. 66 * @throws NullPointerException if {@code sequence} is {@code null} 67 */ 68 public abstract int[] getMidiFileTypes(Sequence sequence); 69 70 /** 71 * Indicates whether file writing support for the specified MIDI file type 72 * is provided by this file writer. 73 * 74 * @param fileType the file type for which write capabilities are queried 75 * @return {@code true} if the file type is supported, otherwise 76 * {@code false} 77 */ 78 public boolean isFileTypeSupported(final int fileType) { 79 return Arrays.stream(getMidiFileTypes()) 80 .anyMatch(type -> fileType == type); 81 } 82 83 /** 84 * Indicates whether a MIDI file of the file type specified can be written 85 * from the sequence indicated. 86 * 87 * @param fileType the file type for which write capabilities are queried 88 * @param sequence the sequence for which file writing support is queried 89 * @return {@code true} if the file type is supported for this sequence, 90 * otherwise {@code false} 91 * @throws NullPointerException if {@code sequence} is {@code null} 92 */ 93 public boolean isFileTypeSupported(final int fileType, 94 final Sequence sequence) { 95 return Arrays.stream(getMidiFileTypes(sequence)) 96 .anyMatch(type -> fileType == type); 97 } 98 99 /** 100 * Writes a stream of bytes representing a MIDI file of the file type 101 * indicated to the output stream provided. 102 * 103 * @param in sequence containing MIDI data to be written to the file 104 * @param fileType type of the file to be written to the output stream 105 * @param out stream to which the file data should be written 106 * @return the number of bytes written to the output stream 107 * @throws IOException if an I/O exception occurs 108 * @throws IllegalArgumentException if the file type is not supported by 109 * this file writer 110 * @throws NullPointerException if {@code in} or {@code out} are 111 * {@code null} 112 * @see #isFileTypeSupported(int, Sequence) 113 * @see #getMidiFileTypes(Sequence) 114 */ 115 public abstract int write(Sequence in, int fileType, OutputStream out) 116 throws IOException; 117 118 /** 119 * Writes a stream of bytes representing a MIDI file of the file type 120 * indicated to the external file provided. 121 * 122 * @param in sequence containing MIDI data to be written to the external 123 * file 124 * @param fileType type of the file to be written to the external file 125 * @param out external file to which the file data should be written 126 * @return the number of bytes written to the file 127 * @throws IOException if an I/O exception occurs 128 * @throws IllegalArgumentException if the file type is not supported by 129 * this file writer 130 * @throws NullPointerException if {@code in} or {@code out} are 131 * {@code null} 132 * @see #isFileTypeSupported(int, Sequence) 133 * @see #getMidiFileTypes(Sequence) 134 */ 135 public abstract int write(Sequence in, int fileType, File out) 136 throws IOException; 137 }