com.datagis.com4j

Class ComEventObject<T extends com4j.Com4jObject>

java.lang.Object

com.datagis.com4j.ComObject<T>

com.datagis.com4j.ComEventObject<T>

Type Parameters:

T - the interface that represents the the native COM interface

All Implemented Interfaces:

Disposable

Direct Known Subclasses:

Application, ContextMenuHost, Device, GenericNativeWindow, Keyboard, Logger, Sensor, TerraExplorer

public abstract class ComEventObject<T extends com4j.Com4jObject>
extends ComObject<T>

The ComEventObject class adds support for registering for native COM events. It is the base class of all COM derived Java classes, that support native COM events.

Since:

TEJ1.0

Author:

Carsten Klein

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<ComEventListener,com4j.EventCookie>	events Stores all event cookies obtained from method Com4jObject.advise(Class nativeEventInterface, T receiver) , using the event receiver ComEventListener as key.

Fields inherited from class com.datagis.com4j.ComObject

base, hashCode, toString

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
<E extends ComEventListener> void	addComEventListener(Class<E> eventInterface, E listener) Adds the specified COM event listener to receive events for the specified event interface from the underlying COM event source.
protected int	comEventListeners() Returns the number of currently registered COM event listeners.
void	dispose() Releases the reference to the native COM object exposed by this object.
<E extends ComEventListener> E[]	getComEventListeners(Class<E> listenerType) Returns an array of all the objects currently registered as ComEventListeners upon this ComEventObject.
boolean	isComEventListener(ComEventListener listener) Indicates whether the specified listener listener is a registered COM event listener for this ComEventObject.
protected void	removeComEventListener(ComEventListener listener) Removes the specified COM event listener for the specified event interface so that it no longer receives events from the underlying COM event source.

Methods inherited from class com.datagis.com4j.ComObject

clone, equals, hashCode, isDisposed, isInstanceOf, referenceEquals, toString

Methods inherited from class java.lang.Object

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

Field Detail

events

protected Map<ComEventListener,com4j.EventCookie> events

Stores all event cookies obtained from method Com4jObject.advise(Class nativeEventInterface, T receiver) , using the event receiver ComEventListener as key.

Constructor Detail

ComEventObject

protected ComEventObject(T base)

Constructs a new ComEventObject 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

addComEventListener

public <E extends ComEventListener> void addComEventListener(Class<E> eventInterface,
                                                             E listener)

Adds the specified COM event listener to receive events for the specified event interface from the underlying COM event source. If either listener listener is null or event interface nativeEventInterface is null, no exception is thrown and no action is performed.

Type Parameters:

E - an interface that derives from com.datagis.com4j.ComEventListener

Parameters:

eventInterface - the type of listeners requested; this parameter should specify an interface that derives from com.datagis.com4j.ComEventListener

listener - the COM event listener to be added

See Also:

removeComEventListener(ComEventListener), getComEventListeners(java.lang.Class<E>), ComEventListener

removeComEventListener

protected void removeComEventListener(ComEventListener listener)

Removes the specified COM event listener for the specified event interface so that it no longer receives events from the underlying COM event source. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to this instance of the underlying COM object. If listener listener is null, no exception is thrown and no action is performed.

Parameters:

listener - the COM event listener to be removed

See Also:

addComEventListener(ComEventListener), getComEventListeners(java.lang.Class<E>), ComEventListener

getComEventListeners

public <E extends ComEventListener> E[] getComEventListeners(Class<E> listenerType)

Returns an array of all the objects currently registered as ComEventListeners upon this ComEventObject. ComEventListeners are registered using the addComEventListener method.

You can specify the listenerType argument with a class literal, such as FooComEventListener.class. For example, you can query the COM class Application a for its COM event listeners with the following code:

 
 
 
 ApplicationListener[] ls = (ApplicationListener[]) (a
                .getComEventListeners(ApplicationListener.class));
 

If no such listeners exist, this method returns an empty array.

Type Parameters:

E - an interface that derives from com.datagis.com4j.ComEventListener

Parameters:

listenerType - the type of listeners requested; this parameter should specify an interface that derives from com.datagis.com4j.ComEventListener

Returns:

an array of all objects registered as ComEventListeners on this component, or an empty array if no such listeners have been added

Throws:

ClassCastException - if listenerType doesn't specify a class or interface that implements com.datagis.com4j.ComEventListener

See Also:

addComEventListener(ComEventListener), removeComEventListener(ComEventListener), ComEventListener

comEventListeners

protected int comEventListeners()

Returns the number of currently registered COM event listeners.

Returns:

the number of currently registered COM event listeners

isComEventListener

public boolean isComEventListener(ComEventListener listener)

Indicates whether the specified listener listener is a registered COM event listener for this ComEventObject.

Parameters:

listener - the COM event listener to test

Returns:

true if the specified listener listener is a registered COM event listener for this ComEventObject; 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 nor will any events be delivered to any event listener that still may be registered. Accessing methods of a disposed native COM object will throw an IllegalStateException.

Specified by:

dispose in interface Disposable

Overrides:

dispose in class ComObject<T extends com4j.Com4jObject>

See Also:

ComObject.isDisposed()