Package com.smartgwt.client.tools.stream

Class EventStream

java.lang.Object
com.smartgwt.client.core.BaseClass
com.smartgwt.client.tools.stream.EventStream
All Implemented Interfaces:
HasHandlers
public class EventStream extends BaseClass
Note: this is currently an experimental feature and not covered by normal support guarantees. See Experimental Features for more information.

A EventStream captures event details as JavaScript objects as they are handled by the EventHandler. The event target canvas ID and class name as well the locator are included, as available. Event-specific data (for example, the String for keyboard events) are also included where appropriate. See EventStreamEvent for more information.

You can configure the stream to capture most DOM event types and other useful events, such as relogins and JavaScript errors that are triggered by events:

Event CategoryIncludes (source DOM eventType(s) or description) Controlling AttributeFrom DOM Event?
click eventsmouseDown, mouseUp, click, dblClickcaptureClickEventsY
move eventsmouseMove, mouseOut captureMoveEventsY
key eventskeyDown, keyPress, keyUpcaptureKeyEvents Y
drag eventsdragStart, dragMove, dragStopcaptureDragEvents Y
context menu eventscontextMenu captureMenuEventsY
mouse wheel eventsmouseWheel captureWheelEventsY
page eventsload, unload, resize capturePageEventsY
login eventsSuccessful relogin via the RPCManagercaptureLoginEvents N
Reify file events Project and screen (auto)saves and loadscaptureDSFileEventsN
event errorsJavaScript exceptions captureEventErrorsN
(Pointer and touch equivalents to mouse events have not been listed above. See the associated attribute for a more inclusive list.)

Note that several types of DOM events can be collapsed so that one event is reported instead of many if they occur over the same target. You can enable collapsing for move and drag events, key events, wheel events, and page events. A stream capture limit is also supported via circular buffering, so that only the most recent events are preserved. All available events can be returned as an array of EventStreamEvent via getEvents().

A EventStream will start capturing events as soon as it's created by default, but if you set autoStart: false, you can start capturing manually by calling start(). Calling end() will end capturing and return the EventStreamData.

See Also:

  • Constructor Details

    • EventStream

      public EventStream()

    • EventStream

      public EventStream(JavaScriptObject jsObj)

  • Method Details

    • getOrCreateRef

      public static EventStream getOrCreateRef(JavaScriptObject jsObj)

    • setJavaScriptObject

      public void setJavaScriptObject(JavaScriptObject jsObj)
      Overrides:
      setJavaScriptObject in class BaseClass

    • create

      public JavaScriptObject create()
      Specified by:
      create in class BaseClass

    • isCreated

      public boolean isCreated()
      Overrides:
      isCreated in class BaseClass

    • getJsObj

      public JavaScriptObject getJsObj()
      Overrides:
      getJsObj in class BaseClass

    • getOrCreateJsObj

      public JavaScriptObject getOrCreateJsObj()
      Overrides:
      getOrCreateJsObj in class BaseClass

    • setAutoStart

      public EventStream setAutoStart(boolean autoStart) throws IllegalStateException
      Whether the stream should automatically begin capturing events. If false, the steam won't start capturing events until start() is called.
      Parameters:
      autoStart - New autoStart value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getAutoStart

      public boolean getAutoStart()
      Whether the stream should automatically begin capturing events. If false, the steam won't start capturing events until start() is called.
      Returns:
      Current autoStart value. Default value is true

    • setCaptureClickEvents

      public EventStream setCaptureClickEvents(boolean captureClickEvents) throws IllegalStateException
      Whether mouse button-driven events (or their touch equivalents) should be captured by the stream.

      Includes such eventTypes as mouseDown, mouseUp, click, doubleClk, pointerDown, pointerUp, pointerCancel, touchStart, touchEnd, and touchCancel.

      Parameters:
      captureClickEvents - New captureClickEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCaptureClickEvents

      public boolean getCaptureClickEvents()
      Whether mouse button-driven events (or their touch equivalents) should be captured by the stream.

      Includes such eventTypes as mouseDown, mouseUp, click, doubleClk, pointerDown, pointerUp, pointerCancel, touchStart, touchEnd, and touchCancel.

      Returns:
      Current captureClickEvents value. Default value is true

    • setCaptureDragEvents

      public EventStream setCaptureDragEvents(boolean captureDragEvents) throws IllegalStateException
      Whether dragging-related events should be captured by the stream. Multiple "drag move" type events that have the same eventType and targetID will be collapsed into one if collapseMoveEvents is true.

      Includes such eventTypes as:

      • dragStart, dragRepositionStart, dragResizeStart, dragSelectStart,
      • dragMove, dragRepositionMove, dragResizeMove, dragSelectMove,
      • dragStop, dragRepositionStop, dragResizeStop, dragSelectStop,
      • drop, dropOver, and dragLeave.
      Parameters:
      captureDragEvents - New captureDragEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCaptureDragEvents

      public boolean getCaptureDragEvents()
      Whether dragging-related events should be captured by the stream. Multiple "drag move" type events that have the same eventType and targetID will be collapsed into one if collapseMoveEvents is true.

      Includes such eventTypes as:

      • dragStart, dragRepositionStart, dragResizeStart, dragSelectStart,
      • dragMove, dragRepositionMove, dragResizeMove, dragSelectMove,
      • dragStop, dragRepositionStop, dragResizeStop, dragSelectStop,
      • drop, dropOver, and dragLeave.
      Returns:
      Current captureDragEvents value. Default value is true

    • setCaptureEventErrors

      public EventStream setCaptureEventErrors(boolean captureEventErrors) throws IllegalStateException
      Whether to capture JavaScript errors. If an already-captured event triggered the error, the details will attached to that event. Otherwise, a separate event will be created, with the eventType of the last dispatched DOM event (i.e., there is no special "error" eventType.)

      EventStreamEvent records annotated or specially-reported with error details will contain an errorTrace with the error stack trace, and a threadCode reporting the thread ID from the EventHandler responsible for the error.

      Parameters:
      captureEventErrors - New captureEventErrors value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCaptureEventErrors

      public boolean getCaptureEventErrors()
      Whether to capture JavaScript errors. If an already-captured event triggered the error, the details will attached to that event. Otherwise, a separate event will be created, with the eventType of the last dispatched DOM event (i.e., there is no special "error" eventType.)

      EventStreamEvent records annotated or specially-reported with error details will contain an errorTrace with the error stack trace, and a threadCode reporting the thread ID from the EventHandler responsible for the error.

      Returns:
      Current captureEventErrors value. Default value is true

    • setCaptureKeyEvents

      public EventStream setCaptureKeyEvents(boolean captureKeyEvents) throws IllegalStateException
      Whether keyboard input events should be captured by the stream. For non-modifier keys, which includes all the self-inserting visible keyboard characters, we capture only the keyPress, as keyDown/keyUp are generally not useful. Conversely, for modifier keys (e.g. Shift), we capture only the keyDown and keyUp. events, and not the keyPress.

      If collapseKeyEvents is true, multiple adjacent keyPress events may be collapsed into a single event for greater readability and a more compact event trace.

      Note that if an error is thrown while handling an event, it will get reported regardless of this setting and the above capturing rules, but see minErrorReportingInterval. So for example an error handling a keyDown would still generally end up in the event trace, even for a self-inserting key such as "A".

      Parameters:
      captureKeyEvents - New captureKeyEvents value. Default value is false
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCaptureKeyEvents

      public boolean getCaptureKeyEvents()
      Whether keyboard input events should be captured by the stream. For non-modifier keys, which includes all the self-inserting visible keyboard characters, we capture only the keyPress, as keyDown/keyUp are generally not useful. Conversely, for modifier keys (e.g. Shift), we capture only the keyDown and keyUp. events, and not the keyPress.

      If collapseKeyEvents is true, multiple adjacent keyPress events may be collapsed into a single event for greater readability and a more compact event trace.

      Note that if an error is thrown while handling an event, it will get reported regardless of this setting and the above capturing rules, but see minErrorReportingInterval. So for example an error handling a keyDown would still generally end up in the event trace, even for a self-inserting key such as "A".

      Returns:
      Current captureKeyEvents value. Default value is false

    • setCaptureLoginEvents

      public EventStream setCaptureLoginEvents(boolean captureLoginEvents) throws IllegalStateException
      Whether relogins are captured by the stream. Login events are non-DOM events originating from the RPCManager rather than the EventHandler. Login events have a transaction URL.

      Includes the eventType relogin.

      Parameters:
      captureLoginEvents - New captureLoginEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCaptureLoginEvents

      public boolean getCaptureLoginEvents()
      Whether relogins are captured by the stream. Login events are non-DOM events originating from the RPCManager rather than the EventHandler. Login events have a transaction URL.

      Includes the eventType relogin.

      Returns:
      Current captureLoginEvents value. Default value is true

    • setCaptureMenuEvents

      public EventStream setCaptureMenuEvents(boolean captureMenuEvents) throws IllegalStateException
      Whether opening a context menu should be captured by the stream. This may occur due to mouse or keyboard interaction.

      Includes the eventType contextMenu.

      Parameters:
      captureMenuEvents - New captureMenuEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCaptureMenuEvents

      public boolean getCaptureMenuEvents()
      Whether opening a context menu should be captured by the stream. This may occur due to mouse or keyboard interaction.

      Includes the eventType contextMenu.

      Returns:
      Current captureMenuEvents value. Default value is true

    • setCaptureMoveEvents

      public EventStream setCaptureMoveEvents(boolean captureMoveEvents) throws IllegalStateException
      Whether mouse or touch motion-related events (other than dragging) should be captured by the stream. Multple adjacent "move events" having the same eventType and targetID will be collapsed into one if collapseMoveEvents is true.

      Includes such eventTypes as mouseMove, pointerMove, touchMove, and mouseOut.

      Parameters:
      captureMoveEvents - New captureMoveEvents value. Default value is false
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCaptureMoveEvents

      public boolean getCaptureMoveEvents()
      Whether mouse or touch motion-related events (other than dragging) should be captured by the stream. Multple adjacent "move events" having the same eventType and targetID will be collapsed into one if collapseMoveEvents is true.

      Includes such eventTypes as mouseMove, pointerMove, touchMove, and mouseOut.

      Returns:
      Current captureMoveEvents value. Default value is false

    • setCapturePageEvents

      public EventStream setCapturePageEvents(boolean capturePageEvents) throws IllegalStateException
      Whether page-level events such as a page load or resize should be captured by the stream. Multple adjacent page events having the same eventType will be collapsed into one if collapsePageEvents is true.

      Includes such eventTypes as load, unload, and resize.

      Parameters:
      capturePageEvents - New capturePageEvents value. Default value is false
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCapturePageEvents

      public boolean getCapturePageEvents()
      Whether page-level events such as a page load or resize should be captured by the stream. Multple adjacent page events having the same eventType will be collapsed into one if collapsePageEvents is true.

      Includes such eventTypes as load, unload, and resize.

      Returns:
      Current capturePageEvents value. Default value is false

    • setCaptureWheelEvents

      public EventStream setCaptureWheelEvents(boolean captureWheelEvents) throws IllegalStateException
      Whether mouse wheel events should be captured by the stream. If the preceding "wheel event" has the same targetID and scroll directions, it will be replaced by the current one, subject to collapseWheelEvents, with the delta offsets in the "collapsed" event getting adjusted to be the sum of those from all the original events.

      Includes the eventType mouseWheel.

      Parameters:
      captureWheelEvents - New captureWheelEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getCaptureWheelEvents

      public boolean getCaptureWheelEvents()
      Whether mouse wheel events should be captured by the stream. If the preceding "wheel event" has the same targetID and scroll directions, it will be replaced by the current one, subject to collapseWheelEvents, with the delta offsets in the "collapsed" event getting adjusted to be the sum of those from all the original events.

      Includes the eventType mouseWheel.

      Returns:
      Current captureWheelEvents value. Default value is true

    • setCollapseKeyEvents

      public EventStream setCollapseKeyEvents(boolean collapseKeyEvents) throws IllegalStateException
      Whether to collapse adjacent keyPress events into one event where possible. Self-inserting keys will generally be collapsed by concatenating them into a single string, EventStreamEvent.keyNames. On the other hand, special keys such as "Esc" and "Backspace" will only be collapsed for repeating sequences of the same key, which will be reported as EventStreamEvent.count.

      Note that if an error is thrown while handling an event, it won't be collapsed, but see minErrorReportingInterval.

      Parameters:
      collapseKeyEvents - New collapseKeyEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getCollapseKeyEvents

      public boolean getCollapseKeyEvents()
      Whether to collapse adjacent keyPress events into one event where possible. Self-inserting keys will generally be collapsed by concatenating them into a single string, EventStreamEvent.keyNames. On the other hand, special keys such as "Esc" and "Backspace" will only be collapsed for repeating sequences of the same key, which will be reported as EventStreamEvent.count.

      Note that if an error is thrown while handling an event, it won't be collapsed, but see minErrorReportingInterval.

      Returns:
      Current collapseKeyEvents value. Default value is true
      See Also:

    • setCollapseMoveEvents

      public EventStream setCollapseMoveEvents(boolean collapseMoveEvents) throws IllegalStateException
      Whether mouse or touch-motion related events (including dragging) with the same eventType and targetID should be collapsed into a single event.

      Note that if an error is thrown while handling an event, it won't be collapsed, but see minErrorReportingInterval.

      Parameters:
      collapseMoveEvents - New collapseMoveEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getCollapseMoveEvents

      public boolean getCollapseMoveEvents()
      Whether mouse or touch-motion related events (including dragging) with the same eventType and targetID should be collapsed into a single event.

      Note that if an error is thrown while handling an event, it won't be collapsed, but see minErrorReportingInterval.

      Returns:
      Current collapseMoveEvents value. Default value is true
      See Also:

    • setCollapsePageEvents

      public EventStream setCollapsePageEvents(boolean collapsePageEvents) throws IllegalStateException
      Whether adjacgent page events with the same eventType should be collapsed into a single event.

      Note that if an error is thrown while handling an event, it won't be collapsed, but see minErrorReportingInterval.

      Parameters:
      collapsePageEvents - New collapsePageEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getCollapsePageEvents

      public boolean getCollapsePageEvents()
      Whether adjacgent page events with the same eventType should be collapsed into a single event.

      Note that if an error is thrown while handling an event, it won't be collapsed, but see minErrorReportingInterval.

      Returns:
      Current collapsePageEvents value. Default value is true
      See Also:

    • setCollapseWheelEvents

      public EventStream setCollapseWheelEvents(boolean collapseWheelEvents) throws IllegalStateException
      Whether mouse wheel events with the same targetID and scroll directions should be collapsed into a single event, containing a sum of the delta offsets from the original events.

      Note that if an error is thrown while handling an event, it won't be collapsed, but see minErrorReportingInterval.

      Parameters:
      collapseWheelEvents - New collapseWheelEvents value. Default value is true
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getCollapseWheelEvents

      public boolean getCollapseWheelEvents()
      Whether mouse wheel events with the same targetID and scroll directions should be collapsed into a single event, containing a sum of the delta offsets from the original events.

      Note that if an error is thrown while handling an event, it won't be collapsed, but see minErrorReportingInterval.

      Returns:
      Current collapseWheelEvents value. Default value is true
      See Also:

    • setMaxSize

      public EventStream setMaxSize(Integer maxSize) throws IllegalStateException
      Maximum number of events that will be stored by this EventStream. After maxSize events are captured, the oldest events will be overwritten. Set this property to null to capture events without ever overwriting.
      Parameters:
      maxSize - New maxSize value. Default value is 10000
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created

    • getMaxSize

      public Integer getMaxSize()
      Maximum number of events that will be stored by this EventStream. After maxSize events are captured, the oldest events will be overwritten. Set this property to null to capture events without ever overwriting.
      Returns:
      Current maxSize value. Default value is 10000

    • setMinErrorReportingInterval

      public EventStream setMinErrorReportingInterval(int minErrorReportingInterval) throws IllegalStateException
      Number of seconds that must elapse before another event error will be reported. This allows you to avoid the stream getting flooded with likely duplicate errors that may be rapidly and repeatedly reported, due to mouseMove or repeatedly executing code. Setting the property to zero disables it (avoiding any timestamp checking).

      Note that when an error is reported by the Framework, this property will be ignored if the last captured event triggered the error and has no errorTrace, so that it effectively only prevents adding new events to the stream specifically to report errors. However, an errorTrace attached to an event within the reporting interval of the previous error won't prevent that event from being collapsed.

      Parameters:
      minErrorReportingInterval - New minErrorReportingInterval value. Default value is 10
      Returns:
      EventStream instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the underlying component has been created
      See Also:

    • getMinErrorReportingInterval

      public int getMinErrorReportingInterval()
      Number of seconds that must elapse before another event error will be reported. This allows you to avoid the stream getting flooded with likely duplicate errors that may be rapidly and repeatedly reported, due to mouseMove or repeatedly executing code. Setting the property to zero disables it (avoiding any timestamp checking).

      Note that when an error is reported by the Framework, this property will be ignored if the last captured event triggered the error and has no errorTrace, so that it effectively only prevents adding new events to the stream specifically to report errors. However, an errorTrace attached to an event within the reporting interval of the previous error won't prevent that event from being collapsed.

      Returns:
      Current minErrorReportingInterval value. Default value is 10
      See Also:

    • end

      public EventStreamData end()
      Ends event capturing and returns the EventStreamData. Once ended, capturing cannot be restarted without losing all stored events.
      Returns:
      See Also:

    • getAsSeleneseCommands

      public SeleniumCommand[] getAsSeleneseCommands()
      Creates and returns Selenese that represents the events captured by the stream as an array of Selenium commands. Compare with getAsSeleneseHTML(), where you'll also find more common details.

      Just as when retrieving the Selenese as HTML, if a transformSelenese() function has been defined, it's called before returning the Selenese.

      Returns:
      See Also:

    • getAsSeleneseCommands

      public SeleniumCommand[] getAsSeleneseCommands(SeleneseSettings settings)
      Creates and returns Selenese that represents the events captured by the stream as an array of Selenium commands. Compare with getAsSeleneseHTML(), where you'll also find more common details.

      Just as when retrieving the Selenese as HTML, if a transformSelenese() function has been defined, it's called before returning the Selenese.

      Parameters:
      settings -
      Returns:
      See Also:

    • getAsSeleneseHTML

      public String getAsSeleneseHTML()
      Creates and returns Selenese that represents the events captured by the stream. This Selenese contains Smart GWT-specific locators (scLocators), and Smart GWT command extensions (e.g. "waitForElementClickable") that are discussed in our Selenium overview.

      This method returns the Selenese as a string of HTML table rows, just as in an rctest.html file that you can directly execute with Selenium. Does not include the leading or trailing HTML, such as the <BODY> and <TBODY> tags; you'll need to wrap what's returned with the appropriate outer HTML tags to properly embed the table. If you'd rather have the Selenese returned as an array of Selenium commands, call getAsSeleneseCommands() instead.

      To customize the returned Selenese, see transformSelenese(). Note that if the stream has rolled over, the Selenese for the lost events will not be returned.

      For example, in your Entrypoint class definition, you can declare a stream member like: 

            EventStream eventStream = new EventStream();
      ... time passes where end user is interacting with your app .... Then to retrieve the Selenese you can call something like: 
            String rcTestHTML = "<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">" +
                          "<body><table><tbody>" +
                          MyApp.eventStream.getAsSeleneseHTML(true) +
                          "</tbody></table></body></html>";
      Returns:
      See HTML
      See Also:

    • getAsSeleneseHTML

      public String getAsSeleneseHTML(SeleneseSettings settings)
      Creates and returns Selenese that represents the events captured by the stream. This Selenese contains Smart GWT-specific locators (scLocators), and Smart GWT command extensions (e.g. "waitForElementClickable") that are discussed in our Selenium overview.

      This method returns the Selenese as a string of HTML table rows, just as in an rctest.html file that you can directly execute with Selenium. Does not include the leading or trailing HTML, such as the <BODY> and <TBODY> tags; you'll need to wrap what's returned with the appropriate outer HTML tags to properly embed the table. If you'd rather have the Selenese returned as an array of Selenium commands, call getAsSeleneseCommands() instead.

      To customize the returned Selenese, see transformSelenese(). Note that if the stream has rolled over, the Selenese for the lost events will not be returned.

      For example, in your Entrypoint class definition, you can declare a stream member like: 

            EventStream eventStream = new EventStream();
      ... time passes where end user is interacting with your app .... Then to retrieve the Selenese you can call something like: 
            String rcTestHTML = "<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">" +
                          "<body><table><tbody>" +
                          MyApp.eventStream.getAsSeleneseHTML(true) +
                          "</tbody></table></body></html>";
      Parameters:
      settings -
      Returns:
      See HTML
      See Also:

    • getEvents

      public EventStreamEvent[] getEvents()
      Returns all available captured events, oldest first. At most maxSize events will be returned.
      Returns:
      See Also:

    • getStartTime

      public Date getStartTime()
      Returns when this stream started capturing events (i.e. when start() got called).
      Returns:
      See Also:

    • setEventErrorListener

      public void setEventErrorListener(EventErrorCallback callback)
      Installs a callback that will be called when the EventStream reports an event error, subject to the error reporting interval. The callback will be passed all retained EventStreamEvents captured by the stream since the last time it was called.
      Parameters:
      callback - Callback to fire when the stream encounters an event error, subject to the reporting interval
      See Also:

    • start

      public void start()
      Starts capturing all enabled events. See the overview of EventStream for a list of filter properties you can configure to control which events are captured.

      If called after end(), capturing will restart, but all previously stored events will be lost.

      See Also: