apache/cloudstack
1
0
Fork 0
mirror of https://github.com/apache/cloudstack.git synced 2025-10-26 08:42:29 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improvements and cleanup on the javadocs of QemuImg (#6917)

Browse Source 
* Cleanup in the javadocs of QemuImg

* Update QemuImg.java

* Apply suggestions from code review

Co-authored-by: Stephan Krug <stekrug@icloud.com>

Co-authored-by: cloudstack-lab-gabriel <gabriel.fernandes@scclouds.com.br>
Co-authored-by: Stephan Krug <stekrug@icloud.com>
This commit is contained in:
GaOrtiga 2022-12-06 17:59:03 -03:00 committed by GitHub
parent 7c61d8aeaf
commit 684f3f4c49
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 137 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

283
plugins/hypervisors/kvm/src/main/java/org/apache/cloudstack/utils/qemu/QemuImg.java
View File

@ -95,14 +95,14 @@ public class QemuImg {
public static PreallocationType getPreallocationType(final Storage.ProvisioningType provisioningType){ public static PreallocationType getPreallocationType(final Storage.ProvisioningType provisioningType){
switch (provisioningType){ switch (provisioningType){
case THIN: case THIN:
return PreallocationType.Off; return PreallocationType.Off;
case SPARSE: case SPARSE:
return PreallocationType.Metadata; return PreallocationType.Metadata;
case FAT: case FAT:
return PreallocationType.Full; return PreallocationType.Full;
default: default:
throw new NotImplementedException(String.format("type %s not defined as member-value of PreallocationType", provisioningType)); 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(); 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 { public QemuImg(final int timeout) throws LibvirtException, QemuImgException {
this(timeout, false, false); 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) { public void setTimeout(final int timeout) {
this.timeout = timeout; this.timeout = timeout;
} }
/** /**
* Create a QemuImg object * Creates a QemuImg object.
*
* *
* @param qemuImgPath * @param qemuImgPath
* A alternative path to the qemu-img binary * An alternative path to the qemu-img binary.
* @return void * @return void
*/ */
public QemuImg(final String qemuImgPath) throws LibvirtException { public QemuImg(final String qemuImgPath) throws LibvirtException {
@ -161,22 +173,17 @@ public class QemuImg {
_qemuImgPath = qemuImgPath; _qemuImgPath = qemuImgPath;
} }
/* These are all methods supported by the qemu-img tool */ /* These are all methods supported by the qemu-img tool. */
/* Perform a consistency check on the disk image */
public void check(final QemuImgFile file) {
}
/** /**
* 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 * @param file
* The file to create * The file to be created.
* @param backingFile * @param backingFile
* A backing file if used (for example with qcow2) * A backing file, if used (for example with qcow2).
* @param options * @param options
* Options for the create. Takes a Map<String, String> with key value * Options for the create. Takes a Map<String, String> with key value
* pairs which are passed on to qemu-img without validation. * 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 * @param file
* The file to create * The file to be created.
* @param backingFile * @param backingFile
* A backing file if used (for example with qcow2) * A backing file, if used (for example with qcow2).
* @param options * @param options
* Options for the create. Takes a Map<String, String> with key value * Options for the creation. Takes a Map<String, String> with key value
* pairs which are passed on to qemu-img without validation. * pairs which are passed on to qemu-img without validation.
* @param qemuObjects * @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 * @return void
*/ */
public void create(final QemuImgFile file, final QemuImgFile backingFile, final Map<String, String> options, final List<QemuObject> qemuObjects) throws QemuImgException { public void create(final QemuImgFile file, final QemuImgFile backingFile, final Map<String, String> options, final List<QemuObject> 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 * @param file
* The file to create * The file to be created.
* @return void * @return void
*/ */
public void create(final QemuImgFile file) throws QemuImgException { 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 * @param file
* The file to create * The file to be created.
* @param backingFile * @param backingFile
* A backing file if used (for example with qcow2) * A backing file, if used (for example with qcow2).
* @return void * @return void
*/ */
public void create(final QemuImgFile file, final QemuImgFile backingFile) throws QemuImgException { 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 * @param file
* The file to create * The file to be created.
* @param options * @param options
* Options for the create. Takes a Map<String, String> with key value * Options for the creation. Takes a Map<String, String> with key value
* pairs which are passed on to qemu-img without validation. * pairs which are passed on to qemu-img without validation.
* @return void * @return void
*/ */
@ -300,23 +307,21 @@ public class QemuImg {
} }
/** /**
* Convert a image from source to destination * Converts an image from source to destination.
*
* This method calls 'qemu-img convert' and takes five objects
* as an argument.
* *
* 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 * @param srcFile
* The source file * The source file.
* @param destFile * @param destFile
* The destination file * The destination file.
* @param options * @param options
* Options for the convert. Takes a Map<String, String> with key value * Options for the conversion. Takes a Map<String, String> with key value
* pairs which are passed on to qemu-img without validation. * pairs which are passed on to qemu-img without validation.
* @param snapshotName * @param snapshotName
* If it is provided, convertion uses it as parameter * If it is provided, conversion uses it as parameter.
* @param forceSourceFormat * @param forceSourceFormat
* If true, specifies the source format in the conversion cmd * If true, specifies the source format in the conversion command.
* @return void * @return void
*/ */
public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, public void convert(final QemuImgFile srcFile, final QemuImgFile destFile,
@ -325,25 +330,23 @@ public class QemuImg {
} }
/** /**
* Convert a image from source to destination * Converts an image from source to destination.
*
* This method calls 'qemu-img convert' and takes five objects
* as an argument.
* *
* 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 * @param srcFile
* The source file * The source file.
* @param destFile * @param destFile
* The destination file * The destination file.
* @param options * @param options
* Options for the convert. Takes a Map<String, String> with key value * Options for the conversion. Takes a Map<String, String> with key value
* pairs which are passed on to qemu-img without validation. * pairs which are passed on to qemu-img without validation.
* @param qemuObjects * @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 * @param snapshotName
* If it is provided, convertion uses it as parameter * If it is provided, conversion uses it as parameter.
* @param forceSourceFormat * @param forceSourceFormat
* If true, specifies the source format in the conversion cmd * If true, specifies the source format in the conversion command.
* @return void * @return void
*/ */
public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, public void convert(final QemuImgFile srcFile, final QemuImgFile destFile,
@ -353,27 +356,25 @@ public class QemuImg {
} }
/** /**
* Convert a image from source to destination * Converts an image from source to destination.
*
* This method calls 'qemu-img convert' and takes five objects
* as an argument.
* *
* 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 * @param srcFile
* The source file * The source file.
* @param destFile * @param destFile
* The destination file * The destination file.
* @param options * @param options
* Options for the convert. Takes a Map<String, String> with key value * Options for the conversion. Takes a Map<String, String> with key value
* pairs which are passed on to qemu-img without validation. * pairs which are passed on to qemu-img without validation.
* @param qemuObjects * @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 * @param srcImageOpts
* pass qemu --image-opts to convert * pass qemu --image-opts to convert.
* @param snapshotName * @param snapshotName
* If it is provided, convertion uses it as parameter * If it is provided, conversion uses it as parameter.
* @param forceSourceFormat * @param forceSourceFormat
* If true, specifies the source format in the conversion cmd * If true, specifies the source format in the conversion command.
* @return void * @return void
*/ */
public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, public void convert(final QemuImgFile srcFile, final QemuImgFile destFile,
@ -472,22 +473,20 @@ public class QemuImg {
script.add(snapshotName); script.add(snapshotName);
} }
/** /**
* Convert a image from source to destination * Converts an image from source to destination.
*
* This method calls 'qemu-img convert' and takes four objects
* as an argument.
* *
* 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 * @param srcFile
* The source file * The source file.
* @param destFile * @param destFile
* The destination file * The destination file.
* @param options * @param options
* Options for the convert. Takes a Map<String, String> with key value * Options for the conversion. Takes a Map<String, String> with key value
* pairs which are passed on to qemu-img without validation. * pairs which are passed on to qemu-img without validation.
* @param snapshotName * @param snapshotName
* If it is provided, convertion uses it as parameter * If it is provided, conversion uses it as parameter.
* @return void * @return void
*/ */
public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, public void convert(final QemuImgFile srcFile, final QemuImgFile destFile,
@ -495,36 +494,32 @@ public class QemuImg {
this.convert(srcFile, destFile, options, snapshotName, false); this.convert(srcFile, destFile, options, snapshotName, false);
} }
/** /**
* Convert a image from source to destination * Converts an image from source to destination.
* *
* This method calls 'qemu-img convert' and takes two objects * 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.
* as an argument. *
* * @param srcFile
* * The source file.
* @param srcFile * @param destFile
* The source file * The destination file.
* @param destFile * @return void
* The destination file */
* @return void
*/
public void convert(final QemuImgFile srcFile, final QemuImgFile destFile) throws QemuImgException, LibvirtException { public void convert(final QemuImgFile srcFile, final QemuImgFile destFile) throws QemuImgException, LibvirtException {
this.convert(srcFile, destFile, null, null); this.convert(srcFile, destFile, null, null);
} }
/** /**
* Convert a image from source to destination * Converts an image from source to destination.
*
* This method calls 'qemu-img convert' and takes three objects
* as an argument.
* *
* 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 * @param srcFile
* The source file * The source file.
* @param destFile * @param destFile
* The destination file * The destination file.
* @param forceSourceFormat * @param forceSourceFormat
* If true, specifies the source format in the conversion cmd * If true, specifies the source format in the conversion command.
* @return void * @return void
*/ */
public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, final boolean forceSourceFormat) throws QemuImgException, LibvirtException { 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 * Converts an image from source to destination.
*
* This method calls 'qemu-img convert' and takes three objects
* as an argument.
* *
* 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 * @param srcFile
* The source file * The source file.
* @param destFile * @param destFile
* The destination file * The destination file.
* @param snapshotName * @param snapshotName
* The snapshot name * The snapshot name.
* @return void * @return void
*/ */
public void convert(final QemuImgFile srcFile, final QemuImgFile destFile, String snapshotName) throws QemuImgException, LibvirtException { 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. * 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 (_).
* This method calls 'qemu-img commit' and takes one object as * - Sizes (virtual_size and disk_size) are returned in bytes.
* an argument * - Paths (image and backing_file) are the absolute path to the file.
* *
* @param file * @param file
* The file of which changes have to be committed * A QemuImgFile object containing the file to get the information from.
* @return void * @return A HashMap with string key-value information as returned by 'qemu-img info'.
*/
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'
*/ */
public Map<String, String> info(final QemuImgFile file) throws QemuImgException { public Map<String, String> info(final QemuImgFile file) throws QemuImgException {
final Script s = new Script(_qemuImgPath); 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 { public void rebase(final QemuImgFile file, final QemuImgFile backingFile, final String backingFileFormat, final boolean secure) throws QemuImgException {
if (backingFile == null) { if (backingFile == null) {
throw new QemuImgException("No backing file was passed"); 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'. * This method is a facade for 'qemu-img resize'.
* A negative size value will get prefixed with - and a positive with +
* *
* 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 * @param file
* The file to resize * The file to be resized.
* @param size * @param size
* The new size * The new size.
* @param delta * @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 { public void resize(final QemuImgFile file, final long size, final boolean delta) throws QemuImgException {
String newSize = null; 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 * @param imageOptions
* Qemu style image options for the image to resize * Qemu style image options to be used in the resizing process.
* @param qemuObjects * @param qemuObjects
* Qemu style options (e.g. for passing secrets) * Qemu style options (e.g. for passing secrets).
* @param size * @param size
* The absolute final size of the image
*/ */
public void resize(final QemuImageOptions imageOptions, final List<QemuObject> qemuObjects, final long size) throws QemuImgException { public void resize(final QemuImageOptions imageOptions, final List<QemuObject> qemuObjects, final long size) throws QemuImgException {
final Script s = new Script(_qemuImgPath); 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'. * 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 * 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 * @param file
* The file to resize * The file to be resized.
* @param size * @param size
* The new size * The new size.
*/ */
public void resize(final QemuImgFile file, final long size) throws QemuImgException { public void resize(final QemuImgFile file, final long size) throws QemuImgException {
this.resize(file, size, false); this.resize(file, size, false);