Package com.almworks.jira.structure.api.sync.util

Class SyncLogger

Object
SyncLogger
@NotThreadSafe public class SyncLogger extends Object
This is a utility class to log messages from synchronizer implementations. It prepends the specified messages with the following information:
  • name of the synchronizer taken from its configuration in the set up in the <structure-synchronizer> module (see SynchronizerDescriptor.getLabel(),
  • mode of synchronization (one-time synchronization, periodical autosync, or resync),
  • name and ID of the structure being synchronized,
  • ID of the synchronizer instance.

Name of the user under which the synchronization is run is not provided, as it is automatically inserted into the log message by JIRA.

Features

There is a bunch of helper methods to pretty-print the user under which the synchronizer runs (username()), produce warnings about typical StructureExceptions that may be encountered by synchronizers (warnStructureException(StructureException)), and select messages based on the synchronization mode (selectBySyncMode(Object, Object, Object)).

All logging methods that take Object... vararg parameter delimit its contents putting a single space before the parameter. If the parameter is a character or a single-character String that is a punctuation mark, the space is not inserted before the parameter. If the parameter is an Object[], its contents are added to the output as if they belonged to the original Object... parameter.

Example:

SyncLogger log = ... ; log.warn("cannot run because of", isKaboozle() ? "kaboozle" : new Object[]{"grumbles with error", getError()}, ':', getCause())

will produce the following log message:

<synchronizer label> autosync #239 for structure 'Unresolved in 2.0' (#156) cannot run because of grumbles with error FATAL: something went wrong

Methods that end with exceptionIfDebug attempt to log exception stack trace if log level is DEBUG or lower and print only exception message if log level is higher.

Since:
7.2.0 (Structure 2.0)
See Also:

  • Constructor Details

  • Method Details

    • get

      @NotNull public static SyncLogger get()

      Retrieves SyncLogger from the thread-local storage. Must only be called during synchronization; if called at any other time, throws an UnsupportedOperationException.

      The returned SyncLogger delegates to Logger for the current StructureSynchronizer class.

    • set

      @Internal public static void set(@Nullable SyncLogger syncLog)
      This is internal method that is used by the synchronization subsystem. Do not use this method. Call from threads other than the synchronization thread will result in UnsupportedOperationException being thrown.

    • isInfo

      public static boolean isInfo()

    • isDebug

      public static boolean isDebug()

    • getPrefix

      @NotNull public String getPrefix()

    • setPrefix

      public void setPrefix(@NotNull String prefix)

    • pushPrefix

      public void pushPrefix(@NotNull String prefixToAppend)

    • popPrefix

      public void popPrefix()

    • getLogger

      public Logger getLogger()

    • setLogger

      public void setLogger(Logger logger)

    • isOneTimeSync

      public boolean isOneTimeSync()

    • isAutoSync

      public boolean isAutoSync()

    • info

      public void info(Object... msgs)

    • infoException

      public void infoException(Throwable e, Object... msgs)

    • debug

      public void debug(Object... msgs)

    • debugException

      public void debugException(@Nullable Throwable ex, Object... msgs)

    • warn

      public void warn(Object... msgs)

    • warnException

      public void warnException(@Nullable Throwable ex, Object... msgs)

    • warnExceptionIfDebug

      public void warnExceptionIfDebug(@Nullable Throwable ex, Object... msgs)

    • error

      public void error(Object... msgs)

    • errorException

      public void errorException(@Nullable Throwable e, Object... msgs)

    • isInfoEnabled

      public boolean isInfoEnabled()

    • isDebugEnabled

      public boolean isDebugEnabled()

    • createLogMessage

      @NotNull public String createLogMessage(Object... msgs)

    • defaultPrefix

      public final String defaultPrefix()

    • username

      @NotNull public String username()

    • issue

      @NotNull public String issue(Long issueId)
      Retrieves debug information about an issue by ID. Costly method.

    • appendIssue

      public StringBuilder appendIssue(Long issueId, StringBuilder sb)
      Adds debug information about an issue by ID. Costly method.

    • issue

      @NotNull public String issue(@Nullable Issue issue)

    • issues

      @NotNull public String issues(@Nullable Iterable<? extends Issue> issues)

    • issues

      public String issues(@Nullable LongIterable issues)

    • structure

      @NotNull public String structure(long structureId)

    • selectBySyncMode

      public Object selectBySyncMode(Object ifAuto, Object ifResync, Object ifOneTime)

    • appendForest

      public StringBuilder appendForest(Forest forest, StringBuilder sb)

    • forest

      public String forest(Forest forest)

    • appendItemForest

      public StringBuilder appendItemForest(ItemForest itemForest, StringBuilder sb)

    • itemForest

      public String itemForest(ItemForest itemForest)

    • appendRows

      public StringBuilder appendRows(LongIterable rowIds, StringBuilder sb)

    • appendItem

      public StringBuilder appendItem(long rowId, StringBuilder sb)

    • appendItem

      public StringBuilder appendItem(ItemIdentity itemId, StringBuilder sb)

    • row

      public String row(long rowId)

    • rows

      public String rows(LongIterable rowIds)

    • warnStructureException

      @Nullable public String warnStructureException(StructureException e)
      Contains standard error descriptions for common StructureExceptions
      Returns:
      a specific string if the exception represents a common known case, null otherwise (generic message should be used)