<?php

namespace AIPT\Api\AutomationJobs\Interfaces;

use AIPT\Api\AutomationJobs\Models\AutomationJob;

/**
 * Job Executor Interface
 * 
 * Defines contract for job execution implementations
 * Following Interface Segregation and Dependency Inversion principles
 * 
 * @since 2.3.0
 */
interface JobExecutorInterface {
    
    /**
     * Execute a job
     * 
     * @param int $job_id Job ID to execute
     * @return bool Success status
     * @throws \Exception On execution failure
     */
    public function executeJob($job_id);
    
    /**
     * Pause a running job
     * 
     * @param int $job_id Job ID to pause
     * @return bool Success status
     * @throws \Exception On pause failure
     */
    public function pauseJob($job_id);
    
    /**
     * Resume a paused job
     * 
     * @param int $job_id Job ID to resume
     * @return bool Success status
     * @throws \Exception On resume failure
     */
    public function resumeJob($job_id);
    
    /**
     * Cancel a job
     * 
     * @param int $job_id Job ID to cancel
     * @return bool Success status
     * @throws \Exception On cancel failure
     */
    public function cancelJob($job_id);
    
    /**
     * Get job execution progress
     * 
     * @param int $job_id Job ID
     * @return array Progress information
     */
    public function getJobProgress($job_id);
    
    /**
     * Check if executor can handle specific tool type
     * 
     * @param string $tool_type Tool type to check
     * @return bool Whether tool type is supported
     */
    public function supportsToolType($tool_type);
    
    /**
     * Validate job before execution
     * 
     * @param AutomationJob $job Job to validate
     * @return array Validation errors (empty if valid)
     */
    public function validateJobForExecution(AutomationJob $job);
}
