QuickTime for Java: A Developer's Notebook

Compiling QTJ Code

Once you’ve installed QuickTime and QuickTime for Java, you have everything you need to start developing QTJ applications—no separate SDK is required.

How do I do that?

You can begin by compiling a trivial application to check the QuickTime and QTJ versions, as shown in Example 1-3.

Example 1-3. Checking the version of QuickTime

package com.oreilly.qtjnotebook.ch01;
  
import quicktime.QTSession;
import quicktime.util.QTBuild;
  
public class QTVersionCheck {
  
  public static void main (String[  ] args) {
      try {
          QTSession.open( );
          System.out.println ("QT version: " +
              QTSession.getMajorVersion( ) +
              "." +
              QTSession.getMinorVersion( ));
          System.out.println ("QTJ version: " +
              QTBuild.getVersion( ) +
              "." +
              QTBuild.getSubVersion( ));
          QTSession.close( );
      } catch (Exception e) {
          e.printStackTrace( );
      }
  }
  
}

The compilation is the tricky step here. If you do a straightforward javac, bad things happen:

cadamson% javac src/com/oreilly/qtjnotebook/ch01/QTVersionCheck.java
src/com/oreilly/qtjnotebook/ch01/QTVersionCheck.java:3:
  package quicktime does not exist
import quicktime.QTSession;
               ^
src/com/oreilly/qtjnotebook/ch01/QTVersionCheck.java:4:
  package quicktime.util does not exist
import quicktime.util.QTBuild;
                    ^
src/com/oreilly/qtjnotebook/ch01/QTVersionCheck.java:10:
  cannot resolve symbol
symbol  : variable QTSession 
location: class com.oreilly.qtjnotebook.ch01.QTVersionCheck
          QTSession.open( );
          ^

Instead, you have to explicitly provide the path to QTJava.zip, which contains the QTJ classes. On the Mac OS X command line, you would do this as follows:

Note

Here, as in many examples, you should type the entire command on one line. It’s broken up in the text for printing purposes.

cadamson% javac -classpath /System/Library/Java/Extensions/QTJava.zip 
  src/com/oreilly/qtjnotebook/ch01/QTVersionCheck.java

On Windows, the path to QTJava.zip would point to wherever the QuickTime installer put the file, which presumably means into your Java installation’s lib/ext:

C:\qtjtests\book stuff\code>javac -classpath
  "c:\Program Files\Java\j2re1.4.2\lib\ext\QTJava.zip"
  src\com\oreilly\qtjnotebook\ch01\QTVersionCheck.java

Once the code compiles, running it is a lot easier—you don’t need to explicitly put QTJava.zip in the runtime classpath to run a QTJ application. Just supply the class name to run, as the following output illustrates:

Note

Using the ant buildfile provided with the downloaded book code (and described in the Preface) makes compiling a lot easier!

cadamson% java -cp classes com.oreilly.qtjnotebook.ch01.QTVersionCheck
QT version: 6.5
QTJ version: 6.1
cadamson%

What just happened?

As for what this trivial first application actually does, a read-through of the main( ) method shows it doing four things:

1. Opening the QuickTime session

2. Printing the QuickTime version by making calls to quicktime.QTSession

3. Printing the QuickTime for Java version by making calls to quicktime.util.QTBuild

4. Closing the QuickTime session

If any of these throws an exception, it’s caught and printed to standard-out.

What about...

...the mismatch between the version numbers? QuickTime and QuickTime for Java versions are somewhat independent, because not every QT update merits a QTJ update. Typically, you’ll see both roll out a major version at the same time, but then a number of QuickTime updates will be issued, usually bug-fix updates or minor feature releases, without any changes to QTJ.

The Latest and Greatest

This book covers QTJ 6.1, which was released alongside QuickTime 6.4. If your software reports a lower version, be sure to update with the QuickTime Updater because QTJ 6.1 has massive differences from previous versions, and this book covers only QTJ 6.1.

How different is QTJ 6.1 from its predecessors? Try “every QTJ application broke with 6.1.”

The problem was caused by Apple changing the internals of its Java implementation from the Carbon framework to Cocoa for its Java 1.4 implementation. QTJ was heavily dependent on Carbon for its native binding, and a full-blown rewrite for Cocoa was impractical.

However, only the parts involving the AWT/Swing bridge were affected—most of QTJ still worked just fine. So, Apple rolled out a radically simplified GUI layer for QTJ in the new quicktime.app.view package. All the incompatible packages, particularly quicktime.app.display and its subpackages, were deprecated. A few nice-to-have features, like live-video compositing, weren’t ported to 6.1.

QTJ 6.1 can be used on Mac OS X with either Java 1.4 or Java 1.3, and on Windows. Earlier versions work on Windows and with Java 1.3 on Mac OS X, but will throw runtime exceptions with Java 1.4.

Parts of Apple’s web site and older books still cover the old API. If you see code that uses quicktime.app.display, or any of its classes (like QTCanvas, SGDrawer, or SWCompositor), beware: it won’t work on Java 1.4 on Mac OS X and won’t be supported going forward. These packages are also in the Javadocs, but they’re clearly marked as deprecated.