001/*
002 * Copyright 2025 devteam@scivicslab.com
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing,
011 * software distributed under the License is distributed on an
012 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
013 * either express or implied.  See the License for the
014 * specific language governing permissions and limitations
015 * under the License.
016 */
017
018package com.scivicslab.actoriac.mixin;
019
020import java.io.IOException;
021
022import com.scivicslab.actoriac.Node;
023
024/**
025 * Abstraction for command execution that can be implemented for different contexts.
026 *
027 * <p>This interface allows the same action implementation to work in different
028 * execution environments:</p>
029 * <ul>
030 *   <li>{@link SshCommandExecutor} - Executes commands on remote nodes via SSH</li>
031 *   <li>{@link LocalCommandExecutor} - Executes commands on the local machine</li>
032 * </ul>
033 *
034 * @author devteam@scivicslab.com
035 * @since 2.15.0
036 */
037public interface CommandExecutor {
038
039    /**
040     * Executes a command and returns the result.
041     *
042     * @param command the command to execute
043     * @return the result of command execution
044     * @throws IOException if command execution fails
045     */
046    Node.CommandResult execute(String command) throws IOException;
047
048    /**
049     * Executes a command and returns the result with output callback.
050     *
051     * @param command the command to execute
052     * @param callback the callback for real-time output (may be null)
053     * @return the result of command execution
054     * @throws IOException if command execution fails
055     */
056    Node.CommandResult execute(String command, Node.OutputCallback callback) throws IOException;
057
058    /**
059     * Executes a command with sudo privileges.
060     *
061     * @param command the command to execute with sudo
062     * @return the result of command execution
063     * @throws IOException if command execution fails or SUDO_PASSWORD is not set
064     */
065    Node.CommandResult executeSudo(String command) throws IOException;
066
067    /**
068     * Executes a command with sudo privileges and output callback.
069     *
070     * @param command the command to execute with sudo
071     * @param callback the callback for real-time output (may be null)
072     * @return the result of command execution
073     * @throws IOException if command execution fails or SUDO_PASSWORD is not set
074     */
075    Node.CommandResult executeSudo(String command, Node.OutputCallback callback) throws IOException;
076
077    /**
078     * Gets a short identifier for this executor (e.g., hostname).
079     *
080     * @return the identifier string
081     */
082    String getIdentifier();
083}