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 /**
19  * Allows for {@link ITestInvocationListener}s to listen for when log files are saved.
20  *
21  * <p>This allows for multiple {@link ITestInvocationListener}s to use the same saved log file when
22  * generating reports, and avoids having each listener save the file individually when {@link
23  * ITestInvocationListener#testLog(String, LogDataType, InputStreamSource)} is called.
24  *
25  * <p>Classes implementing this interface should be aware that {@link #testLogSaved(String,
26  * LogDataType, InputStreamSource, LogFile)} will be called whenever {@link
27  * ITestInvocationListener#testLog(String, LogDataType, InputStreamSource)} is called.
28  *
29  * <p>This class also passes the global {@link ILogSaver} instance so {@link
30  * ITestInvocationListener}s can save additional files in the same location.
31  */
32 public interface ILogSaverListener extends ITestInvocationListener {
33 
34     /**
35      * Called when the test log is saved.
36      *
37      * <p>Should be used in place of {@link ITestInvocationListener#testLog(String, LogDataType,
38      * InputStreamSource)}.
39      *
40      * @param dataName a {@link String} descriptive name of the data. e.g. "device_logcat". Note
41      *     dataName may not be unique per invocation. ie implementers must be able to handle
42      *     multiple calls with same dataName
43      * @param dataType the {@link LogDataType} of the data
44      * @param dataStream the {@link InputStreamSource} of the data. Implementers should call
45      *     createInputStream to start reading the data, and ensure to close the resulting
46      *     InputStream when complete.
47      * @param logFile the {@link LogFile} containing the meta data of the saved file.
48      */
testLogSaved( String dataName, LogDataType dataType, InputStreamSource dataStream, LogFile logFile)49     public default void testLogSaved(
50             String dataName, LogDataType dataType, InputStreamSource dataStream, LogFile logFile) {
51         // Do nothing by default
52     }
53 
54     /**
55      * In some cases, log must be strongly associated with a test cases, but the opportunity to do
56      * so on the direct {@link #testLogSaved(String, LogDataType, InputStreamSource, LogFile)}
57      * callback is not possible. Thus, this callback allows to provide a strong association
58      * explicitly.
59      *
60      * @param dataName The name of the data
61      * @param logFile the {@link LogFile} that was logged before and should be associated with the
62      *     test case.
63      */
logAssociation(String dataName, LogFile logFile)64     public default void logAssociation(String dataName, LogFile logFile) {
65         // Do nothing by default
66     }
67 
68     /**
69      * Set the {@link ILogSaver} to allow the implementor to save files.
70      *
71      * @param logSaver the {@link ILogSaver}
72      */
setLogSaver(ILogSaver logSaver)73     public default void setLogSaver(ILogSaver logSaver) {
74         // Do nothing by default
75     }
76 }
77