QuickTime for Java: A Developer's Notebook

Opening and Closing the QuickTime Session

All QTJ applications are responsible for managing the QuickTime “session.” The call to QTSession.open( ) gives QuickTime an opportunity to initialize itself, and it must be made before any other QTJ call, or you’ll get an exception. Similarly, you must call QTSession.close( ) when you’re done with QuickTime to give it a chance to clean up.

In general, this means you might want to call QTSession.open( ) as early as possible and QTSession.close( ) as late as possible. The former is easy enough to do: just put it in your application’s entry point or even in a static initializer so that it precedes main( ). On the other hand, ensuring that you call QTSession.close( ) gracefully is trickier, because your user could quit your application with a menu item you provide, a Ctrl-C, a Cmd-Q (on Mac), or (heaven forbid) a kill -9 your-pid from the command line. Ideally, you’d like to have a fighting chance of properly closing QuickTime in as many cases as possible.

How do I do that?

One way to close QuickTime late is to put QTSession.close() in a Java shutdown hook, which will get called as the JVM goes away. There are no guarantees, but it’s better than nothing.

Note

You can also run this example with the provided ant run-ch01-qtversioncheck task.

You can use the class in Example 1-4 as a general-purpose session handler for QTJ. It is presented here so that none of the other examples in the book will need to explicitly handle opening or closing the QTSession beyond calling this class.

Example 1-4. Session handler for QuickTime for Java

package com.oreilly.qtjnotebook.ch01;

import quicktime.*;

public class QTSessionCheck {

  private Thread shutdownHook;
  private static QTSessionCheck instance;
  private QTSessionCheck( ) throws QTException {
      super( );
      // init
      QTSession.open( );
      // create shutdown handler
      shutdownHook = new Thread( ) {
              public void run( ) {
                  QTSession.close( );
              }
          };
      Runtime.getRuntime( ).addShutdownHook(shutdownHook);
  }
  private static QTSessionCheck getInstance( ) throws QTException {
      if (instance =  = null)
          instance = new QTSessionCheck( );
      return instance;
  }
  
  public static void check( ) throws QTException {
      // gets instance.  if a new one needs to be created,
      // it calls QTSession.open( ) and creates a shutdown hook
      // to call QTSession.close( )
      getInstance( );
  }
}

Warning

It looks like QTSession.close( ) hangs on some Windows installations. It might be safer to use QTSession.exitMovies( ).

What just happened?

The QTSessionHandler class uses a singleton pattern. The idea is that all the work is done in the constructor, which will be called only once (to create the singleton), so you’re free to call the static QTSessionHandler.check( ) method wherever and whenever you like, knowing it will have to run only once.

When you call check( ), it makes a trivial call to getInstance( ), which creates a new instance if and only if one hasn’t been created yet. The constructor calls QTSession.open( ) to initialize QuickTime, and then sets up a shutdown handler that will call QTSession.close( ) when Java is shutting down.

What about...

...managing the QTSession myself? Absolutely. If some other arrangement works for your application, go for it. This class is merely a convenience, and is arguably overkill—closing the QuickTime session is handled automatically on Mac OS X when you use the default Quit menu item, and I’ve never seen a problem that was definitely caused by improperly shutting down QuickTime on Windows. But, as this class shows, getting it right isn’t that hard.

...making multiple open( ) or close( ) calls? According to QTSession’s Javadocs, if you issue multiple open( ) calls, QuickTime won’t be shut down until an equal number of close( ) calls are received. There’s no benefit (or harm) to multiple open( ) calls, so this is probably just trivia.

Running inside an applet? In an applet, it might make more sense to put your open( ) and close() calls in the applet’s init( ) and destroy( ) methods, respectively, instead of banking on a particular browser’s behavior vis-à-vis taking down the entire JVM and executing shutdown hooks.