org.virtualbox_5_1
Class IMediumAttachment

java.lang.Object
  extended by org.virtualbox_5_1.IMediumAttachment

public class IMediumAttachment
extends java.lang.Object

The IMediumAttachment interface links storage media to virtual machines. For each medium (IMedium) which has been attached to a storage controller (IStorageController) of a machine (IMachine) via theIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_1.DeviceType,org.virtualbox_5_1.IMedium)method, one instance of IMediumAttachment is added to the machine'sIMachine.getMediumAttachments()array attribute. Each medium attachment specifies the storage controller as well as a port and device number and the IMedium instance representing a virtual hard disk or floppy or DVD image. For removable media (DVDs or floppies), there are two additional options. For one, the IMedium instance can be null to represent an empty drive with no media inserted (seeIMachine.mountMedium(String,Integer,Integer,org.virtualbox_5_1.IMedium,Boolean)); secondly, the medium can be one of the pseudo-media for host drives listed inIHost.getDVDDrives()orIHost.getFloppyDrives().

Attaching Hard Disks

Hard disks are attached to virtual machines using theIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_1.DeviceType,org.virtualbox_5_1.IMedium)method and detached using theIMachine.detachDevice(String,Integer,Integer)method. Depending on a medium's type (seeIMedium.getType()), hard disks are attached eitherdirectlyorindirectly. When a hard disk is being attached directly, it is associated with the virtual machine and used for hard disk operations when the machine is running. When a hard disk is being attached indirectly, a new differencing hard disk linked to it is implicitly created and this differencing hard disk is associated with the machine and used for hard disk operations. This also means that ifIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_1.DeviceType,org.virtualbox_5_1.IMedium)performs a direct attachment then the same hard disk will be returned in response to the subsequentIMachine.getMedium(String,Integer,Integer)call; however if an indirect attachment is performed thenIMachine.getMedium(String,Integer,Integer)will return the implicitly created differencing hard disk, not the original one passed toIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_1.DeviceType,org.virtualbox_5_1.IMedium). In detail:Note that the same hard disk, regardless of its type, may be attached to more than one virtual machine at a time. In this case, the machine that is started first gains exclusive access to the hard disk and attempts to start other machines having this hard disk attached will fail until the first machine is powered down. Detaching hard disks is performed in adeferredfashion. This means that the given hard disk remains associated with the given machine after a successfulIMachine.detachDevice(String,Integer,Integer)call untilIMachine.saveSettings()is called to save all changes to machine settings to disk. This deferring is necessary to guarantee that the hard disk configuration may be restored at any time by a call toIMachine.discardSettings()before the settings are saved (committed). Note that ifIMachine.discardSettings()is called after indirectly attaching some hard disks to the machine but before a call toIMachine.saveSettings()is made, it will implicitly delete all differencing hard disks implicitly created byIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_1.DeviceType,org.virtualbox_5_1.IMedium)for these indirect attachments. Such implicitly created hard disks will also be immediately deleted when detached explicitly using theIMachine.detachDevice(String,Integer,Integer)call if it is made beforeIMachine.saveSettings(). This implicit deletion is safe because newly created differencing hard disks do not contain any user data. However, keep in mind that detaching differencing hard disks that were implicitly created byIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_1.DeviceType,org.virtualbox_5_1.IMedium)before the lastIMachine.saveSettings()call willnotimplicitly delete them as they may already contain some data (for example, as a result of virtual machine execution). If these hard disks are no more necessary, the caller can always delete them explicitly usingIMedium.deleteStorage()after they are actually de-associated from this machine by theIMachine.saveSettings()call.

Smart Attachment

When normal base or immutable hard disks are indirectly attached to a virtual machine then some additional steps are performed to make sure the virtual machine will have the most recent "view" of the hard disk being attached. These steps include walking through the machine's snapshots starting from the current one and going through ancestors up to the first snapshot. Hard disks attached to the virtual machine in all of the encountered snapshots are checked whether they are descendants of the given normal base or immutable hard disk. The first found child (which is the differencing hard disk) will be used instead of the normal base or immutable hard disk as a parent for creating a new differencing hard disk that will be actually attached to the machine. And only if no descendants are found or if the virtual machine does not have any snapshots then the normal base or immutable hard disk will be used itself as a parent for this differencing hard disk. It is easier to explain what smart attachment does using the following example:
BEFORE attaching B.vdi:       AFTER attaching B.vdi:

Snapshot 1 (B.vdi)            Snapshot 1 (B.vdi)
Snapshot 2 (D1->B.vdi)        Snapshot 2 (D1->B.vdi)
Snapshot 3 (D2->D1.vdi)       Snapshot 3 (D2->D1.vdi)
Snapshot 4 (none)             Snapshot 4 (none)
CurState   (none)             CurState   (D3->D2.vdi)

NOT
...
CurState   (D3->B.vdi)
The first column is the virtual machine configuration before the base hard diskB.vdiis attached, the second column shows the machine after this hard disk is attached. Constructs likeD1->B.vdiand similar mean that the hard disk that is actually attached to the machine is a differencing hard disk,D1.vdi, which is linked to (based on) another hard disk,B.vdi. As we can see from the example, the hard diskB.vdiwas detached from the machine before taking Snapshot 4. Later, after Snapshot 4 was taken, the user decides to attachB.vdiagain.B.vdihas dependent child hard disks (D1.vdi,D2.vdi), therefore it cannot be attached directly and needs an indirect attachment (i.e. implicit creation of a new differencing hard disk). Due to the smart attachment procedure, the new differencing hard disk (D3.vdi) will be based onD2.vdi, not onB.vdiitself, sinceD2.vdiis the most recent view ofB.vdiexisting for this snapshot branch of the given virtual machine. Note that if there is more than one descendant hard disk of the given base hard disk found in a snapshot, and there is an exact device, channel and bus match, then this exact match will be used. Otherwise, the youngest descendant will be picked up. There is one more important aspect of the smart attachment procedure which is not related to snapshots at all. Before walking through the snapshots as described above, the backup copy of the current list of hard disk attachment is searched for descendants. This backup copy is created when the hard disk configuration is changed for the first time after the lastIMachine.saveSettings()call and used byIMachine.discardSettings()to undo the recent hard disk changes. When such a descendant is found in this backup copy, it will be simply re-attached back, without creating a new differencing hard disk for it. This optimization is necessary to make it possible to re-attach the base or immutable hard disk to a different bus, channel or device slot without losing the contents of the differencing hard disk actually attached to the machine in place of it. Interface ID: {3785B3F7-7B5F-4000-8842-AD0CC6AB30B7}


Constructor Summary
IMediumAttachment(org.virtualbox_5_1.jaxws.IMediumAttachment real, org.virtualbox_5_1.ObjectRefManager objMgr, org.virtualbox_5_1.jaxws.VboxPortType port)
           
 
Method Summary
 IBandwidthGroup getBandwidthGroup()
          The bandwidth group this medium attachment is assigned to.
 java.lang.String getController()
          Name of the storage controller of this attachment; this refers to one of the controllers inIMachine.getStorageControllers()by name.
 java.lang.Integer getDevice()
          Device slot number of this attachment.
 java.lang.Boolean getDiscard()
          Whether the associated medium supports discarding unused blocks.
 java.lang.Boolean getHotPluggable()
          Whether this attachment is hot pluggable or not.
 java.lang.Boolean getIsEjected()
          Signals that the removable medium has been ejected.
 IMedium getMedium()
          Medium object associated with this attachment; it can be null for removable devices.
 java.lang.Boolean getNonRotational()
          Whether the associated medium is non-rotational.
 java.lang.Boolean getPassthrough()
          Pass I/O requests through to a device on the host.
 java.lang.Integer getPort()
          Port number of this attachment.
 java.lang.Boolean getTemporaryEject()
          Whether guest-triggered eject results in unmounting the medium.
 DeviceType getType()
          Device type of this attachment.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IMediumAttachment

public IMediumAttachment(org.virtualbox_5_1.jaxws.IMediumAttachment real,
                         org.virtualbox_5_1.ObjectRefManager objMgr,
                         org.virtualbox_5_1.jaxws.VboxPortType port)
Method Detail

getMedium

public IMedium getMedium()
Medium object associated with this attachment; it can be null for removable devices.

Returns:
org.virtualbox_5_1.IMedium

getController

public java.lang.String getController()
Name of the storage controller of this attachment; this refers to one of the controllers inIMachine.getStorageControllers()by name.

Returns:
String

getPort

public java.lang.Integer getPort()
Port number of this attachment. SeeIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_1.DeviceType,org.virtualbox_5_1.IMedium)for the meaning of this value for the different controller types.

Returns:
Integer

getDevice

public java.lang.Integer getDevice()
Device slot number of this attachment. SeeIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_1.DeviceType,org.virtualbox_5_1.IMedium)for the meaning of this value for the different controller types.

Returns:
Integer

getType

public DeviceType getType()
Device type of this attachment.

Returns:
org.virtualbox_5_1.DeviceType

getPassthrough

public java.lang.Boolean getPassthrough()
Pass I/O requests through to a device on the host.

Returns:
Boolean

getTemporaryEject

public java.lang.Boolean getTemporaryEject()
Whether guest-triggered eject results in unmounting the medium.

Returns:
Boolean

getIsEjected

public java.lang.Boolean getIsEjected()
Signals that the removable medium has been ejected. This is not necessarily equivalent to having a null medium association.

Returns:
Boolean

getNonRotational

public java.lang.Boolean getNonRotational()
Whether the associated medium is non-rotational.

Returns:
Boolean

getDiscard

public java.lang.Boolean getDiscard()
Whether the associated medium supports discarding unused blocks.

Returns:
Boolean

getHotPluggable

public java.lang.Boolean getHotPluggable()
Whether this attachment is hot pluggable or not.

Returns:
Boolean

getBandwidthGroup

public IBandwidthGroup getBandwidthGroup()
The bandwidth group this medium attachment is assigned to.

Returns:
org.virtualbox_5_1.IBandwidthGroup