com.datagis.com4j

Class ComObject<T extends com4j.Com4jObject>

java.lang.Object

com.datagis.com4j.ComObject<T>

Type Parameters:

T - the interface that represents the the native COM interface

All Implemented Interfaces:

Disposable

Direct Known Subclasses:

AngleAxis, ApplicationInfo, Camera, ComEventObject, Command, DateTimeSettings, Feature, Features, Layer, Layers, NativeVersion, TerraExplorerDetect, Vector3D

public abstract class ComObject<T extends com4j.Com4jObject>
extends Object
implements Disposable

The ComObject class is the base class of all COM derived Java classes.

Since:

TEJ1.0

Author:

Carsten Klein

Field Summary

Fields

Modifier and Type	Field and Description
protected T	base Holds a reference to the native COM object's proxy class.
protected int	hashCode The lazily cached hashCode value.
protected String	toString The lazily cached toString value.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ComObject(T base) Constructs a new ComObject descendant object by using the COM object's proxy class specified.

Method Summary

Modifier and Type	Method and Description
protected Object	clone() Throws a CloneNotSupportedException exception.
void	dispose() Releases the reference to the native COM object exposed by this object.
boolean	equals(Object obj) Tests whether two native COM objects or interfaces refer to the same COM object.
int	hashCode() Returns a hash code value consistent with equals(Object) and referenceEquals(Object) This method queries the IUnknown* value from underlying native COM object and returns its pointer as integer.
boolean	isDisposed() Indicates whether the underlying native COM object is already disposed.
boolean	isInstanceOf(Class<T> comInterface) Determines whether this native COM object supports the specified COM interface.
boolean	referenceEquals(Object obj) Tests whether two native COM objects or interfaces refer to the same COM object.
String	toString() Returns a string representation of this native COM object.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

base

protected T extends com4j.Com4jObject base

Holds a reference to the native COM object's proxy class.

hashCode

protected int hashCode

The lazily cached hashCode value.

toString

protected String toString

The lazily cached toString value.

Constructor Detail

ComObject

protected ComObject(T base)

Constructs a new ComObject descendant object by using the COM object's proxy class specified.

Since this class is abstract, this constructor is never called directly but only though a constructor of any subclass, which extends this class. Its only purposes are to pick up the proxy class.

Parameters:

base - the native COM object's proxy class

Method Detail

isInstanceOf

public boolean isInstanceOf(Class<T> comInterface)

Determines whether this native COM object supports the specified COM interface. This method simply calls the queryInterface method on this object for the specified COM interface and return true, if the returned pointer is not a null pointer.

So, this function could also be implemented as follows:

 return (myObject.queryInterface(myInterface) != null);
 

Parameters:

comInterface - the COM interface for which to determine, whether it is supported by this COM object.

Returns:

true if this object supports the specified COM interface; false otherwise

dispose

public void dispose()

Releases the reference to the native COM object exposed by this object. Although, dispose can be called on an object multiple times, regardless whether the object is already disposed, method isDisposed may be used to determine, whether an object is disposed or not.

Since Java objects tend to live longer in memory until they are garbage collected, and applications have generally no control over when this happens, calling the dispose method at any time enables applications to dispose the native COM objects deterministically.

After having disposed a native COM object, one has no longer access to the object's methods. Accessing methods of a disposed native COM object will throw an IllegalStateException.

Specified by:

dispose in interface Disposable

See Also:

isDisposed()

isDisposed

public boolean isDisposed()

Indicates whether the underlying native COM object is already disposed. This method just takes advantage of the fact, that a disposed object will return 0 as its hash code value. So, this method could easily be replaced by:

 return (this.hashCode() == 0);
 

Returns:

true if the underlying COM object is disposed; false otherwise

equals

public boolean equals(Object obj)

Tests whether two native COM objects or interfaces refer to the same COM object. In COM terminology, these are considered to be equal.

For COM objects, this requires calling IUnknown::QueryInterface on both interfaces and test the bit image of the resulting IUnknown*. If both objects share the same IUnknown pointer, they are considered to be equal, according to COM rules.

If a COM object implements several interfaces, in Java each interface is provides as a distinct object. Thus you cannot rely on myObject == anotherObject to determine if they represent the same COM object.

Some native COM objects may implement their own equals method, which then may determine equality not depending on object references but on the object's content. For example, a native COM object, storing an address, may be considered equal to another object of the same type, if all components of the address, like street, zip code or country are equal. Then, the Address subclass will likely overwrite this equals method and forward the call to the native implementation of the equals method. Hence, there is another final method referenceEquals(Object), that does the same test as this equals method's default implementation. Since referenceEquals may not be overwritten by subclasses, it should be the preferred method for the determination of reference equality.

Subclasses, that overwrite the equals method of this base class, should also overwrite the method hashCode() to ensure, that all objects, that are equal according to the equals method, will return the same hash code value. All objects consideren not equal according to the equals method, must never return the same hash code value.

Overrides:

equals in class Object

Parameters:

obj - the reference object with which to compare

Returns:

true if this object is the same as the obj argument; false otherwise

See Also:

referenceEquals(Object), hashCode(), Hashtable

referenceEquals

public final boolean referenceEquals(Object obj)

Tests whether two native COM objects or interfaces refer to the same COM object. In COM terminology, these are considered to be equal.

For COM objects, this requires calling IUnknown::QueryInterface on both interfaces and test the bit image of the resulting IUnknown*. If both objects share the same IUnknown pointer, they are considered to be equal, according to COM rules.

If a COM object implements several interfaces, in Java each interface is provides as a distinct object. Thus you cannot rely on myObject == anotherObject to determine if they represent the same COM object.

In contrast to method equals(Object), this final method cannot be overwritten by subclasses and so is guaranteed always to determine equality based on the identity of the underlying native COM objects. Thus, this should be the preferred method to test the identity of COM objects.

Parameters:

obj - the reference object with which to compare

Returns:

true if this object is the same as the obj argument; false otherwise

See Also:

equals(Object), hashCode(), Hashtable

hashCode

public int hashCode()

Returns a hash code value consistent with equals(Object) and referenceEquals(Object)

This method queries the IUnknown* value from underlying native COM object and returns its pointer as integer.

The net result is that the identity of a Java ComObject is based on the identity of the underlying COM object. Two ComObject instances that are holding different interfaces of the same COM object, are considered to be equal.

Some native COM objects may implement their own hashCode method, which may not calculate the hash code value depending on the object reference but on its content. For example, a native COM object, storing an address, may serve a hash code value based on the hash code values of all components of the address, like street, zip code or country. Then, the Address subclass will likely overwrite this hashCode method and forward the call to the native implementation of the hashCode method.

Subclasses, that overwrite the hashCode method of this base class, should also overwrite the method equals(Object) to ensure, that all objects, that are equal according to the equals method, will return the same hash code value. All objects considered not equal according to the equals method, must never return the same hash code value.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

See Also:

equals(Object), Hashtable

toString

public String toString()

Returns a string representation of this native COM object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class ComObject returns a string consisting of the name of the Java class or interface that is the direct Java counterpart of the underlying COM object, this object is representing, the at-sign character `@', and the unsigned hexadecimal representation of the native COM object pointer of the underlying COM object.

Some native COM objects may implement their own toString method, which may return a more precise description of the object. For example, a native COM object, storing an address, may include all or et least the most important components of the address, like street, zip code or country. Then, the Address subclass will likely overwrite this toString method and forward the call to the native implementation of the toString method.

Overrides:

toString in class Object

Returns:

a string representation of the object

clone

protected Object clone()
                throws CloneNotSupportedException

Throws a CloneNotSupportedException exception. By default, COM based objects should not be cloneable by Java. This should only be supported for these native COM classes, that also implement a native Clone method. Subclasses, that represent such natively cloneable COM based objects, should then override this method.

Overrides:

clone in class Object

Returns:

a clone of this instance

Throws:

CloneNotSupportedException - if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.