|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_5_1.IMediumAttachment
public class IMediumAttachment
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()
.
IMachine.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:IMedium.getReadOnly()
attribute allows to
quickly determine the kind of the attachment for the given hard
disk. Note that if a normal base hard disk is to be indirectly
attached to a virtual machine with snapshots then a special
procedure calledsmart attachmentis performed (see below).IMachine.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.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 last
IMachine.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 in IMachine.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 |
---|
public IMediumAttachment(org.virtualbox_5_1.jaxws.IMediumAttachment real, org.virtualbox_5_1.ObjectRefManager objMgr, org.virtualbox_5_1.jaxws.VboxPortType port)
Method Detail |
---|
public IMedium getMedium()
public java.lang.String getController()
IMachine.getStorageControllers()
by name.
public java.lang.Integer getPort()
IMachine.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.
public java.lang.Integer getDevice()
IMachine.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.
public DeviceType getType()
public java.lang.Boolean getPassthrough()
public java.lang.Boolean getTemporaryEject()
public java.lang.Boolean getIsEjected()
public java.lang.Boolean getNonRotational()
public java.lang.Boolean getDiscard()
public java.lang.Boolean getHotPluggable()
public IBandwidthGroup getBandwidthGroup()
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |