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@redhat.com> To: devel@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@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel