services/core/java/com/android/server/utils/PriorityDump.java

/**
 * Copyright (c) 2016, 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.server.utils;

import android.annotation.IntDef;

import java.io.FileDescriptor;
import java.io.PrintWriter;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Iterator;

/**
 * Helper for {@link android.os.Binder#dump(java.io.FileDescriptor, String[])} that supports the
 * {@link #PRIORITY_ARG} and {@link #PROTO_ARG} arguments.
 * <p>
 * Typical usage:
 *
 * <pre><code>
public class SpringfieldNuclearPowerPlant extends Binder {

 private final PriorityDump.PriorityDumper mPriorityDumper = new PriorityDump.PriorityDumper() {

     @Override
     public void dumpCritical(FileDescriptor fd, PrintWriter pw, String[] args, boolean asProto) {
       if (asProto) {
         ProtoOutputStream proto = new ProtoOutputStream(fd);
         proto.write(SpringfieldProto.DONUTS, 1);
         proto.flush();
       } else {
         pw.println("Donuts in the box: 1");
       }
     }

     @Override
     public void dumpNormal(FileDescriptor fd, PrintWriter pw, String[] args) {
        if (asProto) {
          ProtoOutputStream proto = new ProtoOutputStream(fd);
          proto.write(SpringfieldProto.REACTOR_STATUS, DANGER_MELTDOWN_IMMINENT);
          proto.flush();
        } else {
          pw.println("Nuclear reactor status: DANGER - MELTDOWN IMMINENT");
        }
     }
  };

  @Override
  protected void dump(FileDescriptor fd, PrintWriter pw, String[] args) {
      PriorityDump.dump(mPriorityDumper, fd, pw, args);
  }
}

 * </code></pre>
 *
 * <strong>Disclaimer</strong>: a real-life service should prioritize core status over donuts :-)
 *
 * <p>Then to invoke it:
 *
 * <pre><code>
 *
    $ adb shell dumpsys snpp
    Donuts in the box: 1
    Nuclear reactor status: DANGER - MELTDOWN IMMINENT

    $ adb shell dumpsys snpp --dump-priority CRITICAL
    Donuts in the box: 1

    $ adb shell dumpsys snpp --dump-priority NORMAL
    Nuclear reactor status: DANGER - MELTDOWN IMMINENT

    $ adb shell dumpsys snpp --dump-priority CRITICAL --proto
    //binary output

 * </code></pre>
 *
 *
 *
 * <p>To run the unit tests:
 * <pre><code>
 *
 atest FrameworksServicesTests:PriorityDumpTest
 * </code></pre>
 *
 *
 * @hide
 */
public final class PriorityDump {

    public static final String PRIORITY_ARG = "--dump-priority";
    public static final String PROTO_ARG = "--proto";
    public static final String PRIORITY_ARG_CRITICAL = "CRITICAL";
    public static final String PRIORITY_ARG_HIGH = "HIGH";
    public static final String PRIORITY_ARG_NORMAL = "NORMAL";

    private PriorityDump() {
        throw new UnsupportedOperationException();
    }

    /** Enum to switch through supported priority types */
    @Retention(RetentionPolicy.SOURCE)
    @IntDef({PRIORITY_TYPE_INVALID, PRIORITY_TYPE_CRITICAL, PRIORITY_TYPE_HIGH,
            PRIORITY_TYPE_NORMAL})
    private @interface PriorityType { }
    private static final int PRIORITY_TYPE_INVALID = 0;
    private static final int PRIORITY_TYPE_CRITICAL = 1;
    private static final int PRIORITY_TYPE_HIGH = 2;
    private static final int PRIORITY_TYPE_NORMAL = 3;

    /**
     * Parses {@code args} matching {@code --dump-priority} and/or {@code --proto}. The matching
     * arguments are stripped.
     * <p>
     * If priority args are passed as an argument, it will call the appropriate method and if proto
     * args are passed then the {@code asProto} flag is set.
     * <p>
     * For example, if called as {@code --dump-priority HIGH arg1 arg2 arg3}, it will call
     * <code>dumper.dumpHigh(fd, pw, {"arg1", "arg2", "arg3"}, false) </code>
     * <p>
     * If the {@code --dump-priority} is not set, it calls
     * {@link PriorityDumper#dump(FileDescriptor, PrintWriter, String[], boolean)} passing the whole
     * {@code args} instead.
     */
    public static void dump(PriorityDumper dumper, FileDescriptor fd, PrintWriter pw,
            String[] args) {
        boolean asProto = false;
        @PriorityType int priority = PRIORITY_TYPE_INVALID;

        if (args == null) {
            dumper.dump(fd, pw, args, asProto);
            return;
        }

        String[] strippedArgs = new String[args.length];
        int strippedCount = 0;
        for (int argIndex = 0; argIndex < args.length; argIndex++) {
            if (args[argIndex].equals(PROTO_ARG)) {
                asProto = true;
            } else if (args[argIndex].equals(PRIORITY_ARG)) {
                if (argIndex + 1 < args.length) {
                    argIndex++;
                    priority = getPriorityType(args[argIndex]);
                }
            } else {
                strippedArgs[strippedCount++] = args[argIndex];
            }
        }

        if (strippedCount < args.length) {
            strippedArgs = Arrays.copyOf(strippedArgs, strippedCount);
        }

        switch (priority) {
            case PRIORITY_TYPE_CRITICAL: {
                dumper.dumpCritical(fd, pw, strippedArgs, asProto);
                return;
            }
            case PRIORITY_TYPE_HIGH: {
                dumper.dumpHigh(fd, pw, strippedArgs, asProto);
                return;
            }
            case PRIORITY_TYPE_NORMAL: {
                dumper.dumpNormal(fd, pw, strippedArgs, asProto);
                return;
            }
            default: {
                dumper.dump(fd, pw, strippedArgs, asProto);
                return;
            }
        }
    }

    /**
     * Converts priority argument type to enum.
     */
    private static @PriorityType int getPriorityType(String arg) {
        switch (arg) {
            case PRIORITY_ARG_CRITICAL: {
                return PRIORITY_TYPE_CRITICAL;
            }
            case PRIORITY_ARG_HIGH: {
                return PRIORITY_TYPE_HIGH;
            }
            case PRIORITY_ARG_NORMAL: {
                return PRIORITY_TYPE_NORMAL;
            }
            default: {
                return PRIORITY_TYPE_INVALID;
            }
        }
    }

    /**
     * Helper for {@link android.os.Binder#dump(java.io.FileDescriptor, String[])} that supports the
     * {@link #PRIORITY_ARG} and {@link #PROTO_ARG} arguments.
     *
     * @hide
     */
    public interface PriorityDumper {

        /**
         * Dumps only the critical section.
         */
        @SuppressWarnings("unused")
        default void dumpCritical(FileDescriptor fd, PrintWriter pw, String[] args,
                boolean asProto) {
        }

        /**
         * Dumps only the high-priority section.
         */
        @SuppressWarnings("unused")
        default void dumpHigh(FileDescriptor fd, PrintWriter pw, String[] args, boolean asProto) {
        }

        /**
         * Dumps only the normal section.
         */
        @SuppressWarnings("unused")
        default void dumpNormal(FileDescriptor fd, PrintWriter pw, String[] args, boolean asProto) {
        }

        /**
         * Dumps all sections.
         * <p>
         * This method is called when
         * {@link PriorityDump#dump(PriorityDumper, FileDescriptor, PrintWriter, String[])}
         * is called without priority arguments. By default, it calls the 3 {@code dumpTYPE}
         * methods, so sub-classes just need to implement the priority types they support.
         */
        @SuppressWarnings("unused")
        default void dump(FileDescriptor fd, PrintWriter pw, String[] args, boolean asProto) {
            dumpCritical(fd, pw, args, asProto);
            dumpHigh(fd, pw, args, asProto);
            dumpNormal(fd, pw, args, asProto);
        }
    }
}