com.iizix.event

Class GEvent

java.lang.Object

com.iizix.event.GEvent

All Implemented Interfaces:

IPostEventProcessing

Direct Known Subclasses:

BubbleEvent, ResolveReferencesEvent, SinkEvent

public abstract class GEvent
extends Object
implements IPostEventProcessing

This class is the base class for all events.

Author:

Christopher Mindus

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GEvent.Operation Operations enumeration when sending the from the GProp.onEvent method.

Field Summary

Fields

Modifier and Type	Field and Description
static int	PROP_ADDED Event ID for property added event.
static int	PROP_ATTR_CHANGED Event ID for property attribute changed event.
static int	PROP_CNR_ADDED Event ID for property container added.
static int	PROP_CNR_FOCUS Event ID for resolve references.
static int	PROP_CNR_MOVED Event ID for a property container move to another container event.
static int	PROP_CNR_RENAMED Event ID for property name changed event of a container.
static int	PROP_DESIGNER_ASSET_CHANGED Event ID for Asset files changes in conjunction with AssetReference (only in the Designer).
static int	PROP_DESIGNER_JAVA_CLASS_CHANGED Event ID for Java Class changes in conjunction with ClassReference (only in the Designer).
static int	PROP_DESIGNER_JAVA_METHOD_RENAMED Event ID for Java Method renamed in conjunction with ClassReference (only in the Designer).
static int	PROP_DESIGNER_KSTRING Event ID for KString event.
static int	PROP_DESIGNER_VIEWER_UPDATE Event ID for property update for the Eclipse Common Navigator viewer (only in the Designer).
static int	PROP_DESIGNER_VS_REFERENCE Event ID for VSReference resolving in conjunction with VSRelativeReference (only in the Designer).
static int	PROP_DISPOSED Event ID for property disposed changed event.
static int	PROP_FOCUS Event ID for focus.
static int	PROP_MOVED_FROM Event ID for property moved from container event.
static int	PROP_MOVED_TO Event ID for property moved to container event.
static int	PROP_PROJECT_RENAMED Event ID for project renamed.
static int	PROP_QUERY_DESIGNER_PROPS Event ID to query properties for references.
static int	PROP_REFRESH Event ID for a RefreshEvent.
static int	PROP_REMOVED Event ID for property removed event.
static int	PROP_RENAMED Event ID for property name changed event.
static int	PROP_REORDERED Event ID for property container reordered.
static int	PROP_RESOLVE_REFERENCES_DIRECT Event ID for resolve references.
static int	PROP_VALUE_CHANGED Event ID for property value changed event.
static int	REMOTE Event ID for Remote Property Event.

Constructor Summary

Constructors

Constructor and Description
GEvent(GProp<?> source, int eventID, boolean isRemoteInduced) Constructs the generic event with specified originator without progress monitor.
GEvent(GProp<?> source, int eventID, boolean isRemoteInduced, IPropProgressMonitor monitor) Constructs the generic event with specified originator.
GEvent(GProp<?> source, int eventID, IPropProgressMonitor monitor) Constructs the generic event with specified originator that has a progress monitor and is not remote induced.

Method Summary

Modifier and Type	Method and Description
void	addPostProcessor(EventListener postProcessor) Adds a post-event processor that will be called when the event has completed its notification process.
void	cancel() Cancel even propagation of this event.
void	consume() Consumes this event.
protected EventListener	getAlternateDestination(GProp<?> destination, GEvent.Operation operation, int operationIndex) Gets the alternate property destination for an event about to be sent.
int	getEventID() Gets the event ID.
String	getEventName() Gets the name string of the event.
static String	getEventName(int eventID) Gets the name of an eventID.
GProp<?>	getEventTarget() Gets the event owner.
GEvent.Operation	getOperation() Gets the current operation.
abstract GEvent.Operation[]	getOperations() Gets the Operations order describing what Operation the property that receives the event should process.
EventListener[]	getPostProcessors(GProp<?> dispatcher) Gets the post-processors.
GProp<?>	getSender() Gets the current sender of the event.
GProp<?>	getSource() Gets the source of the event.
IGProp<?>	getTrigger() Returns the trigger of this event, if any.
boolean	isCancelled() Checks if this event has been cancelled.
boolean	isClearCacheEvent() Returns the state for a property container if this event is received in the onEventSelf method as a helper for it would need to clear the property container cache.
boolean	isConsumed() Checks if this event has been consumed.
boolean	isEventProcessed(GProp<?> property, GEvent.Operation operation, int operationIndex) Checks if this Operation at specified index should be processed or not by the specified property.
boolean	isPropertyChange(IGProp<?> property) Checks if the event is a property value change.
boolean	isPropertyChange(PropCnr pc, Atom name) Checks if the event is a modification change of any property in the specified container.
boolean	isPropertyChange(PropCnr pc, String name) Checks if the event is a modification change of any property in the specified container.
boolean	isPropertyChangeIn(PropCnr pc) Checks if the event is a modification change of any property in the specified container.
boolean	isPropertyChangeInTree(PropCnr pc) Checks if the event is a modification change of any property in the specified container or any of its children.
boolean	isRefreshEvent() Returns true if this is a refresh event.
boolean	isRemoteInduced() Flag indicating this change is induced from a remote party.
boolean	isVerifyEvent() Returns if this event is a verify event for a container that processes verification.
protected StringBuilder	paramString(StringBuilder buf) Returns the parameter string representing the state of this event.
void	send(GProp<?> sender, EventListener listener) Sends this event to the event listener in question, with "safe" processing, i.e.
void	send(GProp<?> sender, GProp<?> receiver, GEvent.Operation operation, int operationIndex) Sends this event to the property in question, with "safe" processing, i.e.
void	sendSelf(GProp<?> senderAndReceiver, GEvent.Operation operation, int operationIndex) Sends this event to the property itself in question, with "safe" processing, i.e.
void	setInitialProperty(GProp<?> initialDispatcher) Assigns the initial sender property that should perform post processing of events.
void	setOperation(GEvent.Operation operation) Sets the current operation.
void	setProgressMonitor(IPropProgressMonitor monitor) Sets the progress monitor if not already done.
String	toString() Returns a string representation of this component and its values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PROP_ATTR_CHANGED

public static final int PROP_ATTR_CHANGED

Event ID for property attribute changed event.

It is a bubbling event.

Event class: com.iizix.event.PropAttrEvent.

See Also:

Constant Field Values

PROP_VALUE_CHANGED

public static final int PROP_VALUE_CHANGED

Event ID for property value changed event.

It is a bubbling event.

Event class: com.iizix.event.PropValueEvent.

See Also:

Constant Field Values

PROP_ADDED

public static final int PROP_ADDED

Event ID for property added event.

It is a bubbling event.

Event class: com.iizix.event.PropCnrEvent.

See Also:

Constant Field Values

PROP_REMOVED

public static final int PROP_REMOVED

Event ID for property removed event.

It is a bubbling event.

Event class: com.iizix.event.PropCnrEvent.

See Also:

Constant Field Values

PROP_RENAMED

public static final int PROP_RENAMED

Event ID for property name changed event.

It is a bubbling event.

Event class: com.iizix.event.PropNameEvent.

See Also:

Constant Field Values

PROP_DISPOSED

public static final int PROP_DISPOSED

Event ID for property disposed changed event.

It is a bubbling event.

Event class: com.iizix.event.PropDisposeEvent.

See Also:

Constant Field Values

PROP_MOVED_FROM

public static final int PROP_MOVED_FROM

Event ID for property moved from container event. This event is triggered when the property already has been moved from the original container, and to the destination. This event is sent from the moved container and send upwards in the property hierarchy.

It is a bubbling event.

Event class: com.iizix.event.PropMoveEvent.

See Also:

Constant Field Values

PROP_MOVED_TO

public static final int PROP_MOVED_TO

Event ID for property moved to container event. This event is triggered when the property already has been moved from the original container, and to the destination. This event is sent from the moved property already located in the moved-to-container and send upwards in the property hierarchy. Thus a property listening for move events should process this Moved-To event and not the Moved-From event.

It is a bubbling event.

Event class: com.iizix.event.PropMoveEvent.

See Also:

Constant Field Values

PROP_REORDERED

public static final int PROP_REORDERED

Event ID for property container reordered.

It is a bubbling event.

Event class: com.iizix.event.PropReorderEvent.

See Also:

Constant Field Values

PROP_CNR_ADDED

public static final int PROP_CNR_ADDED

Event ID for property container added.

This is a sinking event.

Event class: com.iizix.event.ParentCnrAddedEvent.

See Also:

Constant Field Values

PROP_CNR_RENAMED

public static final int PROP_CNR_RENAMED

Event ID for property name changed event of a container.

This is a sinking event.

Event class: com.iizix.event.PropNameEvent.

See Also:

Constant Field Values

PROP_CNR_MOVED

public static final int PROP_CNR_MOVED

Event ID for a property container move to another container event. This event is triggered when the property container already has been moved from the original container, and to the destination.

This is a sinking event.

Event class: com.iizix.event.ParentCnrMoveEvent.

See Also:

Constant Field Values

PROP_FOCUS

public static final int PROP_FOCUS

Event ID for focus.

This is a bubbling event.

Event class: com.iizix.event.PropFocusEvent.

See Also:

Constant Field Values

PROP_CNR_FOCUS

public static final int PROP_CNR_FOCUS

Event ID for resolve references.

This is a sinking event.

Event class: com.iizix.event.PropCnrFocusEvent.

See Also:

Constant Field Values

PROP_RESOLVE_REFERENCES_DIRECT

public static final int PROP_RESOLVE_REFERENCES_DIRECT

Event ID for resolve references.

This is a sinking event.

Event class: com.iizix.event.ResolveReferencesEvent.

See Also:

Constant Field Values

PROP_PROJECT_RENAMED

public static final int PROP_PROJECT_RENAMED

Event ID for project renamed.

This is a sinking event.

Event class: com.iizix.event.ProjectNameEvent.

See Also:

Constant Field Values

PROP_QUERY_DESIGNER_PROPS

public static final int PROP_QUERY_DESIGNER_PROPS

Event ID to query properties for references.

This is a sinking event.

Event class: com.iizigo.event.QueryDesignerPropEvent.

See Also:

Constant Field Values

PROP_DESIGNER_VIEWER_UPDATE

public static final int PROP_DESIGNER_VIEWER_UPDATE

Event ID for property update for the Eclipse Common Navigator viewer (only in the Designer).

It is a bubbling event.

Event class: com.iizigo.event.CommonDesignerEvent.

See Also:

Constant Field Values

PROP_DESIGNER_VS_REFERENCE

public static final int PROP_DESIGNER_VS_REFERENCE

Event ID for VSReference resolving in conjunction with VSRelativeReference (only in the Designer). The event is fired when a VSReference is resolved or broken, causing VSRelativeReference instances to re-check their state.

It is a sinking event.

Event class: com.iizix.event.VSReferenceEvent.

See Also:

Constant Field Values

PROP_DESIGNER_ASSET_CHANGED

public static final int PROP_DESIGNER_ASSET_CHANGED

Event ID for Asset files changes in conjunction with AssetReference (only in the Designer). The event is fired when a file property container notices a change of the file or if it removed, to re-check their state.

It is a sinking event.

Event class: com.iizix.event.AssetEvent.

See Also:

Constant Field Values

PROP_DESIGNER_JAVA_CLASS_CHANGED

public static final int PROP_DESIGNER_JAVA_CLASS_CHANGED

Event ID for Java Class changes in conjunction with ClassReference (only in the Designer). The event is fired when a Java source has been compiled and parsed, or if it has been reconciled. All annotations are up-to-date when the event is received.

It is a sinking event.

Event class: com.iizigo.java.event.JavaClassEvent.

See Also:

Constant Field Values

PROP_DESIGNER_JAVA_METHOD_RENAMED

public static final int PROP_DESIGNER_JAVA_METHOD_RENAMED

Event ID for Java Method renamed in conjunction with ClassReference (only in the Designer). The event is fired when a Java source has been compiled and parsed, or if it has been reconciled. All annotations are up-to-date when the event is received.

It is a sinking event.

Event class: com.iizigo.java.event.JavaMethodEvent.

See Also:

Constant Field Values

PROP_DESIGNER_KSTRING

public static final int PROP_DESIGNER_KSTRING

Event ID for KString event.

It is a sinking event.

Event class: com.iizigo.java.event.KStringEvent.

See Also:

Constant Field Values

PROP_REFRESH

public static final int PROP_REFRESH

Event ID for a RefreshEvent.

It is a sinking event.

Event class: com.iizix.event.RefreshEvent.

See Also:

Constant Field Values

REMOTE

public static final int REMOTE

Event ID for Remote Property Event.

It is a bubbling event.

Event class: com.iizix.event.RemoteEvent.

See Also:

Constant Field Values

Constructor Detail

GEvent

public GEvent(GProp<?> source,
              int eventID,
              boolean isRemoteInduced)

Constructs the generic event with specified originator without progress monitor.

Parameters:

source - The source object.

eventID - The event ID, see GEvent.PROP_*.

isRemoteInduced - Flag indicating this change is induced from a remote party.

Throws:

NullPointerException - If source is null.

GEvent

public GEvent(GProp<?> source,
              int eventID,
              IPropProgressMonitor monitor)

Constructs the generic event with specified originator that has a progress monitor and is not remote induced.

Parameters:

source - The source object.

eventID - The event ID, see GEvent.PROP_*.

monitor - The progress monitor, null for none.

Throws:

NullPointerException - If source is null.

GEvent

public GEvent(GProp<?> source,
              int eventID,
              boolean isRemoteInduced,
              IPropProgressMonitor monitor)

Constructs the generic event with specified originator.

Parameters:

source - The source object.

eventID - The event ID, see GEvent.PROP_*.

isRemoteInduced - Flag indicating this change is induced from a remote party.

monitor - The progress monitor, null for none.

Throws:

NullPointerException - If source is null.

Method Detail

getEventName

public static String getEventName(int eventID)

Gets the name of an eventID.

setProgressMonitor

public void setProgressMonitor(IPropProgressMonitor monitor)

Sets the progress monitor if not already done. This method has no effect if the monitor is already set.

getEventID

public final int getEventID()

Gets the event ID.

getEventName

public String getEventName()

Gets the name string of the event. Same as GEvent.getEventName(event.getEventID()).

Returns:

A string representation of the event ID.

getSource

public final GProp<?> getSource()

Gets the source of the event.

Returns:

The Generic Property for the event, the source, or originator.

getEventTarget

public GProp<?> getEventTarget()

Gets the event owner. The owner is the one the message relates to e.g. the property for value change or the property being added or removed for property container events.

Returns:

The Generic Property for the event, the source, or originator.

isRemoteInduced

public final boolean isRemoteInduced()

Flag indicating this change is induced from a remote party.

getOperation

public GEvent.Operation getOperation()

Gets the current operation.

setOperation

public void setOperation(GEvent.Operation operation)

Sets the current operation. This method should not be called, it is intended for GProp.onEvent.

Throws:

NullPointerException - If operation is null.

isConsumed

public final boolean isConsumed()

Checks if this event has been consumed.

Consumed events are still propagating, so this flag is more of informational purpose.

Returns:

true indicates event is consumed, false indicates event is not yet consumed.

consume

public final void consume()

Consumes this event.

Consumed events are still propagating, so this flag is more of informational purpose.

isCancelled

public final boolean isCancelled()

Checks if this event has been cancelled.

Returns:

true indicates event is cancelled, false indicates event is not cancelled.

cancel

public final void cancel()

Cancel even propagation of this event.

getOperations

public abstract GEvent.Operation[] getOperations()

Gets the Operations order describing what Operation the property that receives the event should process. This Operations order defines e.g. if the event is bubbling, sinking or just private.

Subclasses must implement this Operations order. They should NOT use both Sinking and Bubbling Operations, this will cause an infinite loop or stack overflow due to recursion.

Returns:

The order of the Operations, per Event-implementing class dependent, normally a static final array.

toString

public String toString()

Returns a string representation of this component and its values.

Overrides:

toString in class Object

Returns:

A string representation of this property.

paramString

protected StringBuilder paramString(StringBuilder buf)

Returns the parameter string representing the state of this event. This string is useful for debugging. Super classes adds extra information to the string by preceding it with a comma followed by the extra information.

Parameters:

buf - The StringBuilder to append the string to.

Returns:

The StringBuilder, i.e. the buf input parameter.

send

public final void send(GProp<?> sender,
                       EventListener listener)

Sends this event to the event listener in question, with "safe" processing, i.e. that potential exceptions are caught and logged.

This method is intended to be called from GProp.onEvent(event). Do not call this method.

This event's operation, retrieved by getOperation() is set to LISTENERS.

Parameters:

sender - The sender property.

listener - The event listener.

send

public final void send(GProp<?> sender,
                       GProp<?> receiver,
                       GEvent.Operation operation,
                       int operationIndex)

Sends this event to the property in question, with "safe" processing, i.e. that potential exceptions are caught and logged.

This method is intended to be called from GProp.onEvent(event). Do not call this method.

Parameters:

sender - The sender property.

receiver - The receiving property.

operation - The Operation.

operationIndex - The current index in the Operation array provided by this event's getOperations() method.

sendSelf

public final void sendSelf(GProp<?> senderAndReceiver,
                           GEvent.Operation operation,
                           int operationIndex)

Sends this event to the property itself in question, with "safe" processing, i.e. that potential exceptions are caught and logged. The method called for the property (that might be altered using getAlternateDestination) is onEventSelf rather than onEvent.

This method is intended to be called from GProp.onEvent(event). Do not call this method.

Parameters:

senderAndReceiver - The sender and received property.

operation - The Operation.

operationIndex - The current index in the Operation array provided by this event's getOperations() method.

getSender

public final GProp<?> getSender()

Gets the current sender of the event.

getAlternateDestination

protected EventListener getAlternateDestination(GProp<?> destination,
                                                GEvent.Operation operation,
                                                int operationIndex)

Gets the alternate property destination for an event about to be sent. The default is to return the same destination, but subclasses can choose to return another property that would be "more suitable" to receive the event, i.e. the property that would really do the processing. This enables performance enhancements to be done for a particular event.

This method also enables an event to skip sending the event to a property by returning null in this method.

Subclasses can override this method to provide fine-tuned behavior.

Parameters:

destination - The destination property.

operation - The Operation.

operationIndex - The current index in the Operation array provided by this event's getOperations() method.

Returns:

destination by default. If null is returned, this event will not be sent.

isEventProcessed

public boolean isEventProcessed(GProp<?> property,
                                GEvent.Operation operation,
                                int operationIndex)

Checks if this Operation at specified index should be processed or not by the specified property.

An event can fine-tune event distribution with this mechanism, thus improving performance.

This method is intended to be called from GProp.onEvent(event). Do not call this method.

Parameters:

property - The property processing the event in GEvent.onEvent(event).

operation - The Operation.

operationIndex - The current index in the Operation array provided by this event's getOperations() method.

Returns:

true by default. If false is returned, an event could cause e.g. the CHILDREN operation processing to be skipped for certain properties.

isClearCacheEvent

public boolean isClearCacheEvent()

Returns the state for a property container if this event is received in the onEventSelf method as a helper for it would need to clear the property container cache.

Returns:

true if the event would require the property container to clear its cache.

isVerifyEvent

public boolean isVerifyEvent()

Returns if this event is a verify event for a container that processes verification.

Returns:

true if the event should trigger container verification, false otherwise.

addPostProcessor

public void addPostProcessor(EventListener postProcessor)

Adds a post-event processor that will be called when the event has completed its notification process. This method can be called at any time during the event notification phase, but calls to this method when post-processing is executing is not going to change the post-processors, thus will the postProcessor not be called.

Note: the post-processors are called no matter if the event has been canceled, so the processor may have to check the cancel state.

Calling this method with the same postProcessor more than once does not add it again.

Specified by:

addPostProcessor in interface IPostEventProcessing

Parameters:

postProcessor - Processor to add.

Throws:

NullPointerException - If the postProcessor is null.

setInitialProperty

public void setInitialProperty(GProp<?> initialDispatcher)

Assigns the initial sender property that should perform post processing of events. This method should only be called from the initial GProp that sends the event the first time. This is done from the GProp.onEvent method and should not be called elsewhere.

Specified by:

setInitialProperty in interface IPostEventProcessing

Parameters:

initialDispatcher - The initial dispatcher.

getPostProcessors

public EventListener[] getPostProcessors(GProp<?> dispatcher)

Gets the post-processors.

Specified by:

getPostProcessors in interface IPostEventProcessing

Parameters:

dispatcher - The property retrieving the post-processors, null for none.

Returns:

An array of the post-processors to call after all normal event notification, null for none.

isPropertyChange

public boolean isPropertyChange(IGProp<?> property)

Checks if the event is a property value change.

Parameters:

property - The property.

Returns:

true if the property just got changed in the container due to this event, false otherwise.

isPropertyChange

public boolean isPropertyChange(PropCnr pc,
                                Atom name)

Checks if the event is a modification change of any property in the specified container.

Parameters:

pc - The property container.

name - The property name to check for change.

Returns:

true if the property just got changed in the container due to this event, false otherwise.

isPropertyChange

public boolean isPropertyChange(PropCnr pc,
                                String name)

Checks if the event is a modification change of any property in the specified container.

Parameters:

pc - The property container.

name - The property name to check for change.

Returns:

true if the property just got changed in the container due to this event, false otherwise.

isPropertyChangeIn

public boolean isPropertyChangeIn(PropCnr pc)

Checks if the event is a modification change of any property in the specified container.

Parameters:

pc - The property container.

Returns:

true if a property just got changed in the container due to this event, false otherwise.

getTrigger

public IGProp<?> getTrigger()

Returns the trigger of this event, if any.

Returns:

Trigger property of this event, null for none.

isPropertyChangeInTree

public boolean isPropertyChangeInTree(PropCnr pc)

Checks if the event is a modification change of any property in the specified container or any of its children.

Parameters:

pc - The property container.

Returns:

true if a property just got changed in the container tree due to this event, false otherwise.

isRefreshEvent

public boolean isRefreshEvent()

Returns true if this is a refresh event.

Returns:

true if this is a RefreshEvent, false otherwise. Always false if not overridden, e.g. by RefreshEvent.