diff --git a/plugins/hypervisors/kvm/src/main/java/org/apache/cloudstack/utils/qemu/QemuImg.java b/plugins/hypervisors/kvm/src/main/java/org/apache/cloudstack/utils/qemu/QemuImg.java index 43dd0c80292..1cd63b9b566 100644 --- a/plugins/hypervisors/kvm/src/main/java/org/apache/cloudstack/utils/qemu/QemuImg.java +++ b/plugins/hypervisors/kvm/src/main/java/org/apache/cloudstack/utils/qemu/QemuImg.java @@ -95,14 +95,14 @@ public class QemuImg { public static PreallocationType getPreallocationType(final Storage.ProvisioningType provisioningType){ switch (provisioningType){ - case THIN: - return PreallocationType.Off; - case SPARSE: - return PreallocationType.Metadata; - case FAT: - return PreallocationType.Full; - default: - throw new NotImplementedException(String.format("type %s not defined as member-value of PreallocationType", provisioningType)); + case THIN: + return PreallocationType.Off; + case SPARSE: + return PreallocationType.Metadata; + case FAT: + return PreallocationType.Full; + default: + throw new NotImplementedException(String.format("type %s not defined as member-value of PreallocationType", provisioningType)); } } } @@ -140,20 +140,32 @@ public class QemuImg { this.version = LibvirtConnection.getConnection().getVersion(); } + /** + * Creates a QemuImg object. + * + * @param timeout + * The timeout of scripts executed by this QemuImg object. + */ public QemuImg(final int timeout) throws LibvirtException, QemuImgException { this(timeout, false, false); } + /** + * Sets the timeout of the scripts executed by this QemuImg object. + * + * @param timeout + * The timeout of the object. + * @return void + */ public void setTimeout(final int timeout) { this.timeout = timeout; } /** - * Create a QemuImg object - * + * Creates a QemuImg object. * * @param qemuImgPath - * A alternative path to the qemu-img binary + * An alternative path to the qemu-img binary. * @return void */ public QemuImg(final String qemuImgPath) throws LibvirtException { @@ -161,22 +173,17 @@ public class QemuImg { _qemuImgPath = qemuImgPath; } - /* These are all methods supported by the qemu-img tool */ - - /* Perform a consistency check on the disk image */ - public void check(final QemuImgFile file) { - - } + /* These are all methods supported by the qemu-img tool. */ /** - * Create a new image + * Creates a new image. * - * This method calls 'qemu-img create' + * This method is a facade for 'qemu-img create'. * * @param file - * The file to create + * The file to be created. * @param backingFile - * A backing file if used (for example with qcow2) + * A backing file, if used (for example with qcow2). * @param options * Options for the create. Takes a Map with key value * pairs which are passed on to qemu-img without validation. @@ -187,19 +194,19 @@ public class QemuImg { } /** - * Create a new image + * Creates a new image. * - * This method calls 'qemu-img create' + * This method is a facade for 'qemu-img create'. * * @param file - * The file to create + * The file to be created. * @param backingFile - * A backing file if used (for example with qcow2) + * A backing file, if used (for example with qcow2). * @param options - * Options for the create. Takes a Map with key value + * Options for the creation. Takes a Map with key value * pairs which are passed on to qemu-img without validation. * @param qemuObjects - * Pass list of qemu Object to create - see objects in qemu man page + * Pass list of qemu Object to create - see objects in qemu man page. * @return void */ public void create(final QemuImgFile file, final QemuImgFile backingFile, final Map options, final List qemuObjects) throws QemuImgException { @@ -256,12 +263,12 @@ public class QemuImg { } /** - * Create a new image + * Creates a new image. * - * This method calls 'qemu-img create' + * This method is a facade for {@link QemuImg#create(QemuImgFile, QemuImgFile, Map)}. * * @param file - * The file to create + * The file to be created. * @return void */ public void create(final QemuImgFile file) throws QemuImgException { @@ -269,14 +276,14 @@ public class QemuImg { } /** - * Create a new image + * Creates a new image. * - * This method calls 'qemu-img create' + * This method is a facade for {@link QemuImg#create(QemuImgFile, QemuImgFile, Map)}. * * @param file - * The file to create + * The file to be created. * @param backingFile - * A backing file if used (for example with qcow2) + * A backing file, if used (for example with qcow2). * @return void */ public void create(final QemuImgFile file, final QemuImgFile backingFile) throws QemuImgException { @@ -284,14 +291,14 @@ public class QemuImg { } /** - * Create a new image + * Creates a new image. * - * This method calls 'qemu-img create' + * This method is a facade for {@link QemuImg#create(QemuImgFile, QemuImgFile, Map)}. * * @param file - * The file to create + * The file to be created. * @param options - * Options for the create. Takes a Map with key value + * Options for the creation. Takes a Map with key value * pairs which are passed on to qemu-img without validation. * @return void */ @@ -300,23 +307,21 @@ public class QemuImg { } /** - * Convert a image from source to destination - * - * This method calls 'qemu-img convert' and takes five objects - * as an argument. + * Converts an image from source to destination. * + * This method is a facade for 'qemu-img convert' and converts a disk image or snapshot into a disk image with the specified filename and format. * * @param srcFile - * The source file + * The source file. * @param destFile - * The destination file + * The destination file. * @param options - * Options for the convert. Takes a Map with key value + * Options for the conversion. Takes a Map with key value * pairs which are passed on to qemu-img without validation. * @param snapshotName - * If it is provided, convertion uses it as parameter + * If it is provided, conversion uses it as parameter. * @param forceSourceFormat - * If true, specifies the source format in the conversion cmd + * If true, specifies the source format in the conversion command. * @return void */ public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, @@ -325,25 +330,23 @@ public class QemuImg { } /** - * Convert a image from source to destination - * - * This method calls 'qemu-img convert' and takes five objects - * as an argument. + * Converts an image from source to destination. * + * This method is a facade for 'qemu-img convert' and converts a disk image or snapshot into a disk image with the specified filename and format. * * @param srcFile - * The source file + * The source file. * @param destFile - * The destination file + * The destination file. * @param options - * Options for the convert. Takes a Map with key value + * Options for the conversion. Takes a Map with key value * pairs which are passed on to qemu-img without validation. * @param qemuObjects - * Pass qemu Objects to create - see objects in qemu man page + * Pass qemu Objects to create - see objects in the qemu main page. * @param snapshotName - * If it is provided, convertion uses it as parameter + * If it is provided, conversion uses it as parameter. * @param forceSourceFormat - * If true, specifies the source format in the conversion cmd + * If true, specifies the source format in the conversion command. * @return void */ public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, @@ -353,27 +356,25 @@ public class QemuImg { } /** - * Convert a image from source to destination - * - * This method calls 'qemu-img convert' and takes five objects - * as an argument. + * Converts an image from source to destination. * + * This method is a facade for 'qemu-img convert' and converts a disk image or snapshot into a disk image with the specified filename and format. * * @param srcFile - * The source file + * The source file. * @param destFile - * The destination file + * The destination file. * @param options - * Options for the convert. Takes a Map with key value + * Options for the conversion. Takes a Map with key value * pairs which are passed on to qemu-img without validation. * @param qemuObjects - * Pass qemu Objects to convert - see objects in qemu man page + * Pass qemu Objects to create - see objects in the qemu main page. * @param srcImageOpts - * pass qemu --image-opts to convert + * pass qemu --image-opts to convert. * @param snapshotName - * If it is provided, convertion uses it as parameter + * If it is provided, conversion uses it as parameter. * @param forceSourceFormat - * If true, specifies the source format in the conversion cmd + * If true, specifies the source format in the conversion command. * @return void */ public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, @@ -472,22 +473,20 @@ public class QemuImg { script.add(snapshotName); } - /** - * Convert a image from source to destination - * - * This method calls 'qemu-img convert' and takes four objects - * as an argument. + /** + * Converts an image from source to destination. * + * This method is a facade for 'qemu-img convert' and converts a disk image or snapshot into a disk image with the specified filename and format. * * @param srcFile - * The source file + * The source file. * @param destFile - * The destination file + * The destination file. * @param options - * Options for the convert. Takes a Map with key value + * Options for the conversion. Takes a Map with key value * pairs which are passed on to qemu-img without validation. * @param snapshotName - * If it is provided, convertion uses it as parameter + * If it is provided, conversion uses it as parameter. * @return void */ public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, @@ -495,36 +494,32 @@ public class QemuImg { this.convert(srcFile, destFile, options, snapshotName, false); } - /** - * Convert a image from source to destination - * - * This method calls 'qemu-img convert' and takes two objects - * as an argument. - * - * - * @param srcFile - * The source file - * @param destFile - * The destination file - * @return void - */ + /** + * Converts an image from source to destination. + * + * This method is a facade for 'qemu-img convert' and converts a disk image or snapshot into a disk image with the specified filename and format. + * + * @param srcFile + * The source file. + * @param destFile + * The destination file. + * @return void + */ public void convert(final QemuImgFile srcFile, final QemuImgFile destFile) throws QemuImgException, LibvirtException { this.convert(srcFile, destFile, null, null); } /** - * Convert a image from source to destination - * - * This method calls 'qemu-img convert' and takes three objects - * as an argument. + * Converts an image from source to destination. * + * This method is a facade for 'qemu-img convert' and converts a disk image or snapshot into a disk image with the specified filename and format. * * @param srcFile - * The source file + * The source file. * @param destFile - * The destination file + * The destination file. * @param forceSourceFormat - * If true, specifies the source format in the conversion cmd + * If true, specifies the source format in the conversion command. * @return void */ public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, final boolean forceSourceFormat) throws QemuImgException, LibvirtException { @@ -532,18 +527,16 @@ public class QemuImg { } /** - * Convert a image from source to destination - * - * This method calls 'qemu-img convert' and takes three objects - * as an argument. + * Converts an image from source to destination. * + * This method is a facade for 'qemu-img convert' and converts a disk image or snapshot into a disk image with the specified filename and format. * * @param srcFile - * The source file + * The source file. * @param destFile - * The destination file + * The destination file. * @param snapshotName - * The snapshot name + * The snapshot name. * @return void */ public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, String snapshotName) throws QemuImgException, LibvirtException { @@ -551,32 +544,14 @@ public class QemuImg { } /** - * Commit the changes recorded in the file in its base image. - * - * This method calls 'qemu-img commit' and takes one object as - * an argument + * Executes 'qemu-img info' for the given file. Qemu-img returns a human-readable output and this method parses the result to machine-readable data. + * - Spaces in keys are replaced by underscores (_). + * - Sizes (virtual_size and disk_size) are returned in bytes. + * - Paths (image and backing_file) are the absolute path to the file. * * @param file - * The file of which changes have to be committed - * @return void - */ - public void commit(final QemuImgFile file) throws QemuImgException { - - } - - /** - * Execute qemu-img info for the given file - * - * Qemu-img returns human readable output, but this method does it's best - * to turn that into machine readeable data. - * - * Spaces in keys are replaced by underscores (_). - * Sizes (virtual_size and disk_size) are returned in bytes - * Paths (image and backing_file) are the absolute path to the file - * - * @param file - * A QemuImgFile object containing the file to get the information from - * @return A HashMap with String key-value information as returned by 'qemu-img info' + * A QemuImgFile object containing the file to get the information from. + * @return A HashMap with string key-value information as returned by 'qemu-img info'. */ public Map info(final QemuImgFile file) throws QemuImgException { final Script s = new Script(_qemuImgPath); @@ -677,7 +652,22 @@ public class QemuImg { } } - /* Changes the backing file of an image */ + /** + * Rebases the backing file of the image. + * + * This method is a facade for 'qemu-img rebase'. + * + * @param file + * The file to be rebased. + * @param backingFile + * The new backing file. + * @param backingFileFormat + * The format of the new backing file. + * @param secure + * Indicates whether 'safe mode' is active. When active, the operation will be more expensive and will only be possible if the old + * backing file still exists. However, if safe mode is off, the changes in the file name and format will be made without validation, + * so, if the backing file is wrongly specified the contents of the image may be corrupted. + */ public void rebase(final QemuImgFile file, final QemuImgFile backingFile, final String backingFileFormat, final boolean secure) throws QemuImgException { if (backingFile == null) { throw new QemuImgException("No backing file was passed"); @@ -704,19 +694,18 @@ public class QemuImg { } /** - * Resize an image + * Resizes an image. * - * This method simple calls 'qemu-img resize'. - * A negative size value will get prefixed with - and a positive with + + * This method is a facade for 'qemu-img resize'. * - * Sizes are in bytes and will be passed on that way + * A negative size value will get prefixed with '-' and a positive with '+'. Sizes are in bytes and will be passed on that way. * * @param file - * The file to resize + * The file to be resized. * @param size - * The new size + * The new size. * @param delta - * Flag if the new size is a delta + * Flag to inform if the new size is a delta. */ public void resize(final QemuImgFile file, final long size, final boolean delta) throws QemuImgException { String newSize = null; @@ -746,14 +735,17 @@ public class QemuImg { } /** - * Resize an image, new style flags/options + * Resizes an image. + * + * This method is a facade for {@link QemuImg#resize(QemuImgFile, long, boolean)}. + * + * A negative size value will get prefixed with - and a positive with +. Sizes are in bytes and will be passed on that way. * * @param imageOptions - * Qemu style image options for the image to resize + * Qemu style image options to be used in the resizing process. * @param qemuObjects - * Qemu style options (e.g. for passing secrets) + * Qemu style options (e.g. for passing secrets). * @param size - * The absolute final size of the image */ public void resize(final QemuImageOptions imageOptions, final List qemuObjects, final long size) throws QemuImgException { final Script s = new Script(_qemuImgPath); @@ -773,17 +765,16 @@ public class QemuImg { } /** - * Resize an image + * Resizes an image. * - * This method simple calls 'qemu-img resize'. - * A negative size value will get prefixed with - and a positive with + + * This method is a facade for {@link QemuImg#resize(QemuImgFile, long, boolean)}. * - * Sizes are in bytes and will be passed on that way + * A negative size value will get prefixed with - and a positive with +. Sizes are in bytes and will be passed on that way. * * @param file - * The file to resize + * The file to be resized. * @param size - * The new size + * The new size. */ public void resize(final QemuImgFile file, final long size) throws QemuImgException { this.resize(file, size, false);