org.virtualbox_4_3
Class IEventSource

java.lang.Object
  extended by org.virtualbox_4_3.IUnknown
      extended by org.virtualbox_4_3.IEventSource

public class IEventSource
extends IUnknown

Event source. Generally, any object which could generate events can be an event source, or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S), an event source can work with listeners in either active or passive mode. In active mode it is up to the IEventSource implementation to call IEventListener.handleEvent(org.virtualbox_4_3.IEvent), in passive mode the event source keeps track of pending events for each listener and returns available events on demand. See IEventfor an introduction to VirtualBox event handling. Interface ID: {9B6E1AEE-35F3-4F4D-B5BB-ED0ECEFD8538}


Field Summary
 
Fields inherited from class org.virtualbox_4_3.IUnknown
obj, port
 
Constructor Summary
IEventSource(java.lang.String wrapped, org.virtualbox_4_3.jaxws.VboxPortType port)
           
 
Method Summary
 IEventSource createAggregator(java.util.List<IEventSource> subordinates)
          Creates an aggregator event source, collecting events from multiple sources.
 IEventListener createListener()
          Creates a new listener object, useful for passive mode.
 void eventProcessed(IEventListener listener, IEvent event)
          Must be called for waitable events after a particular listener finished its event processing.
 java.lang.Boolean fireEvent(IEvent event, java.lang.Integer timeout)
          Fire an event for this source.
 IEvent getEvent(IEventListener listener, java.lang.Integer timeout)
          Get events from this peer's event queue (for passive mode).
static IEventSource queryInterface(IUnknown obj)
           
 void registerListener(IEventListener listener, java.util.List<VBoxEventType> interesting, java.lang.Boolean active)
          Register an event listener.
 void unregisterListener(IEventListener listener)
          Unregister an event listener.
 
Methods inherited from class org.virtualbox_4_3.IUnknown
getRemoteWSPort, getWrapped, releaseRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IEventSource

public IEventSource(java.lang.String wrapped,
                    org.virtualbox_4_3.jaxws.VboxPortType port)
Method Detail

queryInterface

public static IEventSource queryInterface(IUnknown obj)

createListener

public IEventListener createListener()
Creates a new listener object, useful for passive mode.


createAggregator

public IEventSource createAggregator(java.util.List<IEventSource> subordinates)
Creates an aggregator event source, collecting events from multiple sources. This way a single listener can listen for events coming from multiple sources, using a single blocking getEvent(org.virtualbox_4_3.IEventListener,Integer)on the returned aggregator.

Parameters:
subordinates - Subordinate event source this one aggregates.
Returns:
Event source aggregating passed sources.

registerListener

public void registerListener(IEventListener listener,
                             java.util.List<VBoxEventType> interesting,
                             java.lang.Boolean active)
Register an event listener.

Parameters:
listener - Listener to register.
interesting - Event types listener is interested in. One can use wildcards like - VBoxEventType.Anyto specify wildcards, matching more than one event.
active - Which mode this listener is operating in. In active mode, IEventListener.handleEvent(org.virtualbox_4_3.IEvent)is called directly. In passive mode, an internal event queue is created for this this IEventListener. For each event coming in, it is added to queues for all interested registered passive listeners. It is then up to the external code to call the listener's IEventListener.handleEvent(org.virtualbox_4_3.IEvent)method. When done with an event, the external code must call eventProcessed(org.virtualbox_4_3.IEventListener,org.virtualbox_4_3.IEvent). NOTE: To avoid system overload, the VirtualBox server process checks if passive event listeners call getEvent(org.virtualbox_4_3.IEventListener,Integer)frequently enough. In the current implementation, if more than 500 pending events are detected for a passive event listener, it is forcefully unregistered by the system, and further getEvent(org.virtualbox_4_3.IEventListener,Integer)calls will return VBOX_E_OBJECT_NOT_FOUND.

unregisterListener

public void unregisterListener(IEventListener listener)
Unregister an event listener. If listener is passive, and some waitable events are still in queue they are marked as processed automatically.

Parameters:
listener - Listener to unregister.

fireEvent

public java.lang.Boolean fireEvent(IEvent event,
                                   java.lang.Integer timeout)
Fire an event for this source.

Parameters:
event - Event to deliver.
timeout - Maximum time to wait for event processing (if event is waitable), in ms; 0 = no wait, -1 = indefinite wait.
Returns:
true if an event was delivered to all targets, or is non-waitable.

getEvent

public IEvent getEvent(IEventListener listener,
                       java.lang.Integer timeout)
Get events from this peer's event queue (for passive mode). Calling this method regularly is required for passive event listeners to avoid system overload; see registerListener(org.virtualbox_4_3.IEventListener,List,Boolean)for details.

Parameters:
listener - Which listener to get data for.
timeout - Maximum time to wait for events, in ms; 0 = no wait, -1 = indefinite wait.
Returns:
Event retrieved, or null if none available. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDListener is not registered, or autounregistered.

eventProcessed

public void eventProcessed(IEventListener listener,
                           IEvent event)
Must be called for waitable events after a particular listener finished its event processing. When all listeners of a particular event have called this method, the system will then call IEvent.setProcessed().

Parameters:
listener - Which listener processed event.
event - Which event.