/*
* Copyright (C) 2021 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 androidx.test.platform.io;
import androidx.test.annotation.ExperimentalTestApi;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.Serializable;
import java.util.Map;
/**
* An interface represents on-device I/O operations in an Android test.
*
* <p>This is a low level API, typically used by higher level test frameworks. It is generally not
* recommended for direct use by most tests.
*
* <p>Use a concrete implementation class of this interface if you need to read/write files in your
* tests. For example, in an Android Instrumentation test, use {@code
* androidx.test.services.storage.TestStorage} when the test services is installed on the device.
*
* <p>This API is experimental and is subject to change or removal in future releases.
*/
@ExperimentalTestApi
public interface PlatformTestStorage {
/**
* Provides an InputStream to a test file dependency.
*
* @param pathname path to the test file dependency. Should not be null.
* @return an InputStream to the given test file.
*/
InputStream openInputFile(String pathname) throws IOException;
/**
* Returns the value of a given argument name.
*
* @param argName the argument name. Should not be null.
*/
String getInputArg(String argName);
/**
* Returns the name/value map of all test arguments or an empty map if no arguments are defined.
*/
Map<String, String> getInputArgs();
/**
* Provides an OutputStream to a test output file.
*
* @param pathname path to the test output file. Should not be null.
* @return an OutputStream to the given output file.
*/
OutputStream openOutputFile(String pathname) throws IOException;
/**
* Provides an OutputStream to a test output file.
*
* @param pathname path to the test output file. Should not be null.
* @param append if true, then the lines will be added to the end of the file rather than
* overwriting.
* @return an OutputStream to the given output file.
*/
OutputStream openOutputFile(String pathname, boolean append) throws IOException;
/**
* Adds the given properties.
*
* <p>Adding a property with the same name would append new values and overwrite the old values if
* keys already exist.
*/
void addOutputProperties(Map<String, Serializable> properties);
/**
* Returns a map of all the output test properties. If no properties exist, an empty map will be
* returned.
*/
Map<String, Serializable> getOutputProperties();
/**
* Provides an InputStream to an internal file used by the testing infrastructure.
*
* @param pathname path to the internal file. Should not be null.
* @return an InputStream to the given test file.
*/
InputStream openInternalInputFile(String pathname) throws IOException;
/**
* Provides an OutputStream to an internal file used by the testing infrastructure.
*
* @param pathname path to the internal file. Should not be null.
* @return an OutputStream to the given output file.
*/
OutputStream openInternalOutputFile(String pathname) throws IOException;
}