[ovirt-devel] Engine - Changes to various issues around commands and queries construction and internal execution - please read

[Allon Mureinik]

Can we have a wiki page to consolidate all this info?

In a couple of months when someone will want to write a new command, this info may be hard to come by.


Thanks!

----- Original Message -----
> From: "Yair Zaslavsky" <yzaslavs at redhat.com>
> To: devel at ovirt.org
> Sent: Thursday, June 26, 2014 1:09:28 PM
> Subject: [ovirt-devel] Engine - Changes to various issues around commands and queries construction and internal
> execution - please read
> 
> Hi all,
> Thanks to the help of Alon, oved, Tal, Moti, Arik and others, the following
> changes were introduced:
> 
> 1. Internal commands invocation -
> 
> When invoking an internal command from a command, please use the following :
> 
> Instead of Backend.getInstance().runInternalAction...
> 
> Use
> 
> runInternalAction - a new method that was introdced at CommandBase.
> 
> This method has two variants - one that accepts command context, and the
> other that does not have a command contet -
> 
> runInternalAction(VdcActionType,VdcActionParametersBase,CommandContext)
> 
> and
> 
> runInternalAction(VdcActionType,VdcActionParametersBase)
> 
> If CommandContext is not passed the context at the calling command will be
> cloned and set at the child command.
> 
> If a Command context is pased - it should be the responsibility of the caller
> to clone, however, this will give the caller some degree of freedom to
> determine whether various
> parts of the context will be cloned, or not.
> 
> Examples:
> 
> runInternalAction(VdcActionType.AddPermission, permissionParams)  has the
> same effect as :  runInternlAction(VdcActionType.AddPermissiosn,
> permissionParams, getContext().clone())
> 
> 
> runInternlAction(VdcActionType.AddPermissiosn, permissionParams,
> getContext().clone().withoutCompensationContext()) - will cause the
> compensation context to be reset, and let the child command determine the
> value of compensation context (at handleTransactivity method).
> 
> The complete list of "context alteration methods" are -
> 
> withCompensationContext(CompensationContext)  , withoutCompensationContext()
> withLock(EngineLock), withoutLock()
> withExecutionContext(ExecutionContext), withoutExecutionContext() -  bare in
> mind that all these follow the chaining method "design pattern" [1] (I would
> like to thank Moti for the naming suggestions)
> 
> 
> two methods for running InternalAction with context for tasks were created:
> 
> runInternalActionWithTasksContext(VdcActionType, VdcActionParametersBase)
> 
> runInternalActionWithTasksContext(VdcActionType, VdcActionParametersBase,
> EngineLock)
> 
> 
> These methods use  ExecutionHandler.createDefaultContextForTasks to create
> the relevant command context to be passed to the child command.
> 
> 
> runInternalMultipleActions was introduced to command base in a similar
> manner, with 3 versions:
> 
> runInternalMultipleActions(VdcActionType, ArrayList<VdcActionParametersBase>)
> 
> runInternalMultipleActions(VdcActionType, ArrayList<VdcActionParametersBase>,
> ExecutionContext)
> 
> runInternalMultipleActions(VdcActionType, ArrayList<VdcActionParametersBase>,
> CommandContext)
> 
> 
> 2. Queries invocation -
> 
> 
> runInternalQuery(VdcQueryType, VdcQueryParametersBase) was introduced to
> command base.
> 
> Basically it takes the engine context from the current command context, and
> runs the internal query with it.
> 
> EngineContext is the context which should hold all the common attributes to
> our flows at engine - currently it holds the engineSessionId, working
> towards moving correlationId to it as well.
> 
> 
> 
> 3. Commands & Queries coding
> 
> Each internal query should have a ctor that takes the parameters, and also
> the engine context .
> As some of the queries are both internal and non internal you may have two
> ctors - one with parameters only, one with parameters and EngineContext
> 
> for example
> 
> public class GetUnregisteredDiskQuery<P extends
> GetUnregisteredDiskQueryParameters> extends QueriesCommandBase<P> {
> 
>     public GetUnregisteredDiskQuery(P parameters) {
>         this(parameters, null);
>     }
> 
>     public GetUnregisteredDiskQuery(P parameters, EngineContext context) {
>         super(parameters, context);
>     }
> 
> Notice that the ctor without the context calls the one with the context.
> 
> Same happens at Commands:
> 
> 
>    public RemovePermissionCommand(T parameters) {
>         this(parameters, null);
>     }
> 
>     public RemovePermissionCommand(T parameters, CommandContext
>     commandContext) {
>         super(parameters, commandContext);
>     }
> 
> 
> 
> 4. runVdsCommand was introduced to CommandBase as well
> 
> runVdsCommand(VDSCommandType, VdsCommandParameters) - currently this just
> runs the vds command on vds broker, working on propagating the engine
> context via vds broker as well.
> 
> 
> Please use the above in your code. If you see any issues , or places where
> its problematic to use, feel free to contact me.
> 
> 
> [1]
> http://en.wikipedia.org/wiki/Method_chaining
> 
> 
> 
> 
> 
> 
> 
> _______________________________________________
> Devel mailing list
> Devel at ovirt.org
> http://lists.ovirt.org/mailman/listinfo/devel
>