Summary

Provide an API variant of the exiting Font.createFont that will return all fonts in a TrueType font collection provided as a file or stream.

Problem

TrueType collections used to be rare, or available only pre-installed on a few OSes. Internally JDK handles those fine but the public API dating from 1999/2000 to load a font directly from a file or stream did not account for these.

Solution

Add new API which returns an array of Font.

Specification

   /**
     * Returns a new array of {@code Font} decoded from the specified stream.
     * The returned {@code Font[]} will have at least one element.
     * <p>
     * The explicit purpose of this overloading of the
     * {@code createFont(int, InputStream)} method is to support font
     * sources which represent a TrueType/OpenType font collection and
     * be able to return all individual fonts in that collection.
     * Consequently this method will throw {@code FontFormatException}
     * if the data source does not contain at least one TrueType/OpenType
     * font. The same exception will also be thrown if any of the fonts in
     * the collection does not contain the required font tables.
     * <p>
     * The condition "at least one", allows for the stream to represent
     * a single OpenType/TrueType font. That is, it does not have to be
     * a collection.
     * Each {@code Font} element of the returned array is
     * created with a point size of 1 and style {@link #PLAIN PLAIN}.
     * This base font can then be used with the {@code deriveFont}
     * methods in this class to derive new {@code Font} objects with
     * varying sizes, styles, transforms and font features.
     * <p>This method does not close the {@link InputStream}.
     * <p>
     * To make each {@code Font} available to Font constructors it
     * must be registered in the {@code GraphicsEnvironment} by calling
     * {@link GraphicsEnvironment#registerFont(Font) registerFont(Font)}.
     * @param fontStream an {@code InputStream} object representing the
     * input data for the font or font collection.
     * @return a new {@code Font[]}.
     * @throws FontFormatException if the {@code fontStream} data does
     *     not contain the required font tables for any of the elements of
     *     the collection, or if it contains no fonts at all.
     * @throws IOException if the {@code fontStream} cannot be completely read.
     * @see GraphicsEnvironment#registerFont(Font)
     * @since 9
     */

   public static Font[] createFonts(InputStream fontStream)
        throws FontFormatException, IOException);


    /**
     * Returns a new array of {@code Font} decoded from the specified file.
     * The returned {@code Font[]} will have at least one element.
     * <p>
     * The explicit purpose of this overloading of the
     * {@code createFont(int, File)} method is to support font
     * sources which represent a TrueType/OpenType font collection and
     * be able to return all individual fonts in that collection.
     * Consequently this method will throw {@code FontFormatException}
     * if the data source does not contain at least one TrueType/OpenType
     * font. The same exception will also be thrown if any of the fonts in
     * the collection does not contain the required font tables.
     * <p>
     * The condition "at least one", allows for the stream to represent
     * a single OpenType/TrueType font. That is, it does not have to be
     * a collection.
     * Each {@code Font} element of the returned array is
     * created with a point size of 1 and style {@link #PLAIN PLAIN}.
     * This base font can then be used with the {@code deriveFont}
     * methods in this class to derive new {@code Font} objects with
     * varying sizes, styles, transforms and font features.
     * <p>
     * To make each {@code Font} available to Font constructors it
     * must be registered in the {@code GraphicsEnvironment} by calling
     * {@link GraphicsEnvironment#registerFont(Font) registerFont(Font)}.
     * @param fontFile a {@code File} object containing the
     * input data for the font or font collection.
     * @return a new {@code Font[]}.
     * @throws FontFormatException if the {@code File} does
     *     not contain the required font tables for any of the elements of
     *     the collection, or if it contains no fonts at all.
     * @throws IOException if the {@code fontFile} cannot be read.
     * @see GraphicsEnvironment#registerFont(Font)
     * @since 9
     */
    public static Font[] createFonts(File fontFile)
            throws FontFormatException, IOException);