1 /* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.android.tradefed.result; 17 18 import com.android.tradefed.invoker.IInvocationContext; 19 20 import java.io.File; 21 import java.io.FileInputStream; 22 import java.io.IOException; 23 import java.io.InputStream; 24 25 /** 26 * Classes which implement this interface provide methods for storing logs to a central location. 27 * <p> 28 * A {@link ILogSaver} is declared in the configuration and is responsible for storing logs to a 29 * central location. It also exposes methods so {@link ILogSaverListener}s may save additional files 30 * to the same location. 31 * </p> 32 */ 33 public interface ILogSaver { 34 35 /** 36 * Early notification of initialization, before any build information are available. This allows 37 * to setup any requirements to receive logs. 38 * 39 * @param context information about the invocation. 40 */ init(IInvocationContext context)41 public default void init(IInvocationContext context) { 42 // Empty by default 43 } 44 45 /** 46 * Reports the start of the test invocation. 47 * <p> 48 * Will be automatically called by the TradeFederation framework before 49 * {@link ITestInvocationListener#invocationStarted(IInvocationContext)} is called. 50 * </p> 51 * 52 * @param context information about the invocation. 53 */ invocationStarted(IInvocationContext context)54 public void invocationStarted(IInvocationContext context); 55 56 /** 57 * Reports that the invocation has terminated, whether successfully or due to some error 58 * condition. 59 * <p> 60 * Will be automatically called by the TradeFederation framework after 61 * {@link ITestInvocationListener#invocationEnded(long)} is called. 62 * </p> 63 * 64 * @param elapsedTime the elapsed time of the invocation in ms 65 */ invocationEnded(long elapsedTime)66 public void invocationEnded(long elapsedTime); 67 68 /** 69 * Save the log data. 70 * 71 * <p>Will be automatically called by the TradeFederation framework whenever {@link 72 * ITestInvocationListener#testLog(String, LogDataType, InputStreamSource)} is called. It may 73 * also be used as a helper method to save additional log data. 74 * 75 * <p>Depending on the implementation and policy, the logs may be saved in a compressed form. 76 * Logs may also be stored in a location inaccessible to Tradefed. 77 * 78 * @param dataName a {@link String} descriptive name of the data. e.g. "device_logcat" 79 * @param dataType the {@link LogDataType} of the file. 80 * @param dataStream the {@link InputStream} of the data. 81 * @return the {@link LogFile} containing the path and URL of the saved file. 82 * @throws IOException if log file could not be generated 83 */ saveLogData(String dataName, LogDataType dataType, InputStream dataStream)84 public LogFile saveLogData(String dataName, LogDataType dataType, InputStream dataStream) 85 throws IOException; 86 87 /** 88 * Save the log file. 89 * 90 * <p>Will be automatically called by the TradeFederation framework whenever {@link 91 * ITestInvocationListener#testLog(String, LogDataType, InputStreamSource)} is called and the 92 * stream references a file. 93 * 94 * <p>Depending on the implementation and policy, the logs may be saved in a compressed form. 95 * Logs may also be stored in a location inaccessible to Tradefed. 96 * 97 * @param dataName a {@link String} descriptive name of the data. e.g. "device_logcat" 98 * @param dataType the {@link LogDataType} of the file. 99 * @param fileToLog the {@link File} to save. 100 * @return the {@link LogFile} containing the path and URL of the saved file. 101 * @throws IOException if log file could not be generated 102 */ saveLogFile(String dataName, LogDataType dataType, File fileToLog)103 public default LogFile saveLogFile(String dataName, LogDataType dataType, File fileToLog) 104 throws IOException { 105 try (FileInputStream dataStream = new FileInputStream(fileToLog)) { 106 return saveLogData(dataName, dataType, dataStream); 107 } 108 } 109 110 /** 111 * A helper method to save the log data unmodified. 112 * 113 * <p>Logs may be stored in a location inaccessible to Tradefed. 114 * 115 * @param dataName a {@link String} descriptive name of the data. e.g. "device_logcat". 116 * @param dataType a {@link LogDataType} containing the type and the extension of the file 117 * @param dataStream the {@link InputStream} of the data. 118 * @return the {@link LogFile} containing the path and URL of the saved file. 119 * @throws IOException if log file could not be generated 120 * @deprecated Use {@link #saveLogData(String, LogDataType, InputStream)} instead 121 */ 122 @Deprecated saveLogDataRaw( String dataName, LogDataType dataType, InputStream dataStream)123 public default LogFile saveLogDataRaw( 124 String dataName, LogDataType dataType, InputStream dataStream) throws IOException { 125 return saveLogData(dataName, dataType, dataStream); 126 } 127 128 /** 129 * Get the {@link LogFile} containing the path and/or URL of the directory where logs are saved. 130 * 131 * @return The {@link LogFile}. 132 */ getLogReportDir()133 public LogFile getLogReportDir(); 134 } 135