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 is a subset of {@code java.util.Formatter} syntax.
26  * Supported conversions:
27  * %b - boolean
28  * %d, %o and %x - integral type (Short, Integer or Long)
29  * %f, %e and %g - floating point type (Float or Double)
30  * %s - string
31  * %% - a literal percent character
32  * The width and precision modifiers are supported, argument_index and flags are not.
33  *
34  * Methods in this class are stubs, that are replaced by optimised versions by the ProtoLogTool
35  * during build.
36  */
37 public class ProtoLog {
38 
39     // Needs to be set directly otherwise the protologtool tries to transform the method call
40     public static boolean REQUIRE_PROTOLOGTOOL = true;
41 
42     /**
43      * DEBUG level log.
44      *
45      * @param group         {@code IProtoLogGroup} controlling this log call.
46      * @param messageString constant format string for the logged message.
47      * @param args          parameters to be used with the format string.
48      */
d(IProtoLogGroup group, String messageString, Object... args)49     public static void d(IProtoLogGroup group, String messageString, Object... args) {
50         // Stub, replaced by the ProtoLogTool.
51         if (REQUIRE_PROTOLOGTOOL) {
52             throw new UnsupportedOperationException(
53                     "ProtoLog calls MUST be processed with ProtoLogTool");
54         }
55     }
56 
57     /**
58      * VERBOSE level log.
59      *
60      * @param group         {@code IProtoLogGroup} controlling this log call.
61      * @param messageString constant format string for the logged message.
62      * @param args          parameters to be used with the format string.
63      */
v(IProtoLogGroup group, String messageString, Object... args)64     public static void v(IProtoLogGroup group, String messageString, Object... args) {
65         // Stub, replaced by the ProtoLogTool.
66         if (REQUIRE_PROTOLOGTOOL) {
67             throw new UnsupportedOperationException(
68                     "ProtoLog calls MUST be processed with ProtoLogTool");
69         }
70     }
71 
72     /**
73      * INFO level log.
74      *
75      * @param group         {@code IProtoLogGroup} controlling this log call.
76      * @param messageString constant format string for the logged message.
77      * @param args          parameters to be used with the format string.
78      */
i(IProtoLogGroup group, String messageString, Object... args)79     public static void i(IProtoLogGroup group, String messageString, Object... args) {
80         // Stub, replaced by the ProtoLogTool.
81         if (REQUIRE_PROTOLOGTOOL) {
82             throw new UnsupportedOperationException(
83                     "ProtoLog calls MUST be processed with ProtoLogTool");
84         }
85     }
86 
87     /**
88      * WARNING level log.
89      *
90      * @param group         {@code IProtoLogGroup} controlling this log call.
91      * @param messageString constant format string for the logged message.
92      * @param args          parameters to be used with the format string.
93      */
w(IProtoLogGroup group, String messageString, Object... args)94     public static void w(IProtoLogGroup group, String messageString, Object... args) {
95         // Stub, replaced by the ProtoLogTool.
96         if (REQUIRE_PROTOLOGTOOL) {
97             throw new UnsupportedOperationException(
98                     "ProtoLog calls MUST be processed with ProtoLogTool");
99         }
100     }
101 
102     /**
103      * ERROR level log.
104      *
105      * @param group         {@code IProtoLogGroup} controlling this log call.
106      * @param messageString constant format string for the logged message.
107      * @param args          parameters to be used with the format string.
108      */
e(IProtoLogGroup group, String messageString, Object... args)109     public static void e(IProtoLogGroup group, String messageString, Object... args) {
110         // Stub, replaced by the ProtoLogTool.
111         if (REQUIRE_PROTOLOGTOOL) {
112             throw new UnsupportedOperationException(
113                     "ProtoLog calls MUST be processed with ProtoLogTool");
114         }
115     }
116 
117     /**
118      * WHAT A TERRIBLE FAILURE level log.
119      *
120      * @param group         {@code IProtoLogGroup} controlling this log call.
121      * @param messageString constant format string for the logged message.
122      * @param args          parameters to be used with the format string.
123      */
wtf(IProtoLogGroup group, String messageString, Object... args)124     public static void wtf(IProtoLogGroup group, String messageString, Object... args) {
125         // Stub, replaced by the ProtoLogTool.
126         if (REQUIRE_PROTOLOGTOOL) {
127             throw new UnsupportedOperationException(
128                     "ProtoLog calls MUST be processed with ProtoLogTool");
129         }
130     }
131 }
132