|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_4_1.IUnknown
org.virtualbox_4_1.IEvent
public class IEvent
Abstract parent interface for VirtualBox events. Actual events will typically implement
a more specific interface which derives from this (see below).
Introduction to VirtualBox events
Generally speaking, an event (represented by this interface) signals that something
happened, while an event listener (see IEventListener
) represents an
entity that is interested in certain events. In order for this to work with
unidirectional protocols (i.e. web services), the concepts of passive and active
listener are used.
Event consumers can register themselves as listeners, providing an array of
events they are interested in (see IEventSource.registerListener(org.virtualbox_4_1.IEventListener,List,Boolean)
).
When an event triggers, the listener is notified about the event. The exact
mechanism of the notification depends on whether the listener was registered as
an active or passive listener:
IEventSource
implementation maintains an event queue for each passive listener, and
newly arrived events are put in this queue. When the listener calls
IEventSource.getEvent(org.virtualbox_4_1.IEventListener,Integer)
, first element from its internal event
queue is returned. When the client completes processing of an event,
the IEventSource.eventProcessed(org.virtualbox_4_1.IEventListener,org.virtualbox_4_1.IEvent)
function must be called,
acknowledging that the event was processed. It supports implementing
waitable events. On passive listener unregistration, all events from its
queue are auto-acknowledged.
IVetoEvent
) where a
listeners might veto a certain action, and thus the event producer has to make
sure that all listeners have processed the event and not vetoed before taking
the action.
A given event may have both passive and active listeners at the same time.
Using events
Any VirtualBox object capable of producing externally visible events provides an
eventSource read-only attribute, which is of the type IEventSource
.
This event source object is notified by VirtualBox once something has happened, so
consumers may register event listeners with this event source. To register a listener,
an object implementing the IEventListener
interface must be provided.
For active listeners, such an object is typically created by the consumer, while for
passive listeners IEventSource.createListener()
should be used. Please
note that a listener created with IEventSource.createListener()
must not be used as an active listener.
Once created, the listener must be registered to listen for the desired events
(see IEventSource.registerListener(org.virtualbox_4_1.IEventListener,List,Boolean)
), providing an array of
VBoxEventType
enums. Those elements can either be the individual
event IDs or wildcards matching multiple event IDs.
After registration, the callback's IEventListener.handleEvent(org.virtualbox_4_1.IEvent)
method is
called automatically when the event is triggered, while passive listeners have to call
IEventSource.getEvent(org.virtualbox_4_1.IEventListener,Integer)
and IEventSource.eventProcessed(org.virtualbox_4_1.IEventListener,org.virtualbox_4_1.IEvent)
in
an event processing loop.
The IEvent interface is an abstract parent interface for all such VirtualBox events
coming in. As a result, the standard use pattern inside IEventListener.handleEvent(org.virtualbox_4_1.IEvent)
or the event processing loop is to check the getType()
attribute of the event and
then cast to the appropriate specific interface using QueryInterface().
Interface ID: {0CA2ADBA-8F30-401B-A8CD-FE31DBE839C0}
Field Summary |
---|
Fields inherited from class org.virtualbox_4_1.IUnknown |
---|
obj, port |
Constructor Summary | |
---|---|
IEvent(java.lang.String wrapped,
org.virtualbox_4_1.jaxws.VboxPortType port)
|
Method Summary | |
---|---|
IEventSource |
getSource()
Source of this event. |
VBoxEventType |
getType()
Event type. |
java.lang.Boolean |
getWaitable()
If we can wait for this event being processed. |
static IEvent |
queryInterface(IUnknown obj)
|
void |
setProcessed()
Internal method called by the system when all listeners of a particular event have called IEventSource.eventProcessed(org.virtualbox_4_1.IEventListener,org.virtualbox_4_1.IEvent) . |
java.lang.Boolean |
waitProcessed(java.lang.Integer timeout)
Wait until time outs, or this event is processed. |
Methods inherited from class org.virtualbox_4_1.IUnknown |
---|
getRemoteWSPort, getWrapped, releaseRemote |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public IEvent(java.lang.String wrapped, org.virtualbox_4_1.jaxws.VboxPortType port)
Method Detail |
---|
public VBoxEventType getType()
public IEventSource getSource()
public java.lang.Boolean getWaitable()
waitProcessed(Integer)
returns immediately,
and setProcessed()
doesn't make sense. Non-waitable events are generally better performing,
as no additional overhead associated with waitability imposed.
Waitable events are needed when one need to be able to wait for particular event processed,
for example for vetoable changes, or if event refers to some resource which need to be kept immutable
until all consumers confirmed events.
public static IEvent queryInterface(IUnknown obj)
public void setProcessed()
IEventSource.eventProcessed(org.virtualbox_4_1.IEventListener,org.virtualbox_4_1.IEvent)
. This should not be called by client code.
public java.lang.Boolean waitProcessed(java.lang.Integer timeout)
timeout
- Maximum time to wait for event processeing, in ms;
0 = no wait, -1 = indefinite wait.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |