Org.simantics.message

org.simantics.message (SVN) is an IStatus-based (from Eclipse runtime) OSGi service for basic logging.

org.simantics.message.ui (SVN) offers a basic Workbench view UI for browsing logged messages.

Introduction

Logging is an activity where an input message is provided by a client to be consumed by the logger which stores a log entry for later viewing and use.

In this case, messages are textual and presented by the client as org.eclipse.core.runtime.IStatus instances for the message service. Log entries are stored on the local filesystem by the message logging service as specially formatted entries in text files that can be later parsed back viewable log entries. Messages do not have dynamic traits, they are static data. The static data may embed arbitrary links to other data encoded as URIs.

To perform message logging you need to:

1. Get a hold of the shared org.simantics.message.ILogger service.
2. Log a message with the ILogger.log(IStatus status) method

Fetching ILogger

There are two methods of getting a hold of the shared ILogger.

Method 1: MessageService

• Pros:
  • Very easy to use
• Cons:
  • Explicit implementation dependency on MessageService
• Usage:
  • Add dependency on org.simantics.message bundle
  • Use org.simantics.message.MessageService.getDefault()

Method 2: OSGi ServiceTracker

• Pros:
  • Imposes only interface dependencies, no implementation dependencies
  • The component-oriented way of doing it
• Cons:
  • Requires a bundle activator to properly manage the lifecycle of the service tracker.
  • Requires more code than method 1
• Usage:
  • Add dependency on org.simantics.message bundle
  • Copy parts of the following bundle activator code into your own plug-ins bundle activator:

<enscript lang=java>public class Activator implements BundleActivator {

   // The plug-in ID
   public static final String PLUGIN_ID = "org.simantics.plugin";
   private BundleContext      bundleContext;    
   private ServiceTracker     logTracker;
   /* (non-Javadoc)
    * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
    */
   public void start(BundleContext context) throws Exception {
       this.bundleContext = context;
       plugin = this;
   }
   /* (non-Javadoc)
    * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
    */
   public void stop(BundleContext context) throws Exception {
       if (logTracker != null) {
           logTracker.close();
           logTracker = null;
       }

       this.bundleContext = null;
       plugin = null;
   }
   /*
    * Return the framework log service, if available.
    */
   public ILogger getLogger() {
       if (logTracker == null) {
           logTracker = new ServiceTracker(bundleContext, ILogger.class.getName(), null);
           logTracker.open();
       }
       return (ILogger) logTracker.getService();
   }    

} </enscript>

Using ILogger

• Log a message with the ILogger.log(IStatus status) method
  • Sample code
• All kinds of data references can be added to the logged detailed description as an URI in the standard HTML anchor format

  <a href="uri">link text</a>

  • Different scheme handlers (see IMessageSchemeHandler) can be used to perform actions when a logger URI link is activated in the message viewer.
• Use these utilities to generate your hyperlinks:
  • HtmlUtil.java
  • MessageUtil.java

User Interfaces

Message logging related user interface code is located in the org.simantics.messsage.ui plug-in.

Messages View

The messages view is used for viewing the messages logged with the mechanisms specified above.

The Messages view

The tree part of the view shows the logged message hierarchy. The Message column is used for showing what is returned by IStatus.getMessage().

The description part of the messages should be shown in the bottom area of the view. It is used for showing what is returned by IDetailStatus.getDetailedDescription(). If the logged IStatus does not implement IDetailStatus, the return value of IStatus.getMessage() is shown instead. The description is shown in a normal SWT browser widget so the description should contain normal HTML. The messageview does not decorate the description with HTML tags and headers, i.e. what is logged is also directly shown. The browser widget can also link to other data using standard HTML anchor tags. The links shall be put in the href attribute and they must be encoded as URIs. All link activations in the message view browser will be intercepted and org.simantics.message.messageDataScheme extensions will be used to figure out the appropriate action in each case. See #Adding support for new data schemes for more information.

One way of adding the message view to your own perspective is to add the following perspective extension:

  <extension
        point="org.eclipse.ui.perspectiveExtensions">
     <perspectiveExtension
           targetID="your.perspective.id">
        <view
               closeable="false"
               id="org.simantics.message.view"
               minimized="true"
               ratio="0.75"
               relationship="bottom"
               relative="org.eclipse.ui.editorss"
               visible="true">
        </view>
     </perspectiveExtension>
  </extension>

Adding support for new data schemes

• The hyperlinks seen at the bottom in the messages view are deserialized using an IReferenceSerializer (Resource implementation)
• The actions taken when a user clicks on a link are decided by IMessageSchemeHandler's.
• When the user clicks a hyperlink on the messages view, it will first attempt to find a handler for the clicked link scheme. After finding one, it will deserialize the textual link into a Java object which is then passed on to the matching message handler.

• Current handler limitations:
  • Each scheme can only have one handler

Follow these steps to create new link types:

• Specify a scheme extension through the org.eclipse.message.messageDataScheme extension point for your own link type. The scheme also specifies the IReferenceSerializer for the scheme. Example:

   <extension point="org.simantics.message.messageDataScheme">
      <scheme
            id="org.simantics.message.scheme.resource"
            scheme="resource"
            serializer="org.simantics.message.ResourceReferenceSerializer">
         <description>
            A standard serializer for Simantics database resources.
         </description>
      </scheme>
   </extension>

• Specify a handler extension for your scheme through the same extension point.

   <extension point="org.simantics.message.messageDataScheme">
      <handler
            handler="org.simantics.message.ui.scheme.ResourceSchemeHandler"
            schemeId="org.simantics.message.scheme.resource">
         <description>
            A standard scheme handler for Simantics database resources that simulates a double click on the referenced resource.
         </description>
      </handler>
   </extension>

Download

Version	Date	Download	SVN
unstable	now	-	svn:foundation/message/trunk/
0.9.0	9.1.2010	svn:foundation/message/tags/0.9.0/repository/	svn:foundation/message/tags/0.9.0/

Contact

• User:Tuukka Lehtonen