com4j

Interface Com4jObject

All Known Subinterfaces:

ICoClassDecl, IConstant, IDispInterfaceDecl, IEnumDecl, IEnumVARIANT, IFont, IFontDisp, IImplementedInterfaceDecl, IInterface, IInterfaceDecl, IMethod, IParam, IPicture, IPictureDisp, IPrimitiveType, IProperty, IPtrType, ISafeArrayType, IType, ITypeDecl, ITypedefDecl, IWTypeLib

public interface Com4jObject

Root of all the com4j interfaces.

Java interfaces mapped from COM interfaces always derive from this interface directly/indirectly. This interface provides methods that are common to all the COM interfaces.

Author:

Kohsuke Kawaguchi (kk@kohsuke.org)

Method Summary

Methods

Modifier and Type	Method and Description
<T> EventCookie	advise(Class<T> eventInterface, T receiver) Subscribes to the given event interface of this object.
void	dispose() Releases a reference to the wrapped COM object.
boolean	equals(Object o) Tests the identity of two COM objects.
ComThread	getComThread() Every Com4jObject has a ComThread that is running handling all the calls to this object.
long	getIUnknownPointer() QueryInterface to IUnknown and return its raw pointer value.
long	getPointer() Returns the interface pointer as an integer
int	getPtr() Deprecated. 64bit unasfe.
int	hashCode() Hash code consistent with equals(java.lang.Object) }.
<T extends Com4jObject> boolean	is(Class<T> comInterface) Checks if this COM object implements a given interface.
<T extends Com4jObject> T	queryInterface(Class<T> comInterface) Invokes the queryInterface of the wrapped COM object and attempts to obtain a different interface of the same object.
void	setName(String name) You can use this function to set a name to an object.
String	toString() Prints the raw interface pointer that this object represents.

Method Detail

equals

boolean equals(Object o)

Tests the identity of two COM objects.

This consists of doing IUnknown::QueryInterface on two interfaces and test the bit image of the resulting IUnknown*.

If one COM object implements two interfaces, in Java you see them as two different objects. Thus you cannot rely on == to check if they represent the same COM object.

Overrides:

equals in class Object

Parameters:

o - the other Com4jObject

Returns:

true if the IUnknown pointer of the two objects are equal

hashCode

int hashCode()

Hash code consistent with equals(java.lang.Object) }.

This method queries the IUnknown* value to the wrapped COM object and returns its pointer bit image as integer.

The net result is that the identity of Com4jObject is based on the identity of the underlying COM objects. Two Com4jObject that are holding different interfaces of the same COM object is considered "equal".

Overrides:

hashCode in class Object

Returns:

The hash coded for this Com4jObject

getPtr

int getPtr()

Deprecated. 64bit unasfe.

Returns the interface pointer as an integer

Returns:

the interface pointer of this object.

getPointer

long getPointer()

Returns the interface pointer as an integer

getIUnknownPointer

long getIUnknownPointer()

QueryInterface to IUnknown and return its raw pointer value. This is the object identity in COM.

getComThread

ComThread getComThread()

Every Com4jObject has a ComThread that is running handling all the calls to this object. This method has to return that thread.

Returns:

the ComThread handling all the calls to this object.

toString

String toString()

Prints the raw interface pointer that this object represents.

Overrides:

toString in class Object

Returns:

a String representation of this object.

dispose

void dispose()

Releases a reference to the wrapped COM object.

Since Java objects tend to live longer in memory until it's GC-ed, and applications have generally no control over when it's GC-ed, calling the dispose method earlier enables applications to dispose the COM objects deterministically.

is

<T extends Com4jObject> boolean is(Class<T> comInterface)

Checks if this COM object implements a given interface.

This is just a convenience method that behaves as follows:

 return queryInterface(comInterface)!=null;
 

Type Parameters:

T - the type of the interface class object

Parameters:

comInterface - The class object of the Com4J interface

Returns:

true if the wrapped COM object implements a given interface.

queryInterface

<T extends Com4jObject> T queryInterface(Class<T> comInterface)

Invokes the queryInterface of the wrapped COM object and attempts to obtain a different interface of the same object.

Type Parameters:

T - the type of the interface class object

Parameters:

comInterface - the class object of the requested Com4J interface

Returns:

a reference to the requested interface or null if the queryInterface fails.

advise

<T> EventCookie advise(Class<T> eventInterface,
                     T receiver)

Subscribes to the given event interface of this object.

Type Parameters:

T - the type of the eventInterface class object.

Parameters:

eventInterface - The event interface definition. This interface/class has to have an IID annotation that designates the event interface GUID, and also methods annotated with DISPID that designates what methods are event methods. Must not be null.

receiver - The object that receives events.

Returns:

Always non-null. Call EventCookie.close() to shut down the event subscription.

Throws:

ComException - if a subscription fails.

setName

void setName(String name)

You can use this function to set a name to an object. This is only for debug purposes.

Parameters:

name - the new name of the object.