/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Java Diagnostic API
*
*/


#ifndef JAVADIAGNOSTIC_H
#define JAVADIAGNOSTIC_H

#include <e32cmn.h>

namespace java
{
namespace debug
{

/**
* DiagnosticListener will be called when Java Runtime outputs to standard out
* or makes log message.
*
* DiagnosticListener may not perform any long lasting or blocking tasks
* in the callback.
*
* Example below illustrates how Java Runtime outputs could be logged to file.
*
* @code
* class LoggingListener : public DiagnosticListener
* {
* public:
*     virtual void systemOut(const TDesC8& aData) { flog(aData); };
*     virtual void systemErr(const TDesC8& aData) { flog(aData); };
*     virtual void log(const TDesC8& aData) { flog(aData); };
* protected:
*     virtual void flog(const TDesC8& aData) {
*         RFileLogger::Write(KLogDirectory, KLogFileName, EFileLoggingModeAppendRaw, aData);
*     };
* }
*
* LoggingListener listener;
* JavaDiagnostic* jd = JavaDiagnostic::createInstance();
* jd->setDiagnosticListener(listener);
* ...
* jd->removeDiagnosticListener();
* delete jd;
* @endcode
*/
class DiagnosticListener
{
public:
    /**
     * Called when Java Runtime writes to the standard output stream
     * @param[in] aText may contain multiple lines of data
     */
    virtual void systemOut(const TDesC8& aText) = 0;

    /**
     * Called when Java Runtime writes to the standard error stream
     * @param[in] aText may contain multiple lines of data
     */
    virtual void systemErr(const TDesC8& aText) = 0;

    /**
     * Called when Java Runtime makes log writing
     * @param[in] aText may contain multiple lines of data ending with newline
     */
    virtual void log(const TDesC8& aText) = 0;
};


/**
* Java Diagnostic can be used to monitor Java Runtime standard outs and
* log messages.
*
* DiagnosticListener should be set before making any Java Debug API operation,
* like installing or starting Java application, to ensure that all output
* is captured.
*
* There can be only one running Java Diagnostic instance in the system, i.e.
* instance with set listener.
*
* @code
* JavaDiagnostic* jd = JavaDiagnostic::createInstance();
* jd->setDiagnosticListener(listener);
* ...
* jd->removeDiagnosticListener();
* delete jd;
* @endcode
*
* @lib javadebugapi.lib
* @since S60 v9.2
*/
class JavaDiagnostic
{
public:
    virtual ~JavaDiagnostic() {};

    /**
     * Factory method for JavaDiagnostic.
     * Returned pointer must be deleted once done using it.
     * @return new JavaDiagnostic object
     */
    IMPORT_C static JavaDiagnostic* createInstance();

    /**
     * Sets listener and starts monitoring Java Runtime standard outs and log
     * messages. There can be only one running JavaDiagnostic instance in
     * the system.
     * @param[in] aListener will be called when Java Runtime outputs to standard out
     *                      or makes log message
     * @return KErrNone if listener was set and monitoring was started succesfully
     * @return KErrAlreadyExists if JavaDiagnostic is already running or setDiagnosticListener
     *              is called twice without removing listener in between
     */
    virtual TInt setDiagnosticListener(DiagnosticListener& aListener) = 0;

    /**
     * Removes listener and stops monitoring Java Runtime standard outs and
     * log messages.
     */
    virtual void removeDiagnosticListener() = 0;
};

} // end namespace debug
} // end namespace java

#endif // JAVADIAGNOSTIC_H