com.sun.xml.ws.commons.virtualbox.IHardDisk Maven / Gradle / Ivy
package com.sun.xml.ws.commons.virtualbox;
import java.math.BigInteger;
import java.util.List;
import java.util.UUID;
import javax.xml.ws.WebServiceException;
/**
* The IHardDisk interface represents a virtual hard disk drive
* used by virtual machines.
*
* The virtual hard disk drive virtualizes the hard disk hardware and
* looks like a regular hard disk inside the virtual machine and
* the guest OS.Storage Types
The {@link HardDiskStorageType} of the
* virtual hard disk determines where and how it stores its data
* (sectors). Currently, the following storage types are supported:- Virtual Disk Image (VDI), a regular file in the file system
* of the host OS (represented by the {@link IVirtualDiskImage} interface). This file has a special format optimized so that unused
* sectors of data occupy much less space than on a physical hard disk.
- iSCSI Remote Disk, a disk accessed via the Internet SCSI
* protocol over a TCP/IP network link (represented by the {@link IISCSIHardDisk} interface).
- VMware VMDK image, a regular file in the file system of the
* host OS (represented by the {@link IVMDKImage} interface).
* Note that the regular file may be just a descriptor referring to
* further files, so don't make assumptions about the OS representation
* of a VMDK image.
- Custom HardDisk, a disk accessed via a plugin which is loaded
* when the disk is accessed (represented by the {@link ICustomHardDisk} interface).
- Virtual PC VHD Image, a regular file in the file system of the
* host OS (represented by the {@link IVHDImage} interface).
The storage type of the particular hard disk object is indicated by
* the {@link #storageType} property.
*
* Each storage type is represented by its own interface (as shown
* above), that allows to query and set properties and perform
* operations specific to that storage type. When an IHardDisk object
* reports it uses some particular storage type, it also guaranteed to
* support the corresponding interface which you can query. And vice
* versa, every object that supports a storage-specific interface, also
* supports IHardDisk.Virtual Hard Disk Types
The {@link HardDiskType} of the virtual hard disk
* determines how it is attached to the virtual machine when you call {@link IMachine#attachHardDisk()} and what happens to it when
* a {@link ISnapshot} of the virtual machine is
* taken.
*
* There are three types of virtual hard disks:- Normal
- Immutable
- Writethrough
The virtual disk type is indicated by the {@link #type} property. Each of the above types is described in detail further
* down.
*
* There is also a forth, "hidden" virtual disk type:Differencing. It is "hidden" because you cannot directly
* create hard disks of this type -- they are automatically created by
* VirtualBox when necessary.Differencing Hard DisksUnlike disks of other types (that are similar to real hard disks),
* the differencing hard disk does not store the full range of data
* sectors. Instead, it stores only a subset of sectors of some other
* disk that were changed since the differencing hard disk has been
* created. Thus, every differencing hard disk has a parent hard disk
* it is linked to, and represents the difference between the initial
* and the current hard disk state. A differencing hard disk can be
* linked to another differencing hard disk -- this way, differencing
* hard disks can form a branch of changes. More over, a given virtual
* hard disk can have more than one differencing hard disk linked to
* it.
*
* A disk the differencing hard disk is linked to (or, in other words,
* based on) is called aparenthard disk and is accessible through
* the {@link #parent} property. Similarly, all existing differencing
* hard disks for a given parent hard disk are called itschildhard
* disks (and accessible through the {@link #children} property).
*
* All differencing hard disks use Virtual Disk Image files to store
* changed sectors. They have the {@link #type} property set to
* Normal, but can be easily distinguished from normal hard disks using
* the {@link #parent} property: all differencing hard disks have
* a parent, while all normal hard disks don't.
*
* When the virtual machine makes an attempt to read a sector that is
* missing in a differencing hard disk, its parent is accessed to
* resolve the sector in question. This process continues until the
* sector is found, or until the root hard disk is encountered, which
* always contains all sectors. As a consequence, - The virtual hard disk geometry seen by the guest OS is
* always defined by the root hard disk.
- All hard disks on a branch, up to the root, must be {@link #accessible} for a given differencing hard disk in order
* to let it function properly when the virtual machine is
* running.
Differencing hard disks can be implicitly created by VirtualBox in
* the following cases:- When a hard disk isindirectlyattached to the virtual
* machine using {@link IMachine#attachHardDisk()}. In this
* case, all disk writes performed by the guest OS will go to the
* created diffferencing hard disk, as opposed to thedirectattachment, where all changes are written to the
* attached hard disk itself.
- When a {@link ISnapshot} of the virtual machine
* is taken. After that, disk writes to hard disks the differencing
* ones have been created for, will be directed to those differencing
* hard disks, to preserve the contents of the original disks.
Whether to create a differencing hard disk or not depends on the
* type of the hard disk attached to the virtual machine. This is
* explained below.
*
* Note that in the current implementation, only the {@link VirtualDiskImage} storage type is used to
* represent differencing hard disks. In other words, all
* differencing hard disks are {@link IVirtualDiskImage} objects.Normal Hard DisksNormal hard disks are the most commonly used virtual hard disk. A
* normal hard disk is attached to the machine directly if it is not
* already attached to some other machine. Otherwise, an attempt to
* make an indirect attachment through a differencing hard disk will be
* made. This attempt will fail if the hard disk is attached to a
* virtual machine without snapshots (because it's impossible to create
* a differencing hard disk based on a hard disk that is subject to
* change).
*
* When an indirect attachment takes place, in the simplest case, where
* the machine the hard disk is being attached to doesn't have
* snapshots, the differencing hard disk will be based on the normal
* hard disk being attached. Otherwise, the first (i.e. the most
* recent) descendant of the given normal hard disk found in the
* current snapshot branch (starting from the current snapshot and
* going up to the root) will be actually used as a base.
*
* Note that when you detach an indirectly attached hard disk from the
* machine, the created differencing hard disk image is simplydeleted, soall changes are lost. If you attach the
* same disk again, a clean differencing disk will be created based on
* the most recent child, as described above.
*
* When taking a snapshot, the contents of all normal hard disks (and
* all differencing disks whose roots are normal hard disks) currently
* attached to the virtual machine is preserved by creating
* differencing hard disks based on them.Immutable Hard DisksImmutable hard disks can be used to provide a sort of read-only
* access. An immutable hard disk is always attached indirectly. The
* created differencing hard disk is automatically wiped out (recreated
* from scratch) every time you power off the virtual machine. Thus,
* the contents of the immutable disk remains unchanged between runs.
*
* Detaching an immutable hard disk deletes the differencing disk
* created for it, with the same effect as in case with normal hard
* disks.
*
* When taking a snapshot, the differencing part of the immutable
* hard disk is cloned (i.e. copied to a separate Virtual Disk Image
* file) without any changes. This is necessary to preserve the exact
* virtual machine state when you create an online snapshot.Writethrough Hard DisksHard disks of this type are always attached directly. This means
* that every given writethrough hard disk can be attached only to one
* virtual machine at a time.
*
* It is impossible to take a snapshot of a virtual machine with the
* writethrough hard disk attached, because taking a snapshot implies
* saving the execution state and preserving the contents of all hard
* disks, but writethrough hard disks cannot be preserved. Preserving
* hard disk contents is necessary to ensure the guest OS stored in the
* snapshot will get the same hard disk state when restored, which is
* especially important when it has open file handles or when there are
* cached files and directories stored in memory.Creating, Opening and Registering Hard Disks
Non-differencing hard disks are either created from scratch using {@link IVirtualBox#createHardDisk()} or opened from a VDI file
* using {@link IVirtualBox#openVirtualDiskImage()}(only for hard
* disks using the VirtualDiskImage storage type). Once a hard disk is
* created or opened, it needs to be registered using {@link IVirtualBox#registerHardDisk()} to make it available for
* attaching to virtual machines. See the documentation of individual
* interfaces for various storage types to get more information.
*
* Differencing hard disks are never created explicitly and cannot
* be registered or unregistered; they are automatically registered
* upon creation and deregistered when deleted.More about Indirect Hard Disk Attachments
Normally, when you attach a hard disk to the virtual machine, and then
* query the corresponding attachment using {@link IMachine#getHardDisk()} or {@link IMachine#hardDiskAttachments} you will get the same hard
* disk object, whose UUID you passed earlier to {@link IMachine#attachHardDisk()}. However, when an indirect
* attachment takes place, calling {@link IMachine#getHardDisk()} will return a differencing hard disk object, that is either based on the
* attached hard disk or on another differencing hard disk, the attached
* hard disk is eventually a root for (as described above). In both cases
* the returned hard disk object is the object the virtual machine actually
* uses to perform disk writes to.
*
* Regardless of whether the attachment is direct or indirect, the {@link #machineId} property of the attached disk will contain an
* UUID of the machine object {@link IMachine#attachHardDisk()} has been called on.
*
* Note that both {@link IMachine#attachHardDisk()} and {@link IMachine#detachHardDisk()} arelazyoperations. In
* particular, this means that when an indirect attachment is made,
* differencing hard disks are not created until machine settings are
* committed using {@link IMachine#saveSettings()}. Similarly, when a
* differencing hard disk is detached, it is not deleted until {@link IMachine#saveSettings()} is called. Calling {@link IMachine#discardSettings()} cancels all lazy attachments or
* detachments made since the last commit and effectively restores the
* previous set of hard disks.Hard Disk Accessibility
The {@link #accessible} attribute of the hard disk object
* defines the accessibility state of the respective hard disk storage
* (for example, the VDI file for IVirtualDiskImage objects). If the
* value of this attribute isfalsethen some hard disk
* attributes may contain invalid or outdated values (for example, the
* virtual or the actual hard disk size) until a new accessibility
* check is done that returnstrue(see the attribute
* description for more details).Because of the possible slowness of the accessibility check,
* it is not implicitly performed upon the VirtualBox server startup
* (to prevent the application freeze). In partcular, this means that
* if you try to read hard disk properties that depend on the
* accessibility state without first reading the value of the {@link #accessible} attribute and ensuring it's value istrue, you will get wrong (zero) values.
*
*/
public class IHardDisk {
public final VboxPortType port;
public final String _this;
public IHardDisk(String _this, VboxPortType port) {
this._this = _this;
this.port = port;
}
/**
* UUID of the hard disk. For newly created hard disk objects,
* this value is a randomly generated UUID.
*
*/
public UUID getId() {
try {
String retVal = port.iHardDiskGetId(_this);
return UUID.fromString(retVal);
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Optional description of the hard disk. For a newly created hard
* disk, this value isnull.For some storage types, reading this property is
* meaningless when {@link #accessible} isfalse.
* Also, you cannot assign it a new value in this case.
*
*/
public String getDescription() {
try {
String retVal = port.iHardDiskGetDescription(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Optional description of the hard disk. For a newly created hard
* disk, this value isnull.For some storage types, reading this property is
* meaningless when {@link #accessible} isfalse.
* Also, you cannot assign it a new value in this case.
*
*/
public void setDescription(String value) {
try {
port.iHardDiskSetDescription(_this, value);
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Storage type of this hard disk.
*
* Storage type is defined when you open or create a new hard disk
* object.
*
*/
public HardDiskStorageType getStorageType() {
try {
HardDiskStorageType retVal = port.iHardDiskGetStorageType(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Storage location of this hard disk. The returned string serves
* for informational purposes only. To access detailed information
* about the storage, query the appropriate storage-specific
* interface.
*
*/
public String getLocation() {
try {
String retVal = port.iHardDiskGetLocation(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Type (behavior) of this hard disk. For a newly created or opened hard
* disk, this value is {@link HardDiskType#Normal}.In the current implementation, this property can be
* changed only on an unregistered hard disk object. This may be
* changed later.
*
*/
public HardDiskType getType() {
try {
HardDiskType retVal = port.iHardDiskGetType(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Type (behavior) of this hard disk. For a newly created or opened hard
* disk, this value is {@link HardDiskType#Normal}.In the current implementation, this property can be
* changed only on an unregistered hard disk object. This may be
* changed later.
*
*/
public void setType(HardDiskType value) {
try {
port.iHardDiskSetType(_this, value);
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Parent of this hard disk (a hard disk this one is directly based
* on).
*
* Only differencing hard disks have parents, so anullobject is returned for a hard disk of any other type.
*
*/
public IHardDisk getParent() {
try {
String retVal = port.iHardDiskGetParent(_this);
return new IHardDisk(retVal, port);
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Children of this hard disk (all differencing hard disks for
* those this one is a parent). An empty collection is returned, if
* this hard disk doesn't have any children.
*
*/
public List getChildren() {
try {
ArrayOfIHardDisk retVal = port.iHardDiskGetChildren(_this);
return Helper.wrap(IHardDisk.class, port, ((retVal == null)?null:retVal.getArray()));
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Root hard disk of this hard disk. If this hard disk is a
* differencing hard disk, its root hard disk is the first disk on
* the branch. For all other types of hard disks, this property
* returns the hard disk object itself (i.e. the same object you
* read this property on).
*
*/
public IHardDisk getRoot() {
try {
String retVal = port.iHardDiskGetRoot(_this);
return new IHardDisk(retVal, port);
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Whether the hard disk storage is currently accessible or not.
* The storage, for example, can be unaccessible if it doesn't exist
* or if it is placed on a network resource that is not available
* by the time this attribute is read.
*
* In the current implementation, the value of this property is
* alsofalseif this hard disk is attached to a running
* virtual machine.
*
* The accessibility check is performed automatically every time
* this attribute is read. You should keep it in mind that this check
* may be slow and can block the calling thread for a long time (for
* example, if the network resourse where the hard disk storage is
* located is down).
*
* The following attributes of the hard disk object are considered
* to be invalid when this attribute isfalse:- {@link #size}
- {@link #actualSize}
Individual hard disk storage type interfaces may define
* additional attributes that depend on the accessibility state.
*
*/
public boolean getAccessible() {
try {
boolean retVal = port.iHardDiskGetAccessible(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Whether the whole hard disk branch, starting from this image and
* going through its ancestors up to the root, is accessible or
* not.
*
* This property makes sense only for differencing hard disks. For
* all other types of hard disks it returns the same value as {@link #accessible}.
*
*/
public boolean getAllAccessible() {
try {
boolean retVal = port.iHardDiskGetAllAccessible(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* String describing the reason of inaccessibility of this hard
* disk after the last call to {@link #accessible} that
* returnedfalse. Anullvalue of this property
* means that the last accessibility check returnedtrue.
*
*/
public String getLastAccessError() {
try {
String retVal = port.iHardDiskGetLastAccessError(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Logical size of this hard disk (in megabytes), as reported to the
* guest OS running inside the vurtual machine this disk is
* attached to. The logical size is defined when the hard disk is
* created.Reading this property on a differencing hard disk will
* return the size of its root hard disk.
Reading this property is meaningless when {@link #accessible} isfalse
*
*/
public BigInteger getSize() {
try {
BigInteger retVal = port.iHardDiskGetSize(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* Physical size of the storage used to store hard disk data (in
* bytes). This size is usually less than the logical size of the
* hard disk, depending on the storage type and on the size
* optimization method used for that storage.Reading this property is meaningless when {@link #accessible} isfalse
*
*/
public BigInteger getActualSize() {
try {
BigInteger retVal = port.iHardDiskGetActualSize(_this);
return retVal;
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* UUID of the machine this hard disk is attached to (or anullUUID if it is not attached).Immutable hard disks are never attached directly, so this
* attribute is alwaysnullin this case.
*
*/
public UUID getMachineId() {
try {
String retVal = port.iHardDiskGetMachineId(_this);
return UUID.fromString(retVal);
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
/**
* UUID of the {@link ISnapshot} this hard disk
* is associated with (ornullUUID if it is not
* associated with any snapshot).This attribute is alwaysnullif {@link #machineId} isnull.
Writethrough hard disks are always attached directly and cannot be
* involved when taking snapshots, so this attribute is meaningless and
* therefore alwaysnull.
*
*/
public UUID getSnapshotId() {
try {
String retVal = port.iHardDiskGetSnapshotId(_this);
return UUID.fromString(retVal);
} catch (com.sun.xml.ws.commons.virtualbox.InvalidObjectFaultMsg e) {
throw new WebServiceException(e);
} catch (com.sun.xml.ws.commons.virtualbox.RuntimeFaultMsg e) {
throw new WebServiceException(e);
}
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy