COM4J (com4j Parent 2.1 API)

java.lang.Object
- com4j.COM4J

```
public abstract class COM4J
extends Object
```
The root of the COM4J library.
Provides various global services that don't fit into the rest of classes.

Author:

Kohsuke Kawaguchi (kk@kohsuke.org), Michael Schnell (ScM, (C) 2008, 2009 Michael-Schnell@gmx.de)

Field Summary

Fields
Modifier and Type	Field and Description
`protected static List<Runnable>`	`applicationShutdownTasks` List of application defined task, they are executed _before_ com4j shuts down.
`protected static List<Runnable>`	`com4JShutdownTasks` List of shutdown task defined by Com4J itself.
`static GUID`	`IID_IDispatch` GUID of IDispatch.
`static GUID`	`IID_IFont` IID of IFont
`static GUID`	`IID_IFontDisp` IID of IFontDisp
`static GUID`	`IID_IPicture` IID of IPicture
`static GUID`	`IID_IPictureDisp` IID of IPictureDisp
`static GUID`	`IID_IUnknown` GUID of IUnknown.

Method Summary

Methods
Modifier and Type	Method and Description
`static void`	`addListener(ComObjectListener listener)` Registers a `ComObjectListener` to the current thread.
`static void`	`addShutdownTask(Runnable task)` Add a shutdown task.
`static void`	`cleanUp()` Cleans up COM resources for the current thread.
`static ByteBuffer`	`createBuffer(long ptr, int size)` Maps the memory region into `ByteBuffer` so that it can be then accessed nicely from Java code.
`static <T extends Com4jObject> T`	`createInstance(Class<T> primaryInterface, GUID clsid)` Creates a new COM object of the given CLSID and returns it in a wrapped interface.
`static <T extends Com4jObject> T`	`createInstance(Class<T> primaryInterface, String clsid)` Creates a new COM object of the given CLSID and returns it in a wrapped interface.
`static <T extends Com4jObject> T`	`createInstance(Class<T> primaryInterface, String clsid, int clsctx)` Creates a new COM object of the given CLSID and returns it in a wrapped interface.
`static <T extends Com4jObject> T`	`getActiveObject(Class<T> primaryInterface, GUID clsid)` Gets an already running object from the running object table.
`static <T extends Com4jObject> T`	`getActiveObject(Class<T> primaryInterface, String clsid)` Gets an already object from the running object table.
`static GUID`	`getIID(Class<?> _interface)` Gets the interface GUID associated with the given interface.
`static <T extends Com4jObject> T`	`getObject(Class<T> primaryInterface, String fileName, String progId)` Returns a reference to a COM object primarily by loading a file.
`static ROT`	`getROT()` Returns the singleton ROT instance.
`static Com4jObject`	`loadTypeLibrary(File typeLibraryFile)` Loads a type library from a given file and returns its IUnknown.
`static void`	`removeListener(ComObjectListener listener)` Removes a registered `ComObjectListener` from the current thread.
`static boolean`	`removeShutdownTask(Runnable task)` Remove an already registered shutdown task
`static <T extends Com4jObject> T`	`wrap(Class<T> primaryInterface, long ptr)` Wraps an externally obtained interface pointer into a COM wrapper object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - IID_IUnknown
```
public static final GUID IID_IUnknown
```
    GUID of IUnknown.
  - IID_IDispatch
```
public static final GUID IID_IDispatch
```
    GUID of IDispatch.
  - IID_IPicture
```
public static final GUID IID_IPicture
```
    IID of IPicture
  - IID_IPictureDisp
```
public static final GUID IID_IPictureDisp
```
    IID of IPictureDisp
  - IID_IFont
```
public static final GUID IID_IFont
```
    IID of IFont
  - IID_IFontDisp
```
public static final GUID IID_IFontDisp
```
    IID of IFontDisp
  - applicationShutdownTasks
```
protected static final List<Runnable> applicationShutdownTasks
```
    List of application defined task, they are executed _before_ com4j shuts down.
  - com4JShutdownTasks
```
protected static final List<Runnable> com4JShutdownTasks
```
    List of shutdown task defined by Com4J itself.
- Method Detail
  - createInstance
```
public static <T extends Com4jObject> T createInstance(Class<T> primaryInterface,
                                       GUID clsid)
                                            throws ComException
```
    Creates a new COM object of the given CLSID and returns it in a wrapped interface.
    
    Type Parameters:
    T - the type of the return value and the type parameter of the class object of primaryInterface
    Parameters:
    primaryInterface - The created COM object is returned as this interface. Must be non-null. Passing in Com4jObject allows the caller to create a new instance without knowing its primary interface.
    clsid - The CLSID of the COM object to be created. Must be non-null.
    
    Returns:
    non-null valid object.
    
    Throws:
    
    ComException - if the instantiation fails.
  - createInstance
```
public static <T extends Com4jObject> T createInstance(Class<T> primaryInterface,
                                       String clsid)
                                            throws ComException
```
    Creates a new COM object of the given CLSID and returns it in a wrapped interface.
    
    Type Parameters:
    T - the type of the return value and the type parameter of the class object of primaryInterface
    Parameters:
    primaryInterface - The created COM object is returned as this interface. Must be non-null. Passing in Com4jObject allows the caller to create a new instance without knowing its primary interface.
    clsid - The CLSID of the COM object in the "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" format, or the ProgID of the object (like "Microsoft.XMLParser.1.0")
    
    Returns:
    non-null valid object.
    
    Throws:
    
    ComException - if the instantiation fails.
  - createInstance
```
public static <T extends Com4jObject> T createInstance(Class<T> primaryInterface,
                                       String clsid,
                                       int clsctx)
                                            throws ComException
```
    Creates a new COM object of the given CLSID and returns it in a wrapped interface.
    Compared to createInstance(Class,String), this method allows the caller to specify CLSCTX_XXX constants to control the server instantiation.
    
    Type Parameters:
    T - the type of the return value and the type parameter of the class object of primaryInterface
    Parameters:
    primaryInterface - type parameter of the primaryInterface type
    clsid - a string representation of the class id
    clsctx - Normally this is CLSCTX.ALL, but can be any combination of CLSCTX constants.
    
    Returns:
    the new instance of the COM object
    
    Throws:
    
    ComException - if an error occurred in the native COM part
    See Also:
    CLSCTX
  - wrap
```
public static <T extends Com4jObject> T wrap(Class<T> primaryInterface,
                             long ptr)
                                  throws ComException
```
    Wraps an externally obtained interface pointer into a COM wrapper object.
    This method doesn't call addRef on the given interface pointer. Instead, this method takes over the ownership of the given pointer.
    
    Parameters:
    primaryInterface - The interface type to wrap the pointer into.
    ptr - The rar interface pointer value.
    
    Throws:
    
    ComException
  - getActiveObject
```
public static <T extends Com4jObject> T getActiveObject(Class<T> primaryInterface,
                                        GUID clsid)
```
    Gets an already running object from the running object table.
    
    Type Parameters:
    T - the type of the return value and the type parameter of the class object of primaryInterface
    Parameters:
    primaryInterface - The returned COM object is returned as this interface. Must be non-null. Passing in Com4jObject allows the caller to create a new instance without knowing its primary interface.
    clsid - The CLSID of the object to be retrieved.
    
    Returns:
    the retrieved object
    
    Throws:
    
    ComException - if the retrieval fails.
    See Also:
    MSDN documentation
  - getActiveObject
```
public static <T extends Com4jObject> T getActiveObject(Class<T> primaryInterface,
                                        String clsid)
```
    Gets an already object from the running object table.
    
    Type Parameters:
    T - the type of the return value and the type parameter of the class object of primaryInterface
    Parameters:
    primaryInterface - The returned COM object is returned as this interface. Must be non-null. Passing in Com4jObject allows the caller to create a new instance without knowing its primary interface.
    clsid - The CLSID of the COM object to be retrieved, in the "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" format, or the ProgID of the object (like "Microsoft.XMLParser.1.0")
    
    Returns:
    non-null valid object.
    
    Throws:
    
    ComException - if the retrieval fails.
    See Also:
    getActiveObject(Class,GUID)
  - getObject
```
public static <T extends Com4jObject> T getObject(Class<T> primaryInterface,
                                  String fileName,
                                  String progId)
```
    Returns a reference to a COM object primarily by loading a file.
    This method implements the semantics of the GetObject Visual Basic function. See MSDN reference for its semantics.
    This function really has three different mode of operation:
    - If both fileName and progId are specified, a COM object of the given progId is created and its state is loaded from the given file name. This is normally used to activate a OLE server by loading a file.
    - If just fileName is specified, it is treated as a moniker. The moniker will be bound and the resulting COM object will be returned. In a simple case a moniker is a file path, in which case the associated application is activated and loads the data. But monikers in OLE are extensible, so in more general case the semantics really depends on the moniker provider.
    - If just progId is specified, this method would just work like getActiveObject(Class, String).
    Type Parameters:
    T - the type of the return value and the type parameter of the class object of primaryInterface
    Parameters:
    primaryInterface - The returned COM object is returned as this interface. Must be non-null. Passing in Com4jObject allows the caller to create a new instance without knowing its primary interface.
    fileName - path to the file
    progId - the progID in string representation
    
    Returns:
    non-null valid object.
    
    Throws:
    
    ComException - if the retrieval fails.
  - getROT
```
public static ROT getROT()
```
    Returns the singleton ROT instance.
    
    Returns:
    the singleton ROT instance
  - getIID
```
public static GUID getIID(Class<?> _interface)
```
    Gets the interface GUID associated with the given interface.
    This method retrieves the associated IID annotation from the interface and return it.
    
    Parameters:
    _interface - reference to an object that has the IID annotation.
    
    Returns:
    always return no-null valid GUID object.
    
    Throws:
    
    IllegalArgumentException - if the interface doesn't have any IID annotation.
  - loadTypeLibrary
```
public static Com4jObject loadTypeLibrary(File typeLibraryFile)
```
    Loads a type library from a given file and returns its IUnknown.
    Exposed for tlbimp.
    
    Parameters:
    typeLibraryFile - the path to the file containing the type library
    
    Returns:
    reference to the type library object
  - createBuffer
```
public static ByteBuffer createBuffer(long ptr,
                      int size)
```
    Maps the memory region into ByteBuffer so that it can be then accessed nicely from Java code.
    When bridging native code to Java, it's often necessary to be able to read/write arbitrary portion of the memory, and this method lets you do that.
    Neither this code nor ByteBuffer does anything about making sure that the memory region pointed by ptr remains valid. It's the caller's responsibility.
    
    Parameters:
    ptr - The pointer value that points to the top of the buffer.
    size - The size of the memory region to be mapped to ByteBuffer.
    
    Returns:
    always non-null valid ByteBuffer.
    See Also:
    "http://java.sun.com/j2se/1.4.2/docs/guide/jni/jni-14.html#NewDirectByteBuffer"
  - addListener
```
public static void addListener(ComObjectListener listener)
```
    Registers a ComObjectListener to the current thread.
    The registered listener will receive a notification each time a new proxy is created.
    
    Parameters:
    listener - the listener to be added
    
    Throws:
    
    IllegalArgumentException - If the listener is null or it is already registered.
    See Also:
    removeListener(ComObjectListener)
  - removeListener
```
public static void removeListener(ComObjectListener listener)
```
    Removes a registered ComObjectListener from the current thread.
    
    Parameters:
    listener - the listener to remove.
    
    Throws:
    
    IllegalArgumentException - if the listener is not currently registered.
    See Also:
    addListener(ComObjectListener)
  - cleanUp
```
public static void cleanUp()
```
    Cleans up COM resources for the current thread.
    This method can be invoked explicitly by a thread that used COM objects, to clean up resources, such as references to out-of-process COM objects.
    In COM terminology, this effectively amounts to calling CoUninitialize. After this method is invoked, a thread can still go use other COM resources.
  - addShutdownTask
```
public static void addShutdownTask(Runnable task)
```
    Add a shutdown task.
    Com4J adds a shutdown hook to the java runtime. As soon as the java runtime shuts down, Com4J shuts down, too. To enable the developer to release external resources, accessed via Com4J, such as an automation server object that is running in the background, this method provides a mechanism to add shutdown tasks, that are executed before Com4J really shuts down.
    
    Do not add your own shutdown hooks to the java runtime to do such things, because it is likely that the com4j shutdown hook is running first, and then you can't access the resources any more.
    
    Tasks are executed sequential in LIFO order.
    
    Parameters:
    task - The task to be executed before Com4J shuts down.
  - removeShutdownTask
```
public static boolean removeShutdownTask(Runnable task)
```
    Remove an already registered shutdown task
    
    Parameters:
    task - The task that is to remove from the list.
    
    Returns:
    true if the task was registered.

Class COM4J

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

IID_IUnknown

IID_IDispatch

IID_IPicture

IID_IPictureDisp

IID_IFont

IID_IFontDisp

applicationShutdownTasks

com4JShutdownTasks

Method Detail

createInstance

createInstance

createInstance

wrap

getActiveObject

getActiveObject

getObject

getROT

getIID

loadTypeLibrary

createBuffer

addListener

removeListener

cleanUp

addShutdownTask

removeShutdownTask