package nxm.sys.inc;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import nxm.sys.lib.LogUtilities;

/** This annotation marks a class that is unable to use the methods in {@link LogUtilities}
 *  since {@link LogUtilities} depends on it in a way that would create a race-condition or
 *  circular-reference. Any classes so marked will need to manually define their own log
 *  instance using a construct such as...
 *  <pre>
 *    private static final Logger LOG = Logger.getLogger(MyClass.class.getName());
 *  </pre>
 *  ...and then log using it rather than the methods in {@link LogUtilities}. It is considered
 *  a usage error (though not compiler-enforced) for a class other {@link LogUtilities} that is
 *  marked with this annotation to do any of the following:
 *  <pre>
 *    - Import or otherwise use any of the static methods from {@link LogUtilities}
 *    - Extend any type that imports or otherwise uses any of the static methods
 *      from {@link LogUtilities}
 *  </pre>
 *  @author  J. Czechowski
 *  @since   NeXtMidas 3.9.0
 */
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface SpecialLoggingRequired {
  // Done
}
