001package hm.binkley.lombok;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.Retention;
005import java.lang.annotation.Target;
006import java.util.Formatter;
007
008import static java.lang.annotation.ElementType.CONSTRUCTOR;
009import static java.lang.annotation.ElementType.METHOD;
010import static java.lang.annotation.RetentionPolicy.SOURCE;
011
012/**
013 * {@code ThreadNamed} sets the thread name during method or constructor
014 * execution, restoring it when the method or constructor completes (normally or
015 * exceptionally).
016 *
017 * @author <a href="mailto:binkley@alumni.rice.edu">B. K. Oxley (binkley)</a>
018 * @todo Eclipse handler
019 */
020@Documented
021@Retention(SOURCE)
022@Target({CONSTRUCTOR, METHOD})
023public @interface ThreadNamed {
024    /**
025     * The name for the thread while the annotated method or constructor
026     * executes.  {@code value} is treated as a formatted string for {@link
027     * String#format(String, Object...)} with any method or constructor
028     * parameters passed in as formatting args.  Use <em>positional
029     * notation</em> to skip parameters, or they may be ignroed entirely in
030     * which case {@code value} is treated as a plain string.
031     * <p>
032     * Example with formatting: <pre>
033     * &64;ThreadNamed("Foo #%2$s")
034     * public void doFoo(final String name, final int slot, final Object data) {
035     *     // Do something interesting with method parameters
036     * }</pre> when called with {@code "apple", 2, 3.14159} will set the current
037     * thread name to
038     * "Foo #2" while {@code doFoo} executes.
039     *
040     * @see Formatter
041     */
042    String value();
043}