acm.util
Class MediaTools

java.lang.Object
  extended by acm.util.MediaTools

public class MediaTools
extends Object

This class implements a standard mechanism for loading images, sounds, and data files from the resources associated with a jar file.


Field Summary
static String DEFAULT_AUDIO_PATH
          The list of directories scanned for audio clips, separated by colons.
static String DEFAULT_DATAFILE_PATH
          The list of directories scanned for data files, separated by colons.
static String DEFAULT_IMAGE_PATH
          The list of directories scanned for images, separated by colons.
 
Method Summary
static void beep()
          This method sounds the audible alert on the console, which is typically a beep sound.
static AudioClip createAudioClip(InputStream in)
          Generates an audio clip from an input stream containing the data bytes for the audio clip.
static AudioClip createAudioClip(String[] hexData)
          Generates an audio clip from a string array that provides the sound values.
static BufferedImage createBufferedImage(Image image, int type)
          Creates a BufferedImage from the specified image.
static Image createImage(InputStream in)
          Generates an image from an input stream containing the data bytes for the image formatted in image/gif format.
static Image createImage(int[][] array)
          Generates an image from a two-dimensional array of pixel values.
static Image createImage(int[] pixels, int width, int height)
          Generates an image from a single-dimensional array of pixel values.
static Image createImage(String[] hexData)
          Generates an image from a string array that provides the pixel values.
static Image createPSPreviewImage(Image image, String[] preview)
          Creates a new image that combines an existing image with a PostScript preview represented as a string array.
static void defineAudioClip(String name, AudioClip clip)
          Inserts the given clip into the audio clip table under the specified name.
static void defineImage(String name, Image image)
          Inserts the given image into the image table under the specified name.
static void flushAudioClip(String name)
          Removes the audio clip with the given name from the cache, allowing it to be freed by the garbage collector.
static void flushImage(String name)
          Removes the image with the given name from the cache, allowing it to be freed by the garbage collector.
static InputStream getHexInputStream(String[] hexData)
          Returns an input stream whose bytes come from the string array hex, in which the elements consist of continuous bytes of hex data.
static Component getImageObserver()
          This method returns a new lightweight component suitable as an imageObserver.
static int[][] getPixelArray(Image image)
          Returns a two-dimensional array of the pixels in the image.
static boolean isCachingEnabled()
          This method returns the status of the flag that determins whether images and audio clips are cached internally by name, as described in setCachingEnabled.
static AudioClip loadAudioClip(String name)
          Searches the default audio clip search path for an audio clip with the specified name and then loads it to create an AudioClip.
static AudioClip loadAudioClip(String name, String path)
          Searches for an audio clip with the given name and loads it to create an AudioClip.
static AudioClip loadAudioClip(URL url)
          Loads an audio clip from the specified URL.
static AudioClip loadAudioClip(URL url, boolean topLevel)
          Loads an audio clip from the specified URL.
static Image loadImage(Image image)
          Makes sure that the image is fully loaded before returning.
static Image loadImage(String name)
          Searches the default image search path for an image with the specified name and then loads it to create an Image.
static Image loadImage(String name, String path)
          Searches for an image with the given name and loads it to create an Image.
static Image loadImage(URL url)
          Loads an image from the specified URL.
static Image loadImage(URL url, boolean topLevel)
          Loads an image from the specified URL.
static InputStream openDataFile(String name)
          Searches the default datafile search path for a file with the specified name and then opens it to create an InputStream.
static InputStream openDataFile(String name, String path)
          Searches for a data file with the given name and opens it to create an InputStream.
static InputStream openDataFile(URL url)
          Opens the specified URL to create an InputStream.
static InputStream openDataFile(URL url, boolean topLevel)
          Opens a data file using the specified URL.
static void saveImage(Image image, File file)
          Saves an image to the specified file.
static void saveImage(Image image, String filename)
          Saves an image to a file with the specified filename.
static void setCachingEnabled(boolean flag)
          This method sets an internal flag in the MediaTools package to indicate whether images and audio clips are cached internally by name.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_AUDIO_PATH

public static final String DEFAULT_AUDIO_PATH
The list of directories scanned for audio clips, separated by colons.

See Also:
Constant Field Values

DEFAULT_DATAFILE_PATH

public static final String DEFAULT_DATAFILE_PATH
The list of directories scanned for data files, separated by colons.

See Also:
Constant Field Values

DEFAULT_IMAGE_PATH

public static final String DEFAULT_IMAGE_PATH
The list of directories scanned for images, separated by colons.

See Also:
Constant Field Values
Method Detail

beep

public static void beep()
This method sounds the audible alert on the console, which is typically a beep sound.


createAudioClip

public static AudioClip createAudioClip(InputStream in)
Generates an audio clip from an input stream containing the data bytes for the audio clip. The implementation first tries to create a SoundClip object from the data. If that fails, it then backs up to the older strategy of using the SunAudioClip class.

Parameters:
in - An input stream containing the data
Returns:
An AudioClip object

createAudioClip

public static AudioClip createAudioClip(String[] hexData)
Generates an audio clip from a string array that provides the sound values.

Parameters:
hexData - A hex string array representing an audio clip
Returns:
An AudioClip object

createBufferedImage

public static BufferedImage createBufferedImage(Image image,
                                                int type)
Creates a BufferedImage from the specified image. The type parameter is used to specify the image type, as described in the BufferedImage documentation.

Parameters:
image - The original image
type - The type code used to describe the image model
A - BufferedImage containing the image data

createImage

public static Image createImage(InputStream in)
Generates an image from an input stream containing the data bytes for the image formatted in image/gif format.

Parameters:
in - An input stream containing the data
Returns:
An Image object

createImage

public static Image createImage(int[][] array)
Generates an image from a two-dimensional array of pixel values. As in standard image processing applications, the array is indexed so that the first subscript determines the row and the second determines the column.

Parameters:
array - A two-dimensional array of ints representing the pixels
Returns:
An Image object

createImage

public static Image createImage(int[] pixels,
                                int width,
                                int height)
Generates an image from a single-dimensional array of pixel values. The pixel array is stored in row-major order, which means that the pixels for the entire first row come before the pixels in the second row, and so on.

Parameters:
pixels - An array of ints representing the pixels
width - The width of the image
height - The height of the image
Returns:
An Image object

createImage

public static Image createImage(String[] hexData)
Generates an image from a string array that provides the pixel values.

Parameters:
hexData - A hex string array representing a .gif value
Returns:
An Image object

createPSPreviewImage

public static Image createPSPreviewImage(Image image,
                                         String[] preview)
Creates a new image that combines an existing image with a PostScript preview represented as a string array. Clients can retrieve the PostScript preview by asking for the "PSPreview" property.

Parameters:
image - The original image
preview - The corresponding PostScript preview
Returns:
A new image that includes the preview

defineAudioClip

public static void defineAudioClip(String name,
                                   AudioClip clip)
Inserts the given clip into the audio clip table under the specified name.

Parameters:
name - The name for the audio clip
clip - The audio clip to be stored in the table

defineImage

public static void defineImage(String name,
                               Image image)
Inserts the given image into the image table under the specified name.

Parameters:
name - The name for the image
image - The image to be stored in the table

flushAudioClip

public static void flushAudioClip(String name)
Removes the audio clip with the given name from the cache, allowing it to be freed by the garbage collector.

Parameters:
name - The name for the audio clip

flushImage

public static void flushImage(String name)
Removes the image with the given name from the cache, allowing it to be freed by the garbage collector.

Parameters:
name - The name for the image

getHexInputStream

public static InputStream getHexInputStream(String[] hexData)
Returns an input stream whose bytes come from the string array hex, in which the elements consist of continuous bytes of hex data.

Parameters:
hexData - An array of strings specifying a byte stream coded in hex
Returns:
An input stream for reading the bytes

getImageObserver

public static Component getImageObserver()
This method returns a new lightweight component suitable as an imageObserver.

Returns:
A new lightweight component suitable as an imageObserver.

getPixelArray

public static int[][] getPixelArray(Image image)
Returns a two-dimensional array of the pixels in the image. As in standard image processing applications, the array is indexed so that the first subscript determines the row and the second determines the column.

Parameters:
image - The image
Returns:
A two-dimensional array of pixels

isCachingEnabled

public static boolean isCachingEnabled()
This method returns the status of the flag that determins whether images and audio clips are cached internally by name, as described in setCachingEnabled.

Returns:
true if caching by name is enabled, false otherwise.

loadAudioClip

public static AudioClip loadAudioClip(String name)
Searches the default audio clip search path for an audio clip with the specified name and then loads it to create an AudioClip. The search process consists of the following steps:

  1. Check to see if an audio clip with that name has already been defined. If so, return that audio clip.

  2. Check to see if there is a resource available with that name whose contents can be read as an AudioClip. If so, read the audio clip from the resource file.

  3. Load the audio clip from a file with the specified name, relative to the application directory or the applet code base.

The second and third steps are repeated for each element of the audio clip search path, which consists of a list of directories separated by colons.

Parameters:
name - The name of the audio clip
Returns:
A new AudioClip object

loadAudioClip

public static AudioClip loadAudioClip(String name,
                                      String path)
Searches for an audio clip with the given name and loads it to create an AudioClip. Its operation is identical to the single-argument loadAudioClip call except in that this version allows the client to specify the search path explicitly.

Parameters:
name - The name of the audio clip
path - A string of directories names separated by colons
Returns:
A new AudioClip object

loadAudioClip

public static AudioClip loadAudioClip(URL url)
Loads an audio clip from the specified URL.

Parameters:
url - The url containing the audio clip
Returns:
A new AudioClip object

loadAudioClip

public static AudioClip loadAudioClip(URL url,
                                      boolean topLevel)
Loads an audio clip from the specified URL. The topLevel flag is false if this is invoked internally.


loadImage

public static Image loadImage(Image image)
Makes sure that the image is fully loaded before returning.

Parameters:
image - The Image which may not yet be loaded
Returns:
The same Image after ensuring that it is fully loaded

loadImage

public static Image loadImage(String name)
Searches the default image search path for an image with the specified name and then loads it to create an Image. The search process consists of the following steps:

  1. Check to see if an image with that name has already been defined. If so, return that image.

  2. Check to see if there is a resource available with that name whose contents can be read as an Image. If so, read the image from the resource file.

  3. Load the image from a file with the specified name, relative to the application directory or the applet code base.

The second and third steps are repeated for each element of the image search path, which consists of a list of directories separated by colons.

Unlike the getImage method in the Applet class, loadImage waits for an image to be fully loaded before returning.

Parameters:
name - The name of the image
Returns:
A fully loaded Image object

loadImage

public static Image loadImage(String name,
                              String path)
Searches for an image with the given name and loads it to create an Image. Its operation is identical to the single-argument loadImage call except in that this version allows the client to specify the search path explicitly.

Parameters:
name - The name of the image
path - A string of directories names separated by colons
Returns:
A fully loaded Image object

loadImage

public static Image loadImage(URL url)
Loads an image from the specified URL.

Parameters:
url - The url containing the image
Returns:
A fully loaded Image object

loadImage

public static Image loadImage(URL url,
                              boolean topLevel)
Loads an image from the specified URL. The topLevel flag is false if this is invoked internally.


openDataFile

public static InputStream openDataFile(String name)
Searches the default datafile search path for a file with the specified name and then opens it to create an InputStream. The search process consists of the following steps:

  1. Check to see if there is a resource available with that name. If so, return an InputStream open on that resource.

  2. Open the file with the specified name, relative to the application directory or the applet code base.

These steps are repeated for each element of the datafile search path, which consists of a list of directories separated by colons.

Parameters:
name - The name of the input file
Returns:
A new InputStream open on the specified file

openDataFile

public static InputStream openDataFile(String name,
                                       String path)
Searches for a data file with the given name and opens it to create an InputStream. Its operation is identical to the single-argument openDataFile call except in that this version allows the client to specify the search path explicitly.

Parameters:
name - The name of the audio clip
path - A string of directories names separated by colons
Returns:
A new InputStream open on the specified file

openDataFile

public static InputStream openDataFile(URL url)
Opens the specified URL to create an InputStream.

Parameters:
url - The URL of the data file
Returns:
A new InputStream open on the specified URL

openDataFile

public static InputStream openDataFile(URL url,
                                       boolean topLevel)
Opens a data file using the specified URL. The topLevel flag is false if this is invoked internally.


saveImage

public static void saveImage(Image image,
                             File file)
Saves an image to the specified file. The data format for the image file is determined by the suffix of the filename. If the suffix of the file is not recognized as a supported image type, calling this method generates an error.

Parameters:
image - The image
file - The File to which the image is saved

saveImage

public static void saveImage(Image image,
                             String filename)
Saves an image to a file with the specified filename. The data format for the image file is determined by the suffix of the filename. If the suffix of the file is not recognized as a supported image type, calling this method generates an error.

Parameters:
image - The image
filename - The name of the file to which the image is saved

setCachingEnabled

public static void setCachingEnabled(boolean flag)
This method sets an internal flag in the MediaTools package to indicate whether images and audio clips are cached internally by name. This flag is disabled by default.

Parameters:
flag - true to enable caching by name, false to disable it.