Date: Tue, 19 Mar 2002 19:10:46 GMT+00:00
From: "JDC Tech Tips" <body_11875236-1535423685@hermes.sun.com>
To: alexp@mit.edu
Message-Id: <11875236-1535423685@hermes.sun.com>
Subject: JDC Tech Tips, March 19, 2002 (Capturing Audio, Validating Deserialized Objects)
Precedence: junk
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

 J  D  C    T  E  C  H    T  I  P  S


                      TIPS, TECHNIQUES, AND SAMPLE CODE


WELCOME to the Java Developer Connection(sm) (JDC) Tech Tips, 
March 19, 2002. This issue covers:

         * Capturing audio with the Java(tm) Sound API 
         * Validating Deserialized Objects
         
These tips were developed using Java 2 SDK, Standard Edition, 
v 1.4. 

This issue of the JDC Tech Tips is written by John Zukowski, 
president of JZ Ventures, Inc. (http://www.jzventures.com).

You can view this issue of the Tech Tips on the Web at
http://java.sun.com/jdc/JDCTechTips/2002/tt0319.html

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
CAPTURING AUDIO WITH THE JAVA SOUND API

The Java Sound API has been a part of the standard libraries of 
the Java 2 Platform since the 1.3 release. Found in the 
javax.sound.sampled package, the Java Sound API provides support 
for playing and capturing audio. In addition, the library offers 
a software-based audio mixer and MIDI (Musical Instrument Digital 
Interface) device access. In this tip, you'll learn how to 
capture audio through the Java Sound API and play it back. 

The javax.sound.sampled package consists of eight interfaces, 
twelve top-level classes, twelve inner classes, and two 
exceptions. To record and play audio, you only need to deal with 
a total of seven parts of the package. 

Let's examine recording first. The basic recording process is as
follows:

Describe the audio format in which you want to record the data. 
This includes specifying the sampling rate and the number of 
channels (mono versus stereo) for the audio. You specify these 
properties using the aptly named AudioFormat class. There are two 
constructors for creating an AudioFormat object:

   AudioFormat(AudioFormat.Encoding encoding, 
    float sampleRate, int sampleSizeInBits, 
    int channels, int frameSize, float frameRate, 
    boolean bigEndian) 
    
   AudioFormat(float sampleRate, int sampleSizeInBits, 
    int channels, boolean signed, boolean bigEndian) 

The first constructor lets you explicitly set the audio format 
encoding, while the latter uses a default. The available 
encodings are ALAW, PCM_SIGNED, PCM_UNSIGNED, and ULAW. The 
default encoding used for the second constructor is PCM. Here
is an example that uses the second constructor to create
an AudioFormat object for single channel recording in 8 kHz 
format:

    float sampleRate = 8000;
    int sampleSizeInBits = 8;
    int channels = 1;
    boolean signed = true;
    boolean bigEndian = true;
    AudioFormat format =  new AudioFormat(sampleRate, 
      sampleSizeInBits, channels, signed, bigEndian);

After you describe the audio format, you need to get a DataLine.
This interface represents an audio feed from which you can 
capture the audio. You use a subinterface of DataLine to do the
actual capturing. The subinterface is called TargetDataLine. To 
get the TargetDataLine, you ask the AudioSystem. However when
you do that, you need to specify information about the line. You
make the specification in the form of a DataLine.Info object. In
particular, you need to create a DataLine.Info object that is
specific to the DataLine type and audio format. Here are some
lines of source that get the TargetDataLine.

  DataLine.Info info = new DataLine.Info(
    TargetDataLine.class, format);
  TargetDataLine line = (TargetDataLine)
    AudioSystem.getLine(info);

If the TargetDataLine is unavailable, a LineUnavailableException 
is thrown.

At this point you have your input source. You can think of the 
TargetDataLine like an input stream. However, it requires some 
setup before you can read form it. Setup in this case means first
opening the line using the open() method, and then initializing 
the line using the start() method:

  line.open(format);
  line.start();

Your data line is ready, so you can start recording from it as 
shown in the following lines of code. Here you save a captured 
audio stream to a byte array for later playing. You could also
save the audio stream to a file. Notice that you have to manage 
when to stop outside the read-loop construct.

  int bufferSize = (int)format.getSampleRate() * 
    format.getFrameSize();
  byte buffer[] = new byte[bufferSize];
  out = new ByteArrayOutputStream();
  while (externalTrigger) {
    int count = line.read(buffer, 0, buffer.length);
    if (count > 0) {
      out.write(buffer, 0, count);
    }
  }
  out.close();
  
Now let's examine playing audio. There are two key differences in
playing audio as compared to recording audio. First, when you 
play audio, the bytes come from an AudioInputStream instead of a 
TargetDataLine. Second, you write to a SourceDataLine instead of 
into a ByteArrayOutputStream. Besides that, the process is the 
same.

To get the AudioInputStream, you need to convert the 
ByteArrayOutputStream into the source of the AudioInputStream. 
The AudioInputStream constructor requires the bytes from the output 
stream, the audio format encoding used, and the number of sample 
frames:

  byte audio[] = out.toByteArray();
  InputStream input = new ByteArrayInputStream(audio);
  AudioInputStream ais = new AudioInputStream(input, 
    format, audio.length / format.getFrameSize());

Getting the DataLine is similar to the way you get it for audio
recording, but for playing audio, you need to fetch a 
SourceDataLine instead of a TargetDataLine:

  DataLine.Info info = new DataLine.Info(
                         SourceDataLine.class, format);
  SourceDataLine line = 
             (SourceDataLine)AudioSystem.getLine(info);

Setup for the line is identical to the setup for audio recording:

  line.open(format);
  line.start();

The last step is to play the audio as shown below. Notice that 
this step is similar to the last step in recording. However, here
you read from the buffer and write to the data line. There is 
also an added drain operation that works like a flush on an 
output stream.

  int bufferSize = (int) format.getSampleRate() 
    * format.getFrameSize();
  byte buffer[] = new byte[bufferSize];

  int count;
  while ((count = 
      ais.read(buffer, 0, buffer.length)) != -1) {
    if (count > 0) {
      line.write(buffer, 0, count);
    }
  }
  line.drain();
  line.close();

The following program puts these steps together to demonstrate
using the Java Sound the API to record and play audio. The 
program also presents a GUI. Press the Capture button to start 
recording the audio, the Stop button to stop recording, and
the Play button to play back the audio.

Note: Depending on the audio support your platform provides, you 
might need to change the format returned by the getFormat method
in the program. If you don't know what format is supported by 
your platform, download the demo program from the Java Sound Demo 
page, and run it. Click on the CapturePlayback tab, and find a 
set of format settings that work for you. You can load an audio 
file from the audio subdirectory, and then try various settings 
on the left until something works. Use those settings in the 
creation of the AudioFormat returned by getFormat().

import javax.swing.*;
import java.awt.*;
import java.awt.event.*;
import java.io.*;
import javax.sound.sampled.*;

public class Capture extends JFrame {

  protected boolean running;
  ByteArrayOutputStream out;

  public Capture() {
    super("Capture Sound Demo");
    setDefaultCloseOperation(EXIT_ON_CLOSE);
    Container content = getContentPane();

    final JButton capture = new JButton("Capture");
    final JButton stop = new JButton("Stop");
    final JButton play = new JButton("Play");

    capture.setEnabled(true);
    stop.setEnabled(false);
    play.setEnabled(false);

    ActionListener captureListener = 
        new ActionListener() {
      public void actionPerformed(ActionEvent e) {
        capture.setEnabled(false);
        stop.setEnabled(true);
        play.setEnabled(false);
        captureAudio();
      }
    };
    capture.addActionListener(captureListener);
    content.add(capture, BorderLayout.NORTH);

    ActionListener stopListener = 
        new ActionListener() {
      public void actionPerformed(ActionEvent e) {
        capture.setEnabled(true);
        stop.setEnabled(false);
        play.setEnabled(true);
        running = false;
      }
    };
    stop.addActionListener(stopListener);
    content.add(stop, BorderLayout.CENTER);

    ActionListener playListener = 
        new ActionListener() {
      public void actionPerformed(ActionEvent e) {
        playAudio();
      }
    };
    play.addActionListener(playListener);
    content.add(play, BorderLayout.SOUTH);
  }

  private void captureAudio() {
    try {
      final AudioFormat format = getFormat();
      DataLine.Info info = new DataLine.Info(
        TargetDataLine.class, format);
      final TargetDataLine line = (TargetDataLine)
        AudioSystem.getLine(info);
      line.open(format);
      line.start();
      Runnable runner = new Runnable() {
        int bufferSize = (int)format.getSampleRate() 
          * format.getFrameSize();
        byte buffer[] = new byte[bufferSize];
 
        public void run() {
          out = new ByteArrayOutputStream();
          running = true;
          try {
            while (running) {
              int count = 
                line.read(buffer, 0, buffer.length);
              if (count > 0) {
                out.write(buffer, 0, count);
              }
            }
            out.close();
          } catch (IOException e) {
            System.err.println("I/O problems: " + e);
            System.exit(-1);
          }
        }
      };
      Thread captureThread = new Thread(runner);
      captureThread.start();
    } catch (LineUnavailableException e) {
      System.err.println("Line unavailable: " + e);
      System.exit(-2);
    }
  }

  private void playAudio() {
    try {
      byte audio[] = out.toByteArray();
      InputStream input = 
        new ByteArrayInputStream(audio);
      final AudioFormat format = getFormat();
      final AudioInputStream ais = 
        new AudioInputStream(input, format, 
        audio.length / format.getFrameSize());
      DataLine.Info info = new DataLine.Info(
        SourceDataLine.class, format);
      final SourceDataLine line = (SourceDataLine)
        AudioSystem.getLine(info);
      line.open(format);
      line.start();

      Runnable runner = new Runnable() {
        int bufferSize = (int) format.getSampleRate() 
          * format.getFrameSize();
        byte buffer[] = new byte[bufferSize];
 
        public void run() {
          try {
            int count;
            while ((count = ais.read(
                buffer, 0, buffer.length)) != -1) {
              if (count > 0) {
                line.write(buffer, 0, count);
              }
            }
            line.drain();
            line.close();
          } catch (IOException e) {
            System.err.println("I/O problems: " + e);
            System.exit(-3);
          }
        }
      };
      Thread playThread = new Thread(runner);
      playThread.start();
    } catch (LineUnavailableException e) {
      System.err.println("Line unavailable: " + e);
      System.exit(-4);
    } 
  }

  private AudioFormat getFormat() {
    float sampleRate = 8000;
    int sampleSizeInBits = 8;
    int channels = 1;
    boolean signed = true;
    boolean bigEndian = true;
    return new AudioFormat(sampleRate, 
      sampleSizeInBits, channels, signed, bigEndian);
  }

  public static void main(String args[]) {
    JFrame frame = new Capture();
    frame.pack();
    frame.show();
  }
}

You can find a more complete example of using the Java Sound API 
at the Java Sound Demo page
(http://java.sun.com/products/java-media/sound/samples/JavaSoundDemo/).
That example also shows an oscilloscope of the sound wave as it 
is playing back.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VALIDATING DESERIALIZED OBJECTS

The serialization mechanism of the standard I/O libraries 
provides for reading and writing objects to byte streams. This 
saves the state of those objects so that you can later recreate
them. The basic serialization process was explained in a prior 
Tech Tip devoted to this topic (see
http://java.sun.com/jdc/TechTips/2000/tt0229.html). 

The basic object serialization process is sufficient for most 
needs. However, sometimes you need additional serialization 
capabilities. Fortunately, the serialization mechanism provides 
features that go beyond the basics. One of these additional 
features pertains to object validation. Object validation is
important because serialization allows an object state to be 
stored outside the runtime environment. This leads to the
question how can you be sure that the state you get back still 
represents a valid object? So you need to ensure that a 
object is in the proper state.

The way to ensure that a deserialized object is in the proper 
state is to register an ObjectInputValidation interface with the 
ObjectInputStream class. You do this through the 
registerValidation method of ObjectInputStream. The first 
parameter to the registerValidation method (the validator)
identifies the object that receives the validation callback.
The second parameter to the registerValidation method helps you 
order the validators if there are multiple validators present.

  public class TheClass implements Serializable {

    private void readObject(ObjectInputStream ois)
        throws ClassNotFoundException, IOException {
      ObjectInputValidation validator = ...;
      ois.registerValidation(validator, 0);
      ois.defaultReadObject();
    }
  }

This technique allows you to check the object state when an 
object is completely initialized (that is after it's read). 
Being completely initialized is important when the object being 
validated is subclassed. The validation happens after the 
subclass is initialized, not when the object is read using 
the readObject method of the parent.

The ObjectInputValidation interface includes a single method, 
validateObject, that throws an InvalidObjectException if the
validation fails. You don't have to catch this exception in the
readObject method. Instead, the framework that calls readObject 
passes the exception along when validation fails.

  public void validateObject() 
      throws InvalidObjectException {

    // Data fields are initialized
    if (! checkData()) {
      throw new InvalidObjectException(
        "Invalid data");
    }
  }

The following example demonstrates the object validation mechanism.
It also shows when the validation happens. The example provides a
serializable parent and child classes. The parent class has a 
registered validator. The validation is not complicated, it's
simply a check to see if the elements of a collection are of a 
specific type. The program serializes both a parent and child 
object without a validation error. Then the program tries to do 
the task again. The program fails in this second try due to a
validation error.

  import java.io.*;
  import java.util.*;
  import javax.swing.*;
  
  public class Parent implements Serializable, 
      ObjectInputValidation {
  
    List list;
    Class type;

    static class Child extends Parent {
  
      public Child(List data, Class datatype) {
        super(data, datatype);
      }
  
      private void readObject(ObjectInputStream ois)
          throws ClassNotFoundException, IOException {
        System.out.println("Reading Child");
        ois.defaultReadObject();
        System.out.println("Done Reading Child");
      }
  
      private void writeObject(ObjectOutputStream oos) 
          throws IOException {
        System.out.println("Writing Child");
        oos.defaultWriteObject();
      }
    }
  
    public Parent(List data, Class datatype) {
      list = data;
      type = datatype;
    }
  
    private void readObject(ObjectInputStream ois)
        throws ClassNotFoundException, IOException {
      System.out.println("Reading Parent");
      ois.registerValidation(this, 0);
      ois.defaultReadObject();
      System.out.println("Done Reading Parent");
    }
  
    private void writeObject(ObjectOutputStream oos) 
        throws IOException {
      System.out.println("Writing");
      oos.defaultWriteObject();
    }
    
    public void validateObject() 
        throws InvalidObjectException {
      System.out.println("Validating");
      Iterator it = list.iterator();
      while (it.hasNext()) {
        if (! type.isInstance(it.next())) {
          throw new InvalidObjectException(
            "Invalid type in collection");
        }
      }
    }
  
    public static void main(String args[])
        throws Exception {
      List aList = new ArrayList();
      aList.add(new JButton("Hello, "));
      aList.add(new JLabel("World"));
  
      Parent p = new Parent(aList, 
        javax.swing.JComponent.class);
      try {
        saveAndRestore(p, "parent.ser");
      } catch (InvalidObjectException e) {
        System.err.println(
          "Unable to restore parent/1");
      }
  
      System.out.println("----\n");
  
      Child c = new Child(aList, 
        javax.swing.JComponent.class);
      try {
        saveAndRestore(c, "child.ser");
      } catch (InvalidObjectException e) {
        System.err.println(
          "Unable to restore child/1");
      }
  
      System.out.println("----\n");
  
      aList.add("Problem");
    
      try {
        saveAndRestore(p, "parent2.ser");
      } catch (InvalidObjectException e) {
        System.err.println(
          "Unable to restore parent/2");
      }
  
      System.out.println("----\n");
  
      try {
        saveAndRestore(c, "child2.ser");
      } catch (InvalidObjectException e) {
        System.err.println(
          "Unable to restore child/2");
      }
    }
  
    private static Object saveAndRestore(
        Parent p, String filename) 
        throws IOException, ClassNotFoundException {
  
      FileOutputStream fos = 
        new FileOutputStream(filename);
      ObjectOutputStream oos = 
        new ObjectOutputStream(fos);
      oos.writeObject(p);
      oos.close();
  
      FileInputStream fis = 
        new FileInputStream(filename);
      ObjectInputStream ois = 
        new ObjectInputStream(fis);
      Object obj = ois.readObject();
      ois.close();
      return obj;
    }
  }

For more information on object serialization capabilities, 
including the new features in the J2SE(tm) 1.4 release, see 
the Object Serialization section of the Java 2 SDK, Standard
Edition Documentation
(http://java.sun.com/j2se/1.4/docs/guide/serialization/).

.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .

IMPORTANT: Please read our Terms of Use, Privacy, and Licensing 
policies:
http://www.sun.com/share/text/termsofuse.html
http://www.sun.com/privacy/ 
http://developer.java.sun.com/berkeley_license.html

* FEEDBACK
  Comments? Send your feedback on the JDC Tech Tips to: 
  jdc-webmaster@sun.com

* SUBSCRIBE/UNSUBSCRIBE
  - To subscribe, go to the subscriptions page,
    (http://developer.java.sun.com/subscription/), choose
    the newsletters you want to subscribe to and click "Update".
  - To unsubscribe, go to the subscriptions page,
    (http://developer.java.sun.com/subscription/), uncheck the
    appropriate checkbox, and click "Update".
  - To use our one-click unsubscribe facility, see the link at 
    the end of this email:
    
- ARCHIVES
You'll find the JDC Tech Tips archives at:

http://java.sun.com/jdc/TechTips/index.html


- COPYRIGHT
Copyright 2002 Sun Microsystems, Inc. All rights reserved.
901 San Antonio Road, Palo Alto, California 94303 USA.

This document is protected by copyright. For more information, see:

http://java.sun.com/jdc/copyright.html


JDC Tech Tips 
March 19, 2002

Sun, Sun Microsystems, Java, Java Developer Connection, and J2SE
are trademarks or registered trademarks of Sun Microsystems, Inc. 
in the United States and other countries.


To use our one-click unsubscribe facility, select the following URL:
http://bulkmail.sun.com/unsubscribe?11875236-1535423685