為配合主幹穩定開發模型，並確保生態系統的平台穩定性，我們將於 2026 年起，在第 2 季和第 4 季將原始碼發布至 AOSP。如要建構及貢獻 AOSP，建議使用 android-latest-release，而非 aosp-main。android-latest-release 資訊清單分支版本一律會參照推送至 AOSP 的最新版本。詳情請參閱「Android 開放原始碼計畫變更」一文。

CommandScheduler

public class CommandScheduler
extends Object implements ICommandScheduler

java.lang.Object
↳	com.android.tradefed.command.CommandScheduler

已知的直接子類別

ClusterCommandScheduler

ClusterCommandScheduler ICommandScheduler，支援 TFC (Tradefed Cluster)。

排程器，可在所有可用裝置上執行 TradeFederation 指令。

會嘗試根據指令的總執行時間，優先執行指令。舉例來說，系統會優先執行不常執行或執行速度快的指令，而非執行時間較長的指令。

在背景無限期執行，直到關機為止。

摘要

公用建構函式
`CommandScheduler()` 建立 `CommandScheduler`。

公用方法
`Pair<Boolean, Integer>`	`addCommand(String[] args)` Adds a command to the scheduler.
`void`	`addCommandFile(String cmdFilePath, extraArgs)` Adds all commands from given file to the scheduler
`void`	`await()` 等待排程器開始執行，包括等待從舊版 TF 完成移交 (如適用)。
`static TradefedDelegator`	`checkDelegation(String[] args)` 根據指令列建立委派者，確認是否需要委派執行作業。
`static`	`createReleaseMap(IInvocationContext context, Throwable e)` 建立裝置狀態的地圖，以便適當發布。
`ISandbox`	`createSandbox()` 建立調用作業將用於執行的 `ISandbox`。
`void`	`displayCommandQueue(PrintWriter printWriter)` 輸出指令執行佇列狀態的詳細偵錯資訊。
`void`	`displayCommandsInfo(PrintWriter printWriter, String regex)` 輸出目前的指令清單。
`void`	`displayInvocationsInfo(PrintWriter printWriter)` 顯示目前的叫用清單。
`void`	`dumpCommandsXml(PrintWriter printWriter, String regex)` 傾印指令的展開 XML 檔案，並為所有目前指令指定所有 `Option` 值。
`long`	`execCommand(ICommandScheduler.IScheduledInvocationListener listener, ITestDevice device, String[] args)` 直接在已分配的裝置上執行指令。
`long`	`execCommand(ICommandScheduler.IScheduledInvocationListener listener, reservedDevices, String[] args)` 直接在已分配的裝置上執行指令。
`long`	`execCommand(IInvocationContext context, ICommandScheduler.IScheduledInvocationListener listener, String[] args)` 直接分配裝置並執行指令，不必使用現有的 `IInvocationContext` 將指令新增至指令佇列。
`long`	`execCommand(ICommandScheduler.IScheduledInvocationListener listener, String[] args)` 直接分配裝置並執行指令，不必將指令加入指令佇列。
`CommandFileWatcher`	`getCommandFileWatcher()` Get the appropriate CommandFileWatcher for this scheduler
`int`	`getExecutingCommandCount()` 傳回處於執行狀態的指令數。
`CommandScheduler.HostState`	`getHostState()`
`String`	`getInvocationInfo(int invocationId)` 指定叫用 ID，即可傳回叫用資訊。
`CommandRunner.ExitCode`	`getLastInvocationExitCode()` 傳回上次執行的呼叫作業錯誤代碼。
`Throwable`	`getLastInvocationThrowable()` 傳回上次執行的叫用作業中的 `Throwable`。
`int`	`getReadyCommandCount()` 傳回佇列中處於就緒狀態的指令數量。
`long`	`getShutdownTimeout()`
`boolean`	`isDeviceInInvocationThread(ITestDevice device)` 如果裝置是由有效叫用執行緒使用，則傳回 true。
`boolean`	`isShuttingDown()`
`void`	`notifyFileChanged(File cmdFile, extraArgs)`
`void`	`removeAllCommands()` 從排程器移除所有指令
`void`	`run()` 這個執行緒的主要執行區塊。
`void`	`setClearcutClient(ClearcutClient client)` 將用戶端設為回報安全帶資料
`void`	`setMaxPollTime(long polling)`
`void`	`setPrintSchedulingWarning(boolean print)`
`boolean`	`shouldShutdownOnCmdfileError()` Return true if we need to shutdown the scheduler on a command errors
`void`	`shutdown(boolean notifyStop)` 嘗試安全關閉指令排程器。
`void`	`shutdownHard(boolean killAdb)` 嘗試強制關閉指令排程器。
`void`	`shutdownHard()` 嘗試強制關閉指令排程器。
`void`	`shutdownOnEmpty()` 與 `shutdown()` 類似，但會等待所有指令執行完畢才結束。
`void`	`start()` 啟動排程器，包括設定記錄、初始化 `DeviceManager` 等
`boolean`	`stopInvocation(ITestInvocation invocation)` 停止執行中的叫用。
`boolean`	`stopInvocation(int invocationId, String cause)` 指定 ID 即可停止執行中的叫用。
`void`	`stopScheduling()` 停止排定及接受新測試，但不會停止 Tradefed。

受保護的方法
`void`	`cleanUp()` 關閉記錄並執行任何其他必要的清除作業，然後結束。
`IConfiguration`	`createConfiguration(String[] args)`
`IInvocationContext`	`createInvocationContext()`
`void`	`dryRunCommandReporting(ICommandScheduler.IScheduledInvocationListener handler, IConfiguration config)` 判斷指定指令是否為模擬執行。
`long`	`execCommand(IInvocationContext context, ICommandScheduler.IScheduledInvocationListener listener, reservedDevices, String[] args)`
`IConfigurationFactory`	`getConfigFactory()` 取得 `IConfigurationFactory` 參考資料的工廠方法
`DeviceManagementGrpcServer`	`getDeviceManagementServer()`
`IDeviceManager`	`getDeviceManager()` 取得 `IDeviceManager` 參考資料的工廠方法
`TradefedFeatureServer`	`getFeatureServer()`
`IHostOptions`	`getHostOptions()`
`IKeyStoreClient`	`getKeyStoreClient()` 使用 `IGlobalConfiguration` 中宣告的 `IKeyStoreFactory` 擷取 `IKeyStoreClient`，如果未定義任何項目，則為空值。
`TestInvocationManagementServer`	`getTestInvocationManagementServer()`
`void`	`initLogging()` 初始化 ddmlib 記錄。
`boolean`	`isShutdown()`
`void`	`processReadyCommands(IDeviceManager manager)`

公用建構函式

CommandScheduler

public CommandScheduler ()

建立 CommandScheduler。

注意：必須先呼叫 start，才能使用。

公用方法

addCommand

public Pair<Boolean, Integer> addCommand (String[] args)

將指令新增至排程器。

指令基本上就是要執行的設定執行個體，以及相關聯的引數。

如果指定「--help」引數，設定的說明文字會輸出至 stdout。否則，設定檔會新增至佇列以供執行。

參數
`args`	`String`：設定引數。

傳回
`Pair<Boolean, Integer>`	一組值，第一個值是布林值，如果指令已成功新增，則為 `true`。如果指令新增成功，第二個值是已知的指令追蹤器 ID(非負值)；如果為所有裝置新增指令，則傳回 0；否則傳回 -1。

擲回
`ConfigurationException`

addCommandFile

public void addCommandFile (String cmdFilePath, 
                 extraArgs)

將指定檔案中的所有指令新增至排程器

參數
`cmdFilePath`	`String`：指令檔案的檔案系統路徑
`extraArgs`	：要附加至從檔案剖析的每個指令的 `String` 引數 `ERROR(/List)`。可以留空，但不得為空值。

擲回
`ConfigurationException`

await

public void await ()

等待排程器開始執行，包括等待從舊版 TF 完成移交 (如適用)。

checkDelegation

public static TradefedDelegator checkDelegation (String[] args)

根據指令列建立委派者，確認是否需要委派執行作業。

參數
`args`	`String`

傳回
`TradefedDelegator`

擲回
	com.android.tradefed.config.ConfigurationException
`ConfigurationException`

createReleaseMap

public static  createReleaseMap (IInvocationContext context, 
                Throwable e)

建立裝置狀態的地圖，以便適當釋出裝置。

參數
`context`	`IInvocationContext`
`e`	`Throwable`

傳回

createSandbox

public ISandbox createSandbox ()

建立供叫用作業執行的 ISandbox。

傳回
`ISandbox`

displayCommandQueue

public void displayCommandQueue (PrintWriter printWriter)

輸出指令執行佇列狀態的詳細偵錯資訊。

displayCommandsInfo

public void displayCommandsInfo (PrintWriter printWriter, 
                String regex)

輸出目前的指令清單。

參數
`printWriter`	`PrintWriter`：要輸出至的 `ERROR(/PrintWriter)`。
`regex`	`String`：規則運算式，指令必須符合這個運算式才會列印。如果為空值，則會列印所有指令。

displayInvocationsInfo

public void displayInvocationsInfo (PrintWriter printWriter)

顯示目前的叫用清單。

參數
`printWriter`	`PrintWriter`：要輸出至的 `ERROR(/PrintWriter)`。

dumpCommandsXml

public void dumpCommandsXml (PrintWriter printWriter, 
                String regex)

傾印指令的展開 XML 檔案，並為所有目前指令指定所有 Option 值。

參數
`printWriter`	`PrintWriter`：要輸出狀態的 `ERROR(/PrintWriter)`。
`regex`	`String`：指令應比對的規則運算式，以便傾印 XML 檔案。如果為空值，系統會傾印所有指令。

execCommand

public long execCommand (ICommandScheduler.IScheduledInvocationListener listener, 
                ITestDevice device, 
                String[] args)

直接在已分配的裝置上執行指令。

參數
`listener`	`ICommandScheduler.IScheduledInvocationListener`：要通知的 `ICommandScheduler.IScheduledInvocationListener`
`device`	`ITestDevice`：要使用的 `ITestDevice`
`args`	`String`：指令引數

傳回
`long`	排定指令的叫用 ID。

擲回
`ConfigurationException`

execCommand

public long execCommand (ICommandScheduler.IScheduledInvocationListener listener, 
                 reservedDevices, 
                String[] args)

直接在已分配的裝置上執行指令。

參數
`listener`	`ICommandScheduler.IScheduledInvocationListener`：要通知的 `ICommandScheduler.IScheduledInvocationListener`
`reservedDevices`	：要使用的 `ERROR(/List)`
`args`	`String`：指令引數

傳回
`long`	排定指令的叫用 ID。

擲回
`ConfigurationException`

execCommand

public long execCommand (IInvocationContext context, 
                ICommandScheduler.IScheduledInvocationListener listener, 
                String[] args)

直接分配裝置並執行指令，不必使用現有的 IInvocationContext 將指令新增至指令佇列。

參數
`context`	`IInvocationContext`：現有 `IInvocationContext`。
`listener`	`ICommandScheduler.IScheduledInvocationListener`：要通知的 `ICommandScheduler.IScheduledInvocationListener`
`args`	`String`：指令引數

傳回
`long`

擲回
`ConfigurationException`
`NoDeviceException`

execCommand

public long execCommand (ICommandScheduler.IScheduledInvocationListener listener, 
                String[] args)

直接分配裝置並執行指令，不必將裝置新增至指令佇列。

參數
`listener`	`ICommandScheduler.IScheduledInvocationListener`：要通知的 `ICommandScheduler.IScheduledInvocationListener`
`args`	`String`：指令引數

傳回
`long`	排定指令的叫用 ID。

擲回
`ConfigurationException`
`NoDeviceException`

getCommandFileWatcher

public CommandFileWatcher getCommandFileWatcher ()

取得這個排程器的適當 CommandFileWatcher

傳回
`CommandFileWatcher`

getExecutingCommandCount

public int getExecutingCommandCount ()

傳回處於執行狀態的指令數。

傳回
`int`

getHostState

public CommandScheduler.HostState getHostState ()

傳回
`CommandScheduler.HostState`

getInvocationInfo

public String getInvocationInfo (int invocationId)

指定叫用 ID，即可傳回叫用資訊。

參數
`invocationId`	`int`：呼叫的追蹤 ID。

傳回
`String`	`String`，其中包含有關呼叫的資訊。

getLastInvocationExitCode

public CommandRunner.ExitCode getLastInvocationExitCode ()

傳回上次執行的叫用作業錯誤代碼。如果尚未執行任何叫用，則傳回 0 (無錯誤)。

傳回
`CommandRunner.ExitCode`

getLastInvocationThrowable

public Throwable getLastInvocationThrowable ()

傳回上次執行的呼叫所傳回的 Throwable。如果沒有可擲回的項目，則傳回空值。

傳回
`Throwable`

getReadyCommandCount

public int getReadyCommandCount ()

傳回佇列中處於就緒狀態的指令數。

傳回
`int`

getShutdownTimeout

public long getShutdownTimeout ()

傳回
`long`

isDeviceInInvocationThread

public boolean isDeviceInInvocationThread (ITestDevice device)

如果裝置是由有效叫用執行緒使用，則傳回 true。

參數
`device`	`ITestDevice`

傳回
`boolean`

isShuttingDown

public boolean isShuttingDown ()

傳回
`boolean`

notifyFileChanged

public void notifyFileChanged (File cmdFile, 
                 extraArgs)

參數
`cmdFile`	`File`
`extraArgs`

removeAllCommands

public void removeAllCommands ()

從排程器移除所有指令

得分

public void run ()

這個執行緒的主要執行區塊。

setClearcutClient

public void setClearcutClient (ClearcutClient client)

將用戶端設為回報安全帶資料

參數
`client`	`ClearcutClient`

setMaxPollTime

public void setMaxPollTime (long polling)

參數
`polling`	`long`

setPrintSchedulingWarning

public void setPrintSchedulingWarning (boolean print)

參數
`print`	`boolean`

shouldShutdownOnCmdfileError

public boolean shouldShutdownOnCmdfileError ()

Return true if we need to shutdown the scheduler on a command errors

傳回
`boolean`

關機

public void shutdown (boolean notifyStop)

嘗試安全關閉指令排程器。

參數
`notifyStop`	`boolean`：如果為 true，則會通知 TF 關機的呼叫。

shutdownHard

public void shutdownHard (boolean killAdb)

嘗試強制關閉指令排程器。

與 shutdown() 類似，但也會選擇性終止 ADB 連線，嘗試「激發」進行中的呼叫，以更快完成。

參數
`killAdb`	`boolean`

shutdownHard

public void shutdownHard ()

嘗試強制關閉指令排程器。與 shutdownHard(true) 相同。

shutdownOnEmpty

public void shutdownOnEmpty ()

與 shutdown() 類似，但會等待所有指令執行完畢才結束。

請注意，如果任何指令處於迴圈模式，排程器就不會結束。

start

public void start ()

啟動排程器，包括設定記錄、初始化 DeviceManager 等

stopInvocation

public boolean stopInvocation (ITestInvocation invocation)

停止執行中的叫用。

參數
`invocation`	`ITestInvocation`

傳回
`boolean`	如果停止呼叫，則為 true，否則為 false

stopInvocation

public boolean stopInvocation (int invocationId, 
                String cause)

指定 ID 即可停止執行中的叫用。

參數
`invocationId`	`int`：呼叫的追蹤 ID。
`cause`	`String`：停止呼叫的原因。

傳回
`boolean`	如果停止呼叫，則為 true，否則為 false

stopScheduling

public void stopScheduling ()

停止排定及接受新測試，但不會停止 Tradefed。這是為了啟用兩步驟關機程序，首先排空所有執行中的測試，然後終止 Tradefed 程序。

受保護的方法

cleanUp

protected void cleanUp ()

關閉記錄並執行任何其他必要的清除作業，然後結束。

公開，以便單元測試可以模擬。

createConfiguration

protected IConfiguration createConfiguration (String[] args)

參數
`args`	`String`

傳回
`IConfiguration`

擲回
`ConfigurationException`

createInvocationContext

protected IInvocationContext createInvocationContext ()

傳回
`IInvocationContext`

dryRunCommandReporting

protected void dryRunCommandReporting (ICommandScheduler.IScheduledInvocationListener handler, 
                IConfiguration config)

判斷指定指令是否為模擬測試。如果指令是模擬測試，請驗證指令。如有任何設定問題，系統會擲回 ConfigurationException。

參數
`handler`	`ICommandScheduler.IScheduledInvocationListener`：`ERROR(/InvocationEventHandler)`，用於回報乾式執行驗證的事件。
`config`	`IConfiguration`

傳回
`void`	如果是模擬執行指令，則為 true，否則為 false。

擲回
	com.android.tradefed.config.ConfigurationException
`ConfigurationException`

execCommand

protected long execCommand (IInvocationContext context, 
                ICommandScheduler.IScheduledInvocationListener listener, 
                 reservedDevices, 
                String[] args)

參數
`context`	`IInvocationContext`
`listener`	`ICommandScheduler.IScheduledInvocationListener`
`reservedDevices`
`args`	`String`

傳回
`long`

擲回
`ConfigurationException`

getConfigFactory

protected IConfigurationFactory getConfigFactory ()

取得 IConfigurationFactory 參照的工廠方法

傳回
`IConfigurationFactory`	要使用的 `IConfigurationFactory`

getDeviceManagementServer

protected DeviceManagementGrpcServer getDeviceManagementServer ()

傳回
`DeviceManagementGrpcServer`

getDeviceManager

protected IDeviceManager getDeviceManager ()

取得 IDeviceManager 參照的工廠方法

傳回
`IDeviceManager`	要使用的 `IDeviceManager`

getFeatureServer

protected TradefedFeatureServer getFeatureServer ()

傳回
`TradefedFeatureServer`

getHostOptions

protected IHostOptions getHostOptions ()

傳回
`IHostOptions`

getKeyStoreClient

protected IKeyStoreClient getKeyStoreClient ()

使用 IGlobalConfiguration 中宣告的 IKeyStoreFactory 擷取 IKeyStoreClient，如果未定義任何項目，則為空值。

傳回
`IKeyStoreClient`	IKeyStoreClient

getTestInvocationManagementServer

protected TestInvocationManagementServer getTestInvocationManagementServer ()

傳回
`TestInvocationManagementServer`

initLogging

protected void initLogging ()

初始化 ddmlib 記錄。

公開，以便單元測試可以模擬。

isShutdown

protected boolean isShutdown ()

傳回
`boolean`

processReadyCommands

protected void processReadyCommands (IDeviceManager manager)

參數
`manager`	`IDeviceManager`