1 // ${project.version}
2 var exec = require('cordova/exec');
3
4 /**
5 * The Kapsel Logger plugin provides a Cordova plugin wrapper around the SAP Mobile Platform client logging API.
6 * <br><br>
7 *
8 * The Logger plugin has ERROR, WARN, INFO, and DEBUG log levels and log messages are captured based on the configured and selected log level.
9 * A Kapsel application can be set to these log levels by programmatic control, and by the administrator changing a setting on the server.
10 * For Android and iOS, the default log level is ERROR, so by default only ERROR level logs are captured.
11 * sap.Logger.setLogLevel() method is used to set other levels. If you want to get log messages at all log levels,
12 * you must set the log level to DEBUG. (DEBUG < INFO < WARN < ERROR) <br>
13 * If the log level is set to DEBUG, the application captures all log messages. <br>
14 * If you set the log level to INFO, the application captures INFO, WARN, and ERROR log messages. <br>
15 * If you set the log level to WARN, the application captures WARN and ERROR log messages. <br>
16 * If you set the log level to ERROR, the application captures only Error log messages.
17 * <br><br>
18 *
19 * Using the provided sap.Logger.upload() method allows developers to upload a log file to SAP Mobile Platform Server,
20 * where an administrator can view them and remotely set the appropriate log level to control the amount of information
21 * that is written to the log. When the sap.Logger.upload() method is triggered, a log file will be uploaded.
22 * If the Log Upload checkbox is selected in the Management Cockpit, the client can upload a log file by calling sap.Logger.upload().
23 * If the Log Upload checkbox is disabled in the Management Cockpit, the client does not upload the log file to the server. The attempt to upload causes an "HTTP/1.1 403 Forbidden" error.
24 * To support manual uploading of the log, you should implement a button or some other mechanism that calls sap.Logger.upload() when needed.
25 * <br>
26 * For the Logger plugin to upload a log file these conditions must be met: 1) Log Upload checkbox enabled In the Management Cockpit 2) sap.Logger.upload() is called by developer.
27 * <br>
28 * The expected work flow, with the current architecture consists of the following: <br>
29 * 1) If a user has an issue that needs to be analyzed by an administrator or developer, the user reports the issue as appropriate.<br>
30 * 2) The administrator, or developer, enables the log collection for the user on the SAP Mobile Platform server.<br>
31 * 3) The administrator lets the user know that he, or she, can upload log file. <br>
32 * 4) The user uploads thelog file to the server, and the administrator gets the uploaded log file in the Management Cockpit.<br>
33 * 5) The administrator sends the file to the developer to debug.
34 * <br><br>
35 *
36 * Currently, on iOS, if the current log level is ERROR (default level), only ERROR level messages are displayed on the console
37 * even if other log level messages are generated. But if the current log level is DEBUG, INFO, or WARN,
38 * all generated log messages, regardless of log level, are displayed on the console. <br>
39 * On Android, all generated log messages, regardless of log level, are displayed in the Android logcat view (console)
40 * <br><br>
41 *
42 * When the Kapsel Settings plugin is added to the project, Settings will: 1) Get log level from the server 2) Set it into Logger on the client
43 * 3) Call sap.Logger.upload() after a logon success event, for example, when the app is launched or resumed and logon is successful.
44 * The Settings plugin retrieves the selected log level(type) from the Management Cockpit on the server,
45 * sets the log level to Logger plugin, and then automatically uploads a log file to the server.
46 * If the Settings plugin is not added to the project, a log file can be uploaded only by the developer calling the sap.Logger.upload() method manually.
47 * In the Management Cockpit, in the Client Logging dialog box, the Log Upload checkbox is able to enable or disable log file upload, and you can choose the log type(level).
48 * You can also view a list of the uploaded log files. On the server side, there are seven log types: NONE, FATAL, ERROR, WARNING, INFO, DEBUG and PATH.
49 * Since the Kapsel Logger plugin supports only DEBUG, INFO, WARN, and ERROR, the Logger plugin implicitly matches FATAL to ERROR, and PATH to DEBUG.
50 * If NONE is set in the Management Cockpit, Logger sets it to default log level.
51 * <br><br>
52 * <b>Adding and Removing the Logger Plugin</b><br>
53 * Add or remove the Logger plugin using the
54 * <a href="http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface">Cordova CLI</a>.<br>
55 * <br>
56 * To add the Logger plugin to your project, use the following command:<br>
57 * Cordova plugin add <path to directory containing Kapsel plugins>\logger<br>
58 * <br>
59 * To remove the Logger plugin from your project, use the following command:<br>
60 * cordova plugin rm com.sap.mp.cordova.plugins.logger
61 * <br>
62 *
63 * @namespace
64 * @alias Logger
65 * @memberof sap
66 */
67
68 Logger = function () {
69 /**
70 * Formating for message
71 * @private
72 */
73 var format = function (message) {
74 if ((message === null) || (message === undefined)) {
75 return "";
76 }
77
78 return message.toString();
79 }
80
81
82 /**
83 * Add a debug message to the log.
84 * This function logs messages with a 'DEBUG' log level.
85 *
86 * @memberof sap.Logger
87 * @method debug
88 * @param {String} message Log message to log.
89 * @param {String} [tag] Tag value added to the log entry used to indicate the source of the message (ex. SMP_LOGGER, SMP_AUTHPROXY).
90 * @param {function} [successCallback] Callback function called when the message has been successfully added to the log.
91 * No object will be passed to success callback.
92 * @param {function} [errorCallback] Callback function called when an error occurs while adding the message to the log.
93 * Since Kapsel Logger native code will always call the success callback function, the
94 * errorCallback function will be executed by Cordova if an error or exception occurs
95 * while making the call to the plugin.
96 * @public
97 * @memberof sap.Logger
98 * @example
99 * sap.Logger.debug("debug message", "DEBUG_TAG");
100 */
101 this.debug = function (message, tag, successCallback, errorCallback) {
102 exec(successCallback, errorCallback, "Logging", "logDebug", [format(message), tag]);
103 }
104
105 /**
106 * Add an info message to the log.
107 * This function logs messages with the 'INFO' log level.
108 *
109 * @memberof sap.Logger
110 * @method info
111 * @param {String} message Log message to be logged
112 * @param {String} [tag] Tag value added to the log entry used to indicate the source of the message (for example, SMP_LOGGER, SMP_AUTHPROXY).
113 * @param {function} [successCallback] Callback function called when the message has been successfully added to the log.
114 * No object will be passed to success callback.
115 * @param {function} [errorCallback] Callback function called when an error occurs while adding the message to the log.
116 * Since Kapsel Logger native code will always call the success callback function, the
117 * errorCallback function will be executed by Cordova if an error or exception occurs
118 * while making the call to the plugin.
119 * @public
120 * @memberof sap.Logger
121 * @example
122 * sap.Logger.info("info message", "INFO_TAG");
123 */
124 this.info = function (message, tag, successCallback, errorCallback) {
125 exec(successCallback, errorCallback, "Logging", "logInfo", [format(message), tag]);
126 }
127
128 /**
129 * Add a warning message to the log.
130 * This function logs messages with the 'WARN' log level.
131 *
132 * @memberof sap.Logger
133 * @method warn
134 * @param {String} message Log message to be logged.
135 * @param {String} [tag] Tag value added to the log entry used to indicate the source of the message (for example, SMP_LOGGER, SMP_AUTHPROXY).
136 * @param {function} [successCallback] Callback function called when the message has been successfully added to the log.
137 * No object will be passed to success callback.
138 * @param {function} [errorCallback] Callback function called when an error occurs while adding the message to the log.
139 * Since Kapsel Logger native code will always call the success callback function, the
140 * errorCallback function will be executed by Cordova if an error/exception occurs
141 * while making the call to the plugin.
142 * @public
143 * @memberof sap.Logger
144 * @example
145 * sap.Logger.warn("warn message", "WARN_TAG");
146 */
147 this.warn = function (message, tag, successCallback, errorCallback) {
148 exec(successCallback, errorCallback, "Logging", "logWarning", [format(message), tag]);
149 }
150
151 /**
152 * Add an error message to the log.
153 * This function logs messages with the 'ERROR' log level.
154 *
155 * @memberof sap.Logger
156 * @method error
157 * @param {String} message log Message to be logged.
158 * @param {String} [tag] Tag value added to the log entry used to indicate the source of the message (for example, SMP_LOGGER, SMP_AUTHPROXY).
159 * @param {function} [successCallback] Callback function called when the message has been successfully added to the log.
160 * No object will be passed to success callback.
161 * @param {function} [errorCallback] Callback function called when an error occurs while adding the message to the log.
162 * Since Kapsel Logger native code will always call the success callback function, the
163 * errorCallback function will be executed by Cordova if an error or exception occurs
164 * while making the call to the plugin.
165 * @public
166 * @memberof sap.Logger
167 * @example
168 * sap.Logger.error("error message", "ERROR_TAG");
169 */
170 this.error = function (message, tag, successCallback, errorCallback) {
171 exec(successCallback, errorCallback, "Logging", "logError", [format(message), tag]);
172 }
173
174 /**
175 * Set log level.
176 * This function sets the log level for logging. <br>
177 * Coverage of logging data in each log level: DEBUG < INFO < WARN < ERROR. <br>
178 * Following is the expected behavior to cover log messages at specific log levels: <br>
179 * ERROR : only ERROR messages <br>
180 * WARN : ERROR and WARN messages <br>
181 * INFO : ERROR, WARN and INFO <br>
182 * DEBUG : ERROR, WARN, INFO and DEBUG <br>
183 * For example, if you want to get all log messages, you need to set the log to the 'Debug' level.
184 * If the WARN level is set, logging data contains WARN and ERROR messages. <br>
185 * Default log level is ERROR.
186 *
187 * @memberof sap.Logger
188 * @method setLogLevel
189 * @param {String} level Log level to set [DEBUG, INFO, WARN, ERROR]
190 * @param {function} [successCallback] Callback function called when the log level has been successfully set.
191 * No object will be passed to success callback.
192 * @param {function} [errorCallback] Callback function called when an error occurs while setting the log level.
193 * Since Kapsel Logger native code will always call the success callback function, the
194 * errorCallback function will be executed by Cordova if an error or exception occurs
195 * while making the call to the plugin.
196 * @memberof sap.Logger
197 * @example
198 * sap.Logger.setLogLevel(sap.Logger.DEBUG, successCallback, errorCallback);
199 *
200 * function successCallback() {
201 * alert("Log level set");
202 * }
203 *
204 * function errorCallback() {
205 * alert("Failed to set log level");
206 * }
207 */
208 this.setLogLevel = function (level, successCallback, errorCallback) {
209 if (level.toLowerCase() === "fatal")
210 level = "ERROR";
211 else if (level.toLowerCase() === "path")
212 level = "DEBUG";
213 else if (level.toLowerCase() === "warning")
214 level = "WARN";
215
216 else if (level.toLowerCase() === "debug")
217 level = "DEBUG";
218 else if (level.toLowerCase() === "info")
219 level = "INFO";
220 else if (level.toLowerCase() === "error")
221 level = "ERROR";
222
223 exec(successCallback, errorCallback, "Logging", "setLogLevel", [level]);
224 }
225
226 /**
227 * Get log level.
228 * This function gets the current log level.
229 * Use this function to know what kind of log level messages can be generated and affected at the current log level.
230 *
231 * @memberof sap.Logger
232 * @method getLogLevel
233 * @param {function} successCallback Callback function called when the log level has been successfully retrieved.
234 * When the current log level is successfully retrieved, it is fired with the current log level. [DEBUG, INFO, WARN, ERROR]
235 * Log level of String type will be passed to success callback.
236 * Default log level is ERROR.
237 * @param {function} [errorCallback] Callback function called when an error occurs while getting the current log level. For this method, error callback is optional.
238 * Since Kapsel Logger native code will always call the success callback function, the
239 * errorCallback function will be executed by Cordova if an error or exception occurs
240 * while making the call to the plugin.
241 * @memberof sap.Logger
242 * @example
243 * sap.Logger.getLogLevel(successCallback, errorCallback);
244 *
245 * function successCallback(logLevel) {
246 * alert("Log level is " + logLevel);
247 * }
248 *
249 * function errorCallback() {
250 * alert("Failed to get log level");
251 * }
252 */
253 this.getLogLevel = function(successCallback, errorCallback) {
254 exec(successCallback, errorCallback, "Logging", "getLogLevel",[]);
255 }
256
257 /**
258 * Upload a log file, with log entries, to SAP Mobile Platform server.<br>
259 * This function uploads a log file, which is helpful for collecting logging data from the app to trace bugs and issues.
260 * It uploads a log file, which contains log entries based on log level.
261 * Developers can access the log data in the Management Cockpit and/or a specific folder in installed server directly.<br><br>
262 *
263 * On iOS, the uploaded log messages are filtered by the log level at upon upload.
264 * For example, when you upload a log file with an ERROR log level, the uploaded log messages contain only ERROR log level messages.
265 * When you upload log files with an INFO level, uploaded log messages contain ERROR, WARN, and INFO log level messages.
266 *
267 * <br><br>
268 * On Android, generated log messages are filtered "at the log level."
269 * In other words, the already generated and filtered log messages at another log level are not affected by the current log level.
270 * Log messages are not filtered upon upload. For example, if you set the log level to DEBUG log messages are filtered at four levels (DEBUG, INFO, WARN, and ERROR.
271 * Logger on Android has four log levels messages. So, if you set the log level to WARN and upload a log file, the log file has four log level messages that were already generated at the DEBUG level.
272 *
273 * @memberof sap.Logger
274 * @method upload
275 * @param {function} successCallback Callback function called when a log file is successfully uploaded to the server.
276 * When a log file is successfully uploaded, it is fired. (with http statusCode and statusMessage for success)
277 * @param {function} errorCallback Callback function called when an error occurs while uploading a log file to the server.
278 * If there is a connectivity error, such as an HTTP error, or unknown server error,
279 * it is fired with http statusCode and statusMessage for error.
280 * @public
281 * @memberof sap.Logger
282 * @example
283 * sap.Logger.upload(successCallback, errorCallback);
284 *
285 * function successCallback() {
286 * alert("Upload Successful");
287 * }
288 *
289 * function errorCallback(e) {
290 * alert("Upload Failed. Status: " + e.statusCode + ", Message: " + e.statusMessage);
291 * }
292 */
293 this.upload = function (successCallback, errorCallback) {
294 sap.Logon.unlock(function (connectionInfo) {
295 //Add application ID required for REST call
296 connectionInfo.applicationId = sap.Logon.applicationId;
297
298 exec(successCallback, errorCallback, "Logging", "uploadLog", [connectionInfo]);
299 }, function () {
300 errorCallback({statusCode : 0, statusMessage : "Logon failed"});
301 });
302 }
303 }
304
305 /**
306 * Constant variable for Error log level. It contains "ERROR" string.
307 * @memberof sap.Logger
308 * @constant
309 * @type String
310 * @example
311 * sap.Logger.setLogLevel(sap.Logger.ERROR);
312 */
313 Logger.prototype.ERROR = "ERROR";
314
315 /**
316 * Constant variable for Warning log level. It contains "WARN" string.
317 * @memberof sap.Logger
318 * @constant
319 * @type String
320 * @example
321 * sap.Logger.setLogLevel(sap.Logger.WARN);
322 */
323 Logger.prototype.WARN = "WARN";
324
325 /**
326 * Constant variable for Information log level. It contains "INFO" string.
327 * @memberof sap.Logger
328 * @constant
329 * @type String
330 * @example
331 * sap.Logger.setLogLevel(sap.Logger.INFO);
332 */
333 Logger.prototype.INFO = "INFO";
334
335 /**
336 * Constant variable for Debug log level. It contains "DEBUG" string.
337 * @memberof sap.Logger
338 * @constant
339 * @type String
340 * @example
341 * sap.Logger.setLogLevel(sap.Logger.DEBUG);
342 */
343 Logger.prototype.DEBUG = "DEBUG";
344
345 module.exports = new Logger();
346