uk.autores.Messages Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of annotations Show documentation
Annotation driven library for handling embedded resources
There is a newer version: 11.0.35-beta
// Copyright 2024 https://github.com/autores-uk/autores/blob/main/LICENSE.txt
// SPDX-License-Identifier: Apache-2.0
package uk.autores;

import uk.autores.handling.GenerateMessagesFromProperties;
import uk.autores.naming.IdiomaticNamer;
import uk.autores.repeat.RepeatableMessages;

import java.lang.annotation.*;

/**
 * Annotation for {@link GenerateMessagesFromProperties}.
 *
 * 
 *     // EXAMPLE ANNOTATION
 *     // planets.properties
 *     //   planet-event=At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.
 *     // planets_de.properties
 *     //   planet-event=Am {1,time} um {1,date} Uhr gab es {2} auf Planet {0,number,integer}.
 *     @Messages("planets.properties")
 * 
 * 
 *     // EXAMPLE CODE
 *     var time = ZonedDateTime.now();
 *     String event = Planets.planetEvent(locale, 4, time, "an attack");
 * 
 *
 * 
 *     See Backing a {@link java.util.ResourceBundle} with Properties Files for more information on localization.
 * 
 * 
 *     This annotation is strict by default.
 *     This helps build systems detect missing translations and bugs in translated format strings.
 *     However, developers are likely add or modify strings during development before translations are available.
 *     The {@link #missingKey()} and {@link #incompatibleFormat()} properties can be set to {@link Severity#WARN}
 *     or {@link Severity#IGNORE} during development to avoid breaking builds.
 *     Create a single {@code static final Severity} variable and reference it in annotations to control this globally.
 *     Set these to {@link Severity#ERROR} prior to release and/or in a "smoke test" branch.
 * 
 */
@Target({ElementType.PACKAGE, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
@Repeatable(RepeatableMessages.class)
public @interface Messages {
    /**
     * Resource files.
     * @return resources
     */
    String[] value() default {};

    /**
     * Common processing instructions.
     * @return instruction annotation
     */
    Processing processing() default @Processing(namer = IdiomaticNamer.class);

    /**
     * Generated code visibility.
     *
     * @return visibility
     */
    boolean isPublic() default false;

    /**
     * Search for localized properties.
     *
     * @return whether to localize
     */
    boolean localize() default true;

    /**
     * Generate format signatures.
     *
     * @return whether to format
     */
    boolean format() default true;

    /**
     * How to handle missing keys in localized files.
     * Only applies when {@link #localize()} is true.
     *
     * @return error severity
     */
    Severity missingKey() default Severity.ERROR;

    /**
     * How to handle incompatible format string in localized files.
     * Only applies when {@link #format()} is true.
     *
     * @return error severity
     */
    Severity incompatibleFormat() default Severity.ERROR;
}