1 /* 2 * Copyright 2022 Google LLC 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.google.android.libraries.mobiledatadownload.file.spi; 17 18 import android.net.Uri; 19 import java.io.Closeable; 20 import javax.annotation.Nullable; 21 22 /** 23 * A Monitor observes the stream. It can be used for passively tracking activity such as number of 24 * bytes read and written. Monitors are not invoked for non-stream-based operations. 25 * 26 * <p>Monitors are expected to passively observe and not mutate the stream. However, for efficiency, 27 * the raw byte[] is passed to the implementation so this is not enforced. If the array is mutated, 28 * the behavior is undefined. Moreover, monitors run as best-effort: if they encounter a problem, 29 * they are expected to get out of the way and not block the monitored stream transaction. This is 30 * why they do NOT have IOException in their method signatures. 31 * 32 * <p>Monitors are invoked after all transforms are applied for write, and before on read. For 33 * example, if there is a compression transform, this monitor will see the compressed bytes. 34 * 35 * <p>The original Uri passed to the FileStorage API, including transforms, is passed to this API. 36 */ 37 public interface Monitor { 38 39 /** Creates a new input monitor for this Uri, or null if this IO doesn't need to be monitored. */ 40 @Nullable monitorRead(Uri uri)41 InputMonitor monitorRead(Uri uri); 42 43 /** Creates a new output monitor for this Uri, or null if this IO doesn't need to be monitored. */ 44 @Nullable monitorWrite(Uri uri)45 OutputMonitor monitorWrite(Uri uri); 46 47 /** Creates a new output monitor for this Uri, or null if this IO doesn't need to be monitored. */ 48 @Nullable monitorAppend(Uri uri)49 OutputMonitor monitorAppend(Uri uri); 50 51 /** Monitors data read. */ 52 interface InputMonitor extends Closeable { 53 /** Called with bytes as they are read from the stream. */ bytesRead(byte[] b, int off, int len)54 void bytesRead(byte[] b, int off, int len); 55 56 @Override close()57 default void close() { 58 // Ignore. 59 } 60 } 61 62 /** Monitors data written. */ 63 interface OutputMonitor extends Closeable { 64 /** Called with bytes as they are written to the stream. */ bytesWritten(byte[] b, int off, int len)65 void bytesWritten(byte[] b, int off, int len); 66 67 @Override close()68 default void close() { 69 // Ignore. 70 } 71 } 72 } 73