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:

StructureSynchronizer

Constructor Summary

Constructors

Constructor and Description
SyncLogger(Logger logger, SyncInstance sync, StructureManager structureManager, RowManager rowManager, boolean auto)

Method Summary

Modifier and Type	Method and Description
StringBuilder	appendForest(Forest forest, StringBuilder sb)
StringBuilder	appendIssue(Long issueId, StringBuilder sb) Adds debug information about an issue by ID.
StringBuilder	appendItem(ItemIdentity itemId, StringBuilder sb)
StringBuilder	appendItem(long rowId, StringBuilder sb)
StringBuilder	appendItemForest(ItemForest itemForest, StringBuilder sb)
StringBuilder	appendRows(LongIterable rowIds, StringBuilder sb)
String	createLogMessage(Object... msgs)
void	debug(Object... msgs)
void	debugException(Throwable ex, Object... msgs)
String	defaultPrefix()
void	error(Object... msgs)
void	errorException(Throwable e, Object... msgs)
String	forest(Forest forest)
static SyncLogger	get() Retrieves SyncLogger from the thread-local storage.
Logger	getLogger()
String	getPrefix()
void	info(Object... msgs)
void	infoException(Throwable e, Object... msgs)
boolean	isAutoSync()
static boolean	isDebug()
boolean	isDebugEnabled()
static boolean	isInfo()
boolean	isInfoEnabled()
boolean	isOneTimeSync()
String	issue(Issue issue)
String	issue(Long issueId) Retrieves debug information about an issue by ID.
String	issues(Iterable<? extends Issue> issues)
String	issues(LongIterable issues)
String	itemForest(ItemForest itemForest)
void	popPrefix()
void	pushPrefix(String prefixToAppend)
String	row(long rowId)
String	rows(LongIterable rowIds)
Object	selectBySyncMode(Object ifAuto, Object ifResync, Object ifOneTime)
static void	set(SyncLogger syncLog) This is internal method that is used by the synchronization subsystem.
void	setLogger(Logger logger)
void	setPrefix(String prefix)
String	structure(long structureId)
String	username()
void	warn(Object... msgs)
void	warnException(Throwable ex, Object... msgs)
void	warnExceptionIfDebug(Throwable ex, Object... msgs)
String	warnStructureException(StructureException e) Contains standard error descriptions for common StructureExceptions

Methods inherited from class Object

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

Constructor Detail

SyncLogger

public SyncLogger(Logger logger,
                  @Nullable
                  SyncInstance sync,
                  StructureManager structureManager,
                  RowManager rowManager,
                  boolean auto)

Method Detail

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)