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

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

@ -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<String, String> 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<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.
* @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<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
* 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<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.
* @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<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.
* @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<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.
* @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<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.
* @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,
@ -473,21 +474,19 @@ public class QemuImg {
}
/**
* 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<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.
* @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,
@ -496,16 +495,14 @@ public class QemuImg {
}
/**
* Convert a image from source to destination
*
* This method calls 'qemu-img convert' and takes two 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.
* @return void
*/
public void convert(final QemuImgFile srcFile, final QemuImgFile destFile) throws QemuImgException, LibvirtException {
@ -513,18 +510,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 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<String, String> 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<QemuObject> 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);