1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Java Diagnostic API

    15 *

    16 */

    17 

    18 

    19 #ifndef JAVADIAGNOSTIC_H

    20 #define JAVADIAGNOSTIC_H

    21 

    22 #include <e32cmn.h>

    23 

    24 namespace java

    25 {

    26 namespace debug

    27 {

    28 

    29 /**

    30 * DiagnosticListener will be called when Java Runtime outputs to standard out

    31 * or makes log message.

    32 *

    33 * DiagnosticListener may not perform any long lasting or blocking tasks

    34 * in the callback.

    35 *

    36 * Example below illustrates how Java Runtime outputs could be logged to file.

    37 *

    38 * @code

    39 * class LoggingListener : public DiagnosticListener

    40 * {

    41 * public:

    42 *     virtual void systemOut(const TDesC8& aData) { flog(aData); };

    43 *     virtual void systemErr(const TDesC8& aData) { flog(aData); };

    44 *     virtual void log(const TDesC8& aData) { flog(aData); };

    45 * protected:

    46 *     virtual void flog(const TDesC8& aData) {

    47 *         RFileLogger::Write(KLogDirectory, KLogFileName, EFileLoggingModeAppendRaw, aData);

    48 *     };

    49 * }

    50 *

    51 * LoggingListener listener;

    52 * JavaDiagnostic* jd = JavaDiagnostic::createInstance();

    53 * jd->setDiagnosticListener(listener);

    54 * ...

    55 * jd->removeDiagnosticListener();

    56 * delete jd;

    57 * @endcode

    58 */

    59 class DiagnosticListener

    60 {

    61 public:

    62     /**

    63      * Called when Java Runtime writes to the standard output stream

    64      * @param[in] aText may contain multiple lines of data

    65      */

    66     virtual void systemOut(const TDesC8& aText) = 0;

    67 

    68     /**

    69      * Called when Java Runtime writes to the standard error stream

    70      * @param[in] aText may contain multiple lines of data

    71      */

    72     virtual void systemErr(const TDesC8& aText) = 0;

    73 

    74     /**

    75      * Called when Java Runtime makes log writing

    76      * @param[in] aText may contain multiple lines of data ending with newline

    77      */

    78     virtual void log(const TDesC8& aText) = 0;

    79 };

    80 

    81 

    82 /**

    83 * Java Diagnostic can be used to monitor Java Runtime standard outs and

    84 * log messages.

    85 *

    86 * DiagnosticListener should be set before making any Java Debug API operation,

    87 * like installing or starting Java application, to ensure that all output

    88 * is captured.

    89 *

    90 * There can be only one running Java Diagnostic instance in the system, i.e.

    91 * instance with set listener.

    92 *

    93 * @code

    94 * JavaDiagnostic* jd = JavaDiagnostic::createInstance();

    95 * jd->setDiagnosticListener(listener);

    96 * ...

    97 * jd->removeDiagnosticListener();

    98 * delete jd;

    99 * @endcode

   100 *

   101 * @lib javadebugapi.lib

   102 * @since S60 v9.2

   103 */

   104 class JavaDiagnostic

   105 {

   106 public:

   107     virtual ~JavaDiagnostic() {};

   108 

   109     /**

   110      * Factory method for JavaDiagnostic.

   111      * Returned pointer must be deleted once done using it.

   112      * @return new JavaDiagnostic object

   113      */

   114     IMPORT_C static JavaDiagnostic* createInstance();

   115 

   116     /**

   117      * Sets listener and starts monitoring Java Runtime standard outs and log

   118      * messages. There can be only one running JavaDiagnostic instance in

   119      * the system.

   120      * @param[in] aListener will be called when Java Runtime outputs to standard out

   121      *                      or makes log message

   122      * @return KErrNone if listener was set and monitoring was started succesfully

   123      * @return KErrAlreadyExists if JavaDiagnostic is already running or setDiagnosticListener

   124      *              is called twice without removing listener in between

   125      */

   126     virtual TInt setDiagnosticListener(DiagnosticListener& aListener) = 0;

   127 

   128     /**

   129      * Removes listener and stops monitoring Java Runtime standard outs and

   130      * log messages.

   131      */

   132     virtual void removeDiagnosticListener() = 0;

   133 };

   134 

   135 } // end namespace debug

   136 } // end namespace java

   137 

   138 #endif // JAVADIAGNOSTIC_H