Class ISession

  extended by
      extended by

public class ISession
extends VBoxObject

The ISession interface represents a serialization primitive for virtual machines. With VirtualBox, every time one wishes to manipulate a virtual machine (e.g. change its settings or start execution), a session object is required. Such an object must be passed to one of the session methods that open the given session, which then initiates the machine manipulation. A session serves several purposes: it identifies to the inter-process VirtualBox code which process is currently working with the virtual machine, and it ensures that there are no incompatible requests from several processes for the same virtual machine. Session objects can therefore be thought of as mutex semaphores that lock virtual machines to prevent conflicting accesses from several processes. How sessions objects are used depends on whether you use the Main API via COM or via the webservice:

Sessions are mainly used in two variations:One also can attach to an existing direct session already opened by another process (for example, in order to send a control request to the virtual machine such as the pause or the reset request). This is done by calling IVirtualBox.openExistingSession(, java.util.UUID).
Unless you are trying to write a new VirtualBox front-end that performs direct machine execution (like the VirtualBox or VBoxSDL front-ends), don't call IConsole.powerUp() in a direct session opened by IVirtualBox.openSession(, java.util.UUID) and use this session only to change virtual machine settings. If you simply want to start virtual machine execution using one of the existing front-ends (for example the VirtualBox GUI or headless server), simply use IVirtualBox.openRemoteSession(, java.util.UUID, java.lang.String, java.lang.String); these front-ends will power up the machine automatically for you.

Field Summary
Fields inherited from class
_this, port
Constructor Summary
ISession(String _this, VboxPortType port)
Method Summary
 void close()
          Closes a session that was previously opened.
 IConsole getConsole()
          Console object associated with this session.
 IMachine getMachine()
          Machine object associated with this session.
 SessionState getState()
          Current state of this session.
 SessionType getType()
          Type of this session.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail


public ISession(String _this,
                VboxPortType port)
Method Detail


public SessionState getState()
Current state of this session.


public SessionType getType()
Type of this session. The value of this attribute is valid only if the session is currently open (i.e. its #state is SessionType_SessionOpen), otherwise an error will be returned.


public IMachine getMachine()
Machine object associated with this session.


public IConsole getConsole()
Console object associated with this session.


public void close()
Closes a session that was previously opened. It is recommended that every time an "open session" method (such as IVirtualBox.openRemoteSession(, java.util.UUID, java.lang.String, java.lang.String) or IVirtualBox.openSession(, java.util.UUID)) has been called to manipulate a virtual machine, the caller invoke ISession::close() when it's done doing so. Since sessions are serialization primitives much like ordinary mutexes, they are best used the same way: for each "open" call, there should be a matching "close" call, even when errors occur. Otherwise, if a direct session for a machine opened with IVirtualBox.openSession(, java.util.UUID) is not explicitly closed when the application terminates, the state of the machine will be set to MachineState_Aborted on the server. Generally, it is recommended to close all open sessions explicitly before terminating the application (regardless of the reason for the termination).
Do not expect the session state (ISession#state to return to "Closed" immediately after you invoke ISession::close(), particularly if you have started a remote session to execute the VM in a new process. The session state will automatically return to "Closed" once the VM is no longer executing, which can of course take a very long time.
Session is not open.

Copyright © 2009. All Rights Reserved.