Command set

How to create and use a CommandSet component.

Key takeaways

CommandSet Component used to group a set of commands.
Command Component used to call a method or a function.
Event Component used to send a notification to one or more listeners.

Introduction

The CommandSet component allows us to group a set of commands and events, which can be called and executed at a later stage.

In this tutorial, you will learn how to create a CommandSet component, add commands and events to it, and perform some operations, such as executing or finding a specific command from a command set.

In order to do this, we divide the work into two sections: the first explains how to operate with commands and the second how to work with events in a CommandSet.

Pre-requisites

In order to use the CommandSet component, we need to import it first. The following command shows how to do this:

import { CommandSet } from "pip-services4-rpc-node";

Defining a CommandSet

In order to create a CommandSet component, we need to either create an instance of this class: 

let myCommandSetA = new CommandSet();

or define a subclass of it:

export class MyCommandSet extends CommandSet {
    public constructor() {
        super();
    }
}

Using a CommandSet with Commands

In this section, we will learn how to add commands to a command set, and how to retrieve these commands and execute them

Adding a command

We can add a command to the set with the add_command() method. The following example shows how to add a command that, once executed, prints ‘command 1’.

import { Parameters } from "pip-services4-components-node";
import { CommandSet, ICommand, Command } from "pip-services4-rpc-node";


export class MyCommandSet extends CommandSet {
    public constructor() {
        super();
        this.addCommand(this.command1());
    }

    private command1(): ICommand {
        return new Command("command1",
                null,
                (correlationId: string, args: Parameters) => {
                console.log("command 1");
                return null;
            }
        );
    } 
}

Adding several commands at once

We can also add several commands at once via the addCommands() method, which accepts as input a list with the names of the methods to be added. In the example below, we add two commands to the set.

export class MyCommandSet extends CommandSet {
    public constructor() {
        super();
        this.addCommands([this.command2(), this.command3()]);
    }

    private command2(): ICommand {
        return new Command("command2",
            null,
            (correlationId: string, args: Parameters) => {
                console.log("command 2");
                return null;
            }
        );
    }

    private command3(): ICommand {
        return new Command("command3",
            null,
            (correlationId: string, args: Parameters) => {
                console.log("command 2");
                return null;
            }
        );
    }
}

Adding a command set

Alternatively, we can add a CommandSet containing one or more commands. This can be done with the addCommandSet() method. The following example shows how to do this:


export class MyCommandSetB extends CommandSet {
    public constructor() {
        super();
        this.addCommand(this.command1B());
    }

    private command1B(): ICommand {
        return new Command(
            "command1B",
            null, 
            async (correlationId: string, args: Parameters) => {
                console.log("command 1B");
            }
        );
    }
}
    
export class MyCommandSet extends CommandSet {
    private _commandSet = new MyCommandSetB();

    public constructor() {
        super();
        this.addCommandSet(this._commandSet);
    }
}

Executing a command

Once our command set is ready, we can create an instance of it and execute any of the commands it contains with the execute() method. This method accepts as inputs the context, the name of the command to be executed, and the parameters that this command requires.

await mySet.execute(ctx, "command1", null); // Returns command 1

Finding a command

We can find a command via the findCommand() method, which accepts the name of the command as input. The next example shows how to use it.

let result = mySet.findCommand("command1");
    
console.log(result.getName());

Getting all commands

We can get all the commands available in our command set via the getCommands() method, which returns the results in the form of a list. In the following example, we obtain a list with the commands and then we print their names.

let result2 = mySet.getCommands();

for (let command of result2) {
    console.log(command.getName());
}

// Returns    
// command1
// command2
// command3
// command1B

Using a CommandSet with Events

We can also use our command set to store events.

Adding an event

Adding an event is very similar to adding a command and can be done with the addEvent() method. This method accepts the event to be added as input.

export class MyEventSet extends CommandSet {
    public constructor() {
        super();
        this.addEvent(this.event1());
    }

    private event1(): Event {
        return new Event("event1");
    }
}

Adding several events at once

We can also add several commands together with the addEvents() method, which accepts as input a list containing the events to be added. This example explains how to do this:

export class MyEventSet extends CommandSet {
    public constructor() {
        super();
        this.addEvents([this.event2(), this.event3()]);
    }

    private event2(): IEvent {
        return new Event("event2");
    }

    private event3(): IEvent {
        return new Event("event3");
    }
}

Adding a listener

Additionally, we can add a listener to our command set by using the addListener() method. This method takes the listener as input and adds a listener that is connected to all the events in the command set. In the following example, we add a listener that is connected to event2 and event3.

import { Parameters, Context } from "pip-services4-components-node";
import { CommandSet, IEventListener, IEvent } from "pip-services4-rpc-node";

export class MyListener implements IEventListener {
    onEvent(ctx: Context, event: IEvent, args: Parameters): void {
        console.log("Fired event name " + event.getName());
    }
} 

export class MyEventSet extends CommandSet {
    public constructor() {
        super();
        
        this.addEvents([this.event2(), this.event3()]);
        this.addListener(this.listener1());
    }

    private event2(): IEvent {
        return new Event("event2");
    }

    private event3(): IEvent {
        return new Event("event3");
    }

    private listener1(): IEventListener {
        return new MyListener();
    }
}

Finding an event

We can use the findEvent() method to search for a specific event. This method asks for the event name as input, and if found, returns the event object.


let result4 = myEvents.findEvent("event1");

console.log(result4.getName());  // Returns 'event1'

Getting all the events

Finally, similar to the previous method, the getEvents() method allows us to obtain all the events available in our command set in the form of a list. In the example below, we obtain a list with the events, and then, we print their names.

let myEvents = new MyEventSet();

let result3 = myEvents.getEvents();

for (let event of result3)
{
    console.log(event.getName());
}

// Returns:    
// event1
// event2
// event3

Examples

In this section, we have two examples that show how to work with command sets. The first focus on commands and the second on events.

Example 1

import { Parameters } from "pip-services4-components-node";
import { CommandSet, Command, ICommand } from "pip-services4-rpc-node";

export async function main() { 
    var mySet = new MyCommandSet();

    await mySet.execute(null, "command1", null);
    await mySet.execute(null, "command2", null);
    await mySet.execute(null, "command3", null);
    await mySet.execute(null, "command1B", null);
}


export class MyCommandSetB extends CommandSet {
    public constructor() {
        super();

        this.addCommand(this.command1B());
    }

    private command1B(): ICommand {
        return new Command(
            "command1B",
            null, 
            async (correlationId: string, args: Parameters) => {
                console.log("command 1B");
            }
        );
    }
}

export class MyCommandSet extends CommandSet {
    private _commandSet = new MyCommandSetB();

    public constructor() {
        super();
        this.addCommandSet(this._commandSet);
        this.addCommand(this.command1());
        this.addCommands([this.command2(), this.command3()]);
    }

    private command1(): ICommand {
        return new Command("command1",
                null,
                (correlationId: string, args: Parameters) => {
                console.log("command 1");
                return null;
            }
        );
    } 

    private command2(): ICommand {
        return new Command("command2",
            null,
            (correlationId: string, args: Parameters) => {
                console.log("command 2");
                return null;
            }
        );
    }

    private command3(): ICommand {
        return new Command("command3",
            null,
            (correlationId: string, args: Parameters) => {
                console.log("command 2");
                return null;
            }
        );
    }
}

Example 2


import { Parameters, Context } from "pip-services4-components-node";
import { CommandSet, IEventListener, IEvent } from "pip-services4-rpc-node";

// Step 1 - Create the command set with events
export class MyEventSet extends CommandSet {
    public constructor() {
        super();
        this.addEvent(this.event1());
        this.addEvents([this.event2(), this.event3()]);
        this.addListener(this.listener1());
    }

    private event1(): IEvent {
        return new Event("event1");
    }

    private event2(): IEvent {
        return new Event("event2");
    }

    private event3(): IEvent {
        return new Event("event3");
    }

    private listener1(): IEventListener {
        return new MyListener();
    }
}

// Step 2 - Create a listener
export class MyListener implements IEventListener {
    onEvent(ctx: Context, event: IEvent, args: Parameters): void {
        console.log("Fired event name " + event.getName());
    }
} 


// Step 3  - Create an instance of the command set
let myEvents = new MyEventSet();

// Step 4 - Obtain events
let event1 = myEvents.findEvent("event1");
let events = myEvents.getEvents();  // Returns a list with event1, event2 and event3

// Step 5 - Select event1 (first element in the list)
let event2 = events[1];  // Returns event1

// Step 6 - Notify the listener of an event occurrence
event1.notify(ctx, null);
event2.notify(ctx, null);
myEvents.notify(ctx, "event3", null);

Wrapping up

In this tutorial, we have seen how to create a CommandSet that contains commands and events. We have also seen how to extract and use those commands and events and perform some operations with them.