Package com._1c.g5.v8.dt.common

Class EnhancedMultiStatus

java.lang.Object
org.eclipse.core.runtime.Status
org.eclipse.core.runtime.MultiStatus
com._1c.g5.v8.dt.common.EnhancedMultiStatus
All Implemented Interfaces:
org.eclipse.core.runtime.IStatus
Direct Known Subclasses:
ExternalMergeToolExecutionStatus, ImportFileStatus, PresetMessageValidationResults, ValidationResults, ValidationResults
public class EnhancedMultiStatus extends org.eclipse.core.runtime.MultiStatus
Enhanced alternative that is to be used instead of MultiStatus.

The reason to replace MultiStatus is the fact that most code that deals with IStatus is not prepared to deal with MultiStatus. Specifically, code usually disregards IStatus.getChildren() and instead just grabs useful information from IStatus.getMessage() and IStatus.getException(). However, with MultiStatus both Status.getMessage() and Status.getException() are problematic:
  • The problem with Status.getMessage() is that it is lost when combining statuses with MultiStatus.merge(IStatus). So in many cases the original message specified during multi-status instantiation is lost. Meaning that sometimes no useful message is being specified for it. Meanwhile, MultiStatus completely ignores messages contained in child statuses.
  • The problem with Status.getException() is very much the same like with the message. However, this is even more problematic because noone ever specifies exception during multi-status instantiation. Instead, everyone adds child statuses with exceptions. But Status.getException() completely disregards exceptions in its child statuses.
As a result, the following commonly seen code works unexpectedly: 

 private void victim() {
     IStatus status = returnsMutiStatus();
     if(status.matches(IStatus.ERROR)) {
         throw new Exception(
             status.getMessage(),
             status.getException());
     }
 }
When this exception is later caught and logged or shown to user, it will have no useful information neither in message, nor in cause.

Enhanced multi status tries to remedy aforementioned deficiencies. Specifically, if no exception was explicitly specified during instantiation then getException() will try to return an exception representing child statuses. Non error and cancellation statuses are ignored. If status has a message then a separate wrapper exception with this message is created and an exception from the status is provided as a cause. If status had no message then exception from the status is used. If there is neither message nor exception then such status is useless and is ignored (except for Status.CANCEL_STATUS). getException() will then return an exception that has the same message as the first extracted exception and specifies this first extracted exception as Throwable.getCause(). All other exceptions will be added as Throwable.getSuppressed() exceptions so that when exception is printed to log or console then all errors are printed as well. If there is just a single child error or cancellation status then the exception from it is returned directly without a wrapper. Throwable.getMessage() and Throwable.getLocalizedMessage() from the returned exception will provide the same message as the exception in the cause. getMessage() works very much alike: if no message was specified explicitly during instantiation (or an empty string was used) then the message from the cause (as explained previously) will be provided instead.

All this means that the common code converting IStatus to an Exception should now produce exception chain that can be processed using standard cause/suppressed JDK mechanics. If should be enough just to instantiate this class instead of MultiStatus.

  • Field Summary

    Fields inherited from class org.eclipse.core.runtime.Status

    CANCEL_STATUS, OK_STATUS

    Fields inherited from interface org.eclipse.core.runtime.IStatus

    CANCEL, ERROR, INFO, OK, WARNING

  • Constructor Summary

    Constructors
    Constructor
    Description
    EnhancedMultiStatus(Class<?> caller, int code, String message)
    Creates and returns a new multi-status object with no children.
    EnhancedMultiStatus(Class<?> caller, int code, String message, Throwable exception)
    Creates and returns a new multi-status object with no children.
    EnhancedMultiStatus(Class<?> caller, int code, org.eclipse.core.runtime.IStatus[] newChildren, String message, Throwable exception)
    Creates and returns a new multi-status object with the given children.
    EnhancedMultiStatus(String pluginId, int code, String message)
    Creates and returns a new multi-status object with no children.
    EnhancedMultiStatus(String pluginId, int code, String message, Throwable exception)
    Creates and returns a new multi-status object with no children.
    EnhancedMultiStatus(String pluginId, int code, org.eclipse.core.runtime.IStatus[] newChildren, String message, Throwable exception)
    Creates and returns a new multi-status object with the given children.

  • Method Summary

    Modifier and Type
    Method
    Description
    Throwable
    getException()
     
    String
    getMessage()
     

    Methods inherited from class org.eclipse.core.runtime.MultiStatus

    add, addAll, getChildren, isMultiStatus, merge, toString

    Methods inherited from class org.eclipse.core.runtime.Status

    error, error, getCode, getPlugin, getSeverity, info, isOK, matches, setCode, setException, setMessage, setPlugin, setSeverity, warning, warning

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • EnhancedMultiStatus

      public EnhancedMultiStatus(Class<?> caller, int code, String message)
      Creates and returns a new multi-status object with no children.
      Parameters:
      caller - the relevant class to build unique identifier from
      code - the caller-specific status code
      message - a human-readable message, localized to the current locale
      See Also:
      • MultiStatus(Class, int, String)

    • EnhancedMultiStatus

      public EnhancedMultiStatus(String pluginId, int code, String message)
      Creates and returns a new multi-status object with no children.
      Parameters:
      pluginId - the unique identifier of the relevant plug-in
      code - the plug-in-specific status code
      message - a human-readable message, localized to the current locale
      See Also:
      • MultiStatus(String, int, String)

    • EnhancedMultiStatus

      public EnhancedMultiStatus(Class<?> caller, int code, String message, Throwable exception)
      Creates and returns a new multi-status object with no children.
      Parameters:
      caller - the relevant class to build unique identifier from
      code - the caller-specific status code
      message - a human-readable message, localized to the current locale
      exception - a low-level exception, or null if not applicable
      See Also:
      • MultiStatus(Class, int, String, Throwable)

    • EnhancedMultiStatus

      public EnhancedMultiStatus(String pluginId, int code, String message, Throwable exception)
      Creates and returns a new multi-status object with no children.
      Parameters:
      pluginId - the unique identifier of the relevant plug-in
      code - the plug-in-specific status code
      message - a human-readable message, localized to the current locale
      exception - a low-level exception, or null if not applicable
      See Also:
      • MultiStatus(String, int, String, Throwable)

    • EnhancedMultiStatus

      public EnhancedMultiStatus(Class<?> caller, int code, org.eclipse.core.runtime.IStatus[] newChildren, String message, Throwable exception)
      Creates and returns a new multi-status object with the given children.
      Parameters:
      caller - the relevant class to build unique identifier from
      code - the caller-specific status code
      newChildren - the list of children status objects
      message - a human-readable message, localized to the current locale
      exception - a low-level exception, or null if not applicable
      See Also:
      • MultiStatus(Class, int, IStatus[], String, Throwable)

    • EnhancedMultiStatus

      public EnhancedMultiStatus(String pluginId, int code, org.eclipse.core.runtime.IStatus[] newChildren, String message, Throwable exception)
      Creates and returns a new multi-status object with the given children.
      Parameters:
      pluginId - the unique identifier of the relevant plug-in
      code - the plug-in-specific status code
      newChildren - the list of children status objects
      message - a human-readable message, localized to the current locale
      exception - a low-level exception, or null if not applicable
      See Also:
      • MultiStatus(String, int, IStatus[], String, Throwable)

  • Method Details

    • getException

      public Throwable getException()
      Specified by:
      getException in interface org.eclipse.core.runtime.IStatus
      Overrides:
      getException in class org.eclipse.core.runtime.Status

    • getMessage

      public String getMessage()
      Specified by:
      getMessage in interface org.eclipse.core.runtime.IStatus
      Overrides:
      getMessage in class org.eclipse.core.runtime.Status