org.isis.jaut
Class Apartment

java.lang.Object
  extended byorg.isis.jaut.Apartment

public class Apartment
extends java.lang.Object

The Apartment class represents a COM Apartment, and its Threads, in a Java application.


Field Summary
protected static int COINIT_APARTMENTTHREADED
          A flag for apartment-threaded concurrency.
protected static int COINIT_DISABLE_OLE1DDE
          A flag that disables DDE for OLE1.
protected static int COINIT_MULTITHREADED
          A flag for multi-threaded concurrency.
protected static int COINIT_SPEED_OVER_MEMORY
          A flag for trading memory for speed, if possible.
protected static Apartment multiThreadedApartment
          The single multi threaded apartment of the process, if any.
protected  java.util.LinkedList threads
          The list of threads that entered this apartment.
 
Constructor Summary
protected Apartment()
          Constructs an Apartment.
 
Method Summary
protected static void coInitialize(int coInit)
          Initialize the COM library for the calling Thread.
protected static void coUninitialize()
          Uninitialize the COM library for the calling Thread.
static Apartment currentApartment()
          Returns the current Apartment for this Thread.
static Apartment enter(boolean multiThreaded)
          Makes the current Thread enter an Apartment.
static Apartment getMultiThreadedApartment()
          Retrives the multi threaded apartment (MTA) of the process.
 java.util.LinkedList getThreads()
          Returns the list of threads in this Apartment.
static void leave()
          Makes the current Thread leave its Apartment.
static void releaseObjects()
          Releases all COM resources that were finalized from Threads that are not in the current Apartment.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COINIT_APARTMENTTHREADED

protected static final int COINIT_APARTMENTTHREADED
A flag for apartment-threaded concurrency.

See Also:
coInitialize(int), Constant Field Values

COINIT_MULTITHREADED

protected static final int COINIT_MULTITHREADED
A flag for multi-threaded concurrency.

See Also:
coInitialize(int), Constant Field Values

COINIT_DISABLE_OLE1DDE

protected static final int COINIT_DISABLE_OLE1DDE
A flag that disables DDE for OLE1.

See Also:
coInitialize(int), Constant Field Values

COINIT_SPEED_OVER_MEMORY

protected static final int COINIT_SPEED_OVER_MEMORY
A flag for trading memory for speed, if possible.

See Also:
coInitialize(int), Constant Field Values

threads

protected java.util.LinkedList threads
The list of threads that entered this apartment.


multiThreadedApartment

protected static Apartment multiThreadedApartment
The single multi threaded apartment of the process, if any.

See Also:
getMultiThreadedApartment()
Constructor Detail

Apartment

protected Apartment()
Constructs an Apartment. Use the public enter(boolean) method the create and enter apartments.

Method Detail

coInitialize

protected static void coInitialize(int coInit)
                            throws ComException
Initialize the COM library for the calling Thread. It sets the Thread concurrency model. This function is a direct wrapper around the CoInitializeEx COM function. Every succesfull invocation must be matched by a coUninitialize() call. Do not use coInitialize directly, use enter(boolean) instead.

Parameters:
coInit - the requested concurreny model. Acceptable values are combined from the COINIT_XXX constants.
Throws:
ComException - if CoInitializeEx fails.
See Also:
coUninitialize(), enter(boolean)

coUninitialize

protected static void coUninitialize()
Uninitialize the COM library for the calling Thread. This function is a direct wrapper around the CoUninitialize COM function. Do not use coUninitialize directly, use leave() instead.

See Also:
coInitialize(int), leave()

currentApartment

public static Apartment currentApartment()
Returns the current Apartment for this Thread.

Returns:
the Apartment that this Thread enetered, or null if this Thread is not part of any Apartment.

getThreads

public java.util.LinkedList getThreads()
Returns the list of threads in this Apartment.

Returns:
the list of threads that entered this Apartment.

enter

public static Apartment enter(boolean multiThreaded)
Makes the current Thread enter an Apartment. If multiThreaded is true, then this thread enters the only multi threaded apartment of the process. Otherwise, a new single threaded apartment is created. A Thread can enter at most one Apartment. If a Thread is not part of any Apartment, then it cannot call any Automation functions. It is the responsibility of the caller to make sure that all Automation objects created by threads of this Apartment are finalized (garbage collected), and then to call leave() before the last Thread of this Apartment dies. Otherwise, some COM references and other resources might not get released.

Parameters:
multiThreaded - true if the multi threaded apartment is requested (COINIT_MULTITHREADED), false otherwise (COINIT_APARTMENTTHREADED).
Returns:
the Apartment this Thread enetered.
Throws:
JAutException - if this Thread is already part of an apartment
ComException - if coInitialize(int) fails. This indicates that this thread is already part of a COM apartment (entered without using this method), and the current apartment uses a different concurrency model than the one requested now.
See Also:
leave(), coInitialize(int)

leave

public static void leave()
Makes the current Thread leave its Apartment. If this Thread is the last one in the Apartment, calls the garbage collector to try to finalize the remaining ApartmentObject objects. Then calls releaseObjects(). This method makes the best effort to free all COM resources before calling coUninitialize().

Throws:
JAutException - if the current Thread is not part of an Apartment.
JAutException - if this thread is the last thread of its Apartment, and there are Automation objects created in this thread that are not yet finalized.
See Also:
enter(boolean), ApartmentObject.release()

releaseObjects

public static void releaseObjects()
Releases all COM resources that were finalized from Threads that are not in the current Apartment. Calls the ApartmentObject.release() method on all objects that were registered by #registerRelease.


getMultiThreadedApartment

public static Apartment getMultiThreadedApartment()
Retrives the multi threaded apartment (MTA) of the process.

Returns:
the single multi threaded apartment of the process, or null if no Java thread is part of the MTA.