1 /*
2  * Copyright (C) 2020 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 
17 package com.android.internal.protolog.common;
18 
19 /**
20  * ProtoLog API - exposes static logging methods. Usage of this API is similar
21  * to {@code android.utils.Log} class. Instead of plain text log messages each call consists of
22  * a messageString, which is a format string for the log message (has to be a string literal or
23  * a concatenation of string literals) and a vararg array of parameters for the formatter.
24  *
25  * The syntax for the message string depends on
26  * {@link android.text.TextUtils#formatSimple(String, Object...)}}.
27  * Supported conversions:
28  * %b - boolean
29  * %d %x - integral type (Short, Integer or Long)
30  * %f - floating point type (Float or Double)
31  * %s - string
32  * %% - a literal percent character
33  * The width and precision modifiers are supported, argument_index and flags are not.
34  *
35  * Methods in this class are stubs, that are replaced by optimised versions by the ProtoLogTool
36  * during build.
37  */
38 public class ProtoLog {
39 
40     // Needs to be set directly otherwise the protologtool tries to transform the method call
41     public static boolean REQUIRE_PROTOLOGTOOL = true;
42 
43     /**
44      * DEBUG level log.
45      *
46      * @param group         {@code IProtoLogGroup} controlling this log call.
47      * @param messageString constant format string for the logged message.
48      * @param args          parameters to be used with the format string.
49      */
d(IProtoLogGroup group, String messageString, Object... args)50     public static void d(IProtoLogGroup group, String messageString, Object... args) {
51         // Stub, replaced by the ProtoLogTool.
52         if (REQUIRE_PROTOLOGTOOL) {
53             throw new UnsupportedOperationException(
54                     "ProtoLog calls MUST be processed with ProtoLogTool");
55         }
56     }
57 
58     /**
59      * VERBOSE level log.
60      *
61      * @param group         {@code IProtoLogGroup} controlling this log call.
62      * @param messageString constant format string for the logged message.
63      * @param args          parameters to be used with the format string.
64      */
v(IProtoLogGroup group, String messageString, Object... args)65     public static void v(IProtoLogGroup group, String messageString, Object... args) {
66         // Stub, replaced by the ProtoLogTool.
67         if (REQUIRE_PROTOLOGTOOL) {
68             throw new UnsupportedOperationException(
69                     "ProtoLog calls MUST be processed with ProtoLogTool");
70         }
71     }
72 
73     /**
74      * INFO level log.
75      *
76      * @param group         {@code IProtoLogGroup} controlling this log call.
77      * @param messageString constant format string for the logged message.
78      * @param args          parameters to be used with the format string.
79      */
i(IProtoLogGroup group, String messageString, Object... args)80     public static void i(IProtoLogGroup group, String messageString, Object... args) {
81         // Stub, replaced by the ProtoLogTool.
82         if (REQUIRE_PROTOLOGTOOL) {
83             throw new UnsupportedOperationException(
84                     "ProtoLog calls MUST be processed with ProtoLogTool");
85         }
86     }
87 
88     /**
89      * WARNING level log.
90      *
91      * @param group         {@code IProtoLogGroup} controlling this log call.
92      * @param messageString constant format string for the logged message.
93      * @param args          parameters to be used with the format string.
94      */
w(IProtoLogGroup group, String messageString, Object... args)95     public static void w(IProtoLogGroup group, String messageString, Object... args) {
96         // Stub, replaced by the ProtoLogTool.
97         if (REQUIRE_PROTOLOGTOOL) {
98             throw new UnsupportedOperationException(
99                     "ProtoLog calls MUST be processed with ProtoLogTool");
100         }
101     }
102 
103     /**
104      * ERROR level log.
105      *
106      * @param group         {@code IProtoLogGroup} controlling this log call.
107      * @param messageString constant format string for the logged message.
108      * @param args          parameters to be used with the format string.
109      */
e(IProtoLogGroup group, String messageString, Object... args)110     public static void e(IProtoLogGroup group, String messageString, Object... args) {
111         // Stub, replaced by the ProtoLogTool.
112         if (REQUIRE_PROTOLOGTOOL) {
113             throw new UnsupportedOperationException(
114                     "ProtoLog calls MUST be processed with ProtoLogTool");
115         }
116     }
117 
118     /**
119      * WHAT A TERRIBLE FAILURE level log.
120      *
121      * @param group         {@code IProtoLogGroup} controlling this log call.
122      * @param messageString constant format string for the logged message.
123      * @param args          parameters to be used with the format string.
124      */
wtf(IProtoLogGroup group, String messageString, Object... args)125     public static void wtf(IProtoLogGroup group, String messageString, Object... args) {
126         // Stub, replaced by the ProtoLogTool.
127         if (REQUIRE_PROTOLOGTOOL) {
128             throw new UnsupportedOperationException(
129                     "ProtoLog calls MUST be processed with ProtoLogTool");
130         }
131     }
132 
133     /**
134      * Check if ProtoLog isEnabled for a target group.
135      * @param group Group to check enable status of.
136      * @return true iff this is being logged.
137      */
isEnabled(IProtoLogGroup group, LogLevel level)138     public static boolean isEnabled(IProtoLogGroup group, LogLevel level) {
139         if (REQUIRE_PROTOLOGTOOL) {
140             throw new UnsupportedOperationException(
141                     "ProtoLog calls MUST be processed with ProtoLogTool");
142         }
143         return false;
144     }
145 
146     /**
147      * Get the single ProtoLog instance.
148      * @return A singleton instance of ProtoLog.
149      */
getSingleInstance()150     public static IProtoLog getSingleInstance() {
151         if (REQUIRE_PROTOLOGTOOL) {
152             throw new UnsupportedOperationException(
153                     "ProtoLog calls MUST be processed with ProtoLogTool");
154         }
155         return null;
156     }
157 }
158