| /* |
| * Copyright (C) 2010 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.android.tradefed.command; |
| |
| import com.android.tradefed.config.IConfigurationFactory; |
| import com.android.tradefed.invoker.ITestInvocation; |
| |
| import java.util.Collection; |
| |
| /** |
| * A scheduler for running TradeFederation commands. |
| */ |
| public interface ICommandScheduler { |
| |
| /** |
| * Adds a command to the scheduler. |
| * <p/> |
| * A command is essentially an instance of a configuration to run and its associated arguments. |
| * <p/> |
| * If "--help" argument is specified, or the config arguments are invalid, the help text for |
| * the config will be outputed to stdout. Otherwise, the config will be added to the queue to |
| * run. |
| * |
| * @param args the config arguments. |
| * @return <code>true</code> if command was added successfully |
| * |
| * @see {@link IConfigurationFactory#createConfigurationFromArgs(String[])} |
| */ |
| public boolean addCommand(String[] args); |
| |
| /** |
| * An alternate {@link #addCommand(String[])} that accepts a {@link ICommandListener} for |
| * monitoring command execution. |
| * |
| * @param args the config arguments. |
| * @param listener the {@link ICommandListener} |
| * @return <code>true</code> if command was added successfully |
| */ |
| public boolean addCommand(String[] args, ICommandListener listener); |
| |
| /** |
| * An alternate {@link #addCommand(String[], ICommandListener)} that accepts an initial total |
| * execution time for the command. |
| * <p/> |
| * Useful when transitioning pre-existing commands from another tradefed process |
| * |
| * @param args the config arguments. |
| * @param listener the {@link ICommandListener} |
| * @param totalExecTime the accumulated elapsed execution time of the command |
| * @return <code>true</code> if command was added successfully |
| */ |
| public boolean addCommand(String[] args, ICommandListener listener, long totalExecTime); |
| |
| /** |
| * Remove all commands from scheduler |
| */ |
| public void removeAllCommands(); |
| |
| /** |
| * Attempt to gracefully shutdown the command scheduler. |
| * <p/> |
| * Clears commands waiting to be tested, and requests that all invocations in progress |
| * shut down gracefully. |
| * <p/> |
| * After shutdown is called, the scheduler main loop will wait for all invocations in progress |
| * to complete before exiting completely. |
| */ |
| public void shutdown(); |
| |
| /** |
| * Initiates a {@link #shutdown()} and handover to another tradefed process on this same host. |
| * <p/> |
| * The scheduler will inform the remote tradefed process listening on that port of freed devices |
| * as they become available. |
| * |
| * @return <code>true</code> if handover initiation was successful, <code>false</code> |
| * otherwise |
| */ |
| public boolean handoverShutdown(int handoverPort); |
| |
| /** |
| * Attempt to forcefully shutdown the command scheduler. |
| * <p/> |
| * Similar to {@link #shutdown()}, but will also forcefully kill the adb connection, in an |
| * attempt to 'inspire' invocations in progress to complete quicker. |
| */ |
| public void shutdownHard(); |
| |
| /** |
| * Start the {@link ICommandScheduler}. |
| * <p/> |
| * Will run until {@link #shutdown()} is called. |
| * |
| * see {@link Thread#start()}. |
| */ |
| public void start(); |
| |
| /** |
| * Waits for scheduler to complete. |
| * |
| * @see {@link Thread#join()}. |
| */ |
| public void join() throws InterruptedException; |
| |
| /** |
| * Waits for scheduler to start running. |
| */ |
| public void await() throws InterruptedException; |
| |
| |
| // The following are optional management-related interfaces. |
| /** |
| * Get a list of current invocations. |
| * |
| * @return A list of {@link ITestInvocation} descriptions, or {@code null} if none |
| * @throw {@link UnsupportedOperationException} if the implementation doesn't support this |
| */ |
| public Collection<String> listInvocations() throws UnsupportedOperationException; |
| |
| /** |
| * Stop a running invocation. |
| * |
| * @return true if the invocation was stopped, false otherwise |
| * @throw {@link UnsupportedOperationException} if the implementation doesn't support this |
| */ |
| public boolean stopInvocation(ITestInvocation invocation) throws UnsupportedOperationException; |
| |
| /** |
| * Get a list of current commands. |
| * |
| * @return A list of current commands, pre-serialized |
| * @throw {@link UnsupportedOperationException} if the implementation doesn't support this |
| */ |
| public Collection<String> listCommands() throws UnsupportedOperationException; |
| |
| /** |
| * Starts a socket to listen to remote commands. |
| * <p/> |
| * Used to handle handover communication. @see {@link #handoverShutdown(int)}. |
| * |
| * @return the TCP port of the socket or -1 if it failed to start. |
| */ |
| public int startRemoteManager(); |
| |
| /** |
| * Cancels the currently running remote manager. |
| */ |
| public void stopRemoteManager(); |
| |
| } |