| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <meta name="Author" content="Build"> |
| <title>Eclipse Platform Core RFC 0003 - Log File Retrieval</title> |
| </head> |
| <body bgcolor="#FFFFFF" > |
| <div align="right"> |
| <table border=0 cellspacing=0 cellpadding=2 width="100%"> |
| <tr> |
| <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF"> |
| Request For Comment |
| </font></font></b></td> |
| </tr> |
| </table> |
| </div> |
| <div align="left"> |
| <h1><img src="../images/idea.gif" width="120" height="86"></h1> |
| </div> |
| <h1 align="CENTER">Eclipse Platform Core RFC 0003</h1> |
| <h1 align="CENTER">Log File Retrieval</h1> |
| <blockquote> |
| <p><b>Summary</b> <br> |
| There is a requirement to make available programatically the information that has |
| been written to the platform log file. |
| This RFC describes the proposed approach, which involves adding a new API method |
| for obtaining the log file location, and changing the log file format to XML. |
| <p><b> By John Arthorne, OTI.</b> <br> |
| <font size="-1">Created: 28-NOV-2001.</font> <br> |
| <font size="-1">Modified 3-JAN-2002. Removed API method for log retrieval.</font> <br> |
| <font size="-1">Modified 5-DEC-2001. Sample log file added.</font> <br> |
| </blockquote> |
| <hr> |
| <h2>The Problem</h2> |
| <p> |
| Currently, the only way to programatically access the platform log is by adding a listener by calling |
| <code>Platform.addLogListener(ILogListener)</code>. While this approach has many benefits, |
| there are also some drawbacks: |
| <ul> |
| <li>If errors or warnings occur during platform startup, before listeners can be added, it is impossible |
| to programatically obtain information about these errors. It is even impossible to detect if startup |
| errors have occurred.</li> |
| <li>A listener has no access to errors that have been logged before that listener was activated. |
| Since plug-ins cannot control when they are started, they may miss logged information that is |
| interesting to them.</li> |
| <li>Each listener that wants to maintain a representation of what has been logged must |
| keep their own list. This leads to a duplication of the information available in the log file on disk.</li> |
| </ul> |
| </p> |
| <h2>The Solution</h2> |
| <p> |
| The proposed solution is to add an API method to org.eclipse.core.runtime.Platform that returns |
| the location of the log file, and to make the log file an XML file with a known DTD. With a well known |
| log file name and format, third parties can use Xerces to scan or parse the log file to retrieve |
| the information they are interested in. The proposed API method is: |
| <pre> |
| /** |
| * Returns the location of the platform log file. This file may contain information |
| * about errors that have previously occurred during this invocation of the Platform. |
| * @return the path of the log file on disk. |
| */ |
| IPath getLogFileLocation(); |
| </pre> |
| <p> |
| The proposed document type definition for the log file is provided below. This format will be |
| considered API. |
| </p> |
| <p> |
| <!ELEMENT log (entry)*> |
| <br> |
| <br><!ELEMENT entry (status)> |
| <br><!ATTLIST entry |
| <br> date CDATA #REQUIRED> |
| <ul> |
| <li><b>date -</b> the date this entry was logged, in the default java date format.</li> |
| </ul> |
| <br><!ELEMENT status (status)* (exception)?> |
| <br><!ATTLIST status |
| <br> sev (ERROR | INFO | OK | WARNING) #REQUIRED |
| <br> id CDATA #REQUIRED |
| <br> code CDATA #REQUIRED |
| <br> msg CDATA #REQUIRED> |
| <ul> |
| <li><b>sev -</b> the problem severity.</li> |
| <li><b>id -</b> the ID of the plug-in in which the error occurred.</li> |
| <li><b>code -</b> the error code, an integer value that generally has some meaning |
| for the plug-in that generated the error. See <tt>org.eclipse.core.runtime.IStatus#getCode</tt>.</li> |
| <li><b>msg -</b> the status message, describing the error that occurred.</li> |
| </ul> |
| <br><!ELEMENT exception (exception)? > |
| <br><!ATTLIST exception |
| <br> msg CDATA #REQUIRED |
| <br> trace CDATA #REQUIRED> |
| <ul> |
| <li><b>msg -</b> the message associated with some <tt>java.lang.Throwable</tt> object.</li> |
| <li><b>trace -</b> a stack trace provided by <tt>java.lang.Throwable#printStackTrace</tt>.</li> |
| </ul> |
| </p> |
| <p> |
| The log file would remain at its present location, and its name would remain the same (.log). |
| Here is a <A HREF="sample.txt">sample log file</A> in the new XML format. |
| </p> |
| <h2>RFC Status</h2> |
| <p>This proposal has been accepted, implemented, and released in build 20020409. |
| </p> |
| </body> |
| </html> |
