docs/manual/propkey-checker.tex - typetools/checker-framework - Git at Google

 \htmlhr
 \chapterAndLabel{Property File Checker}{propkey-checker}

 The Property File Checker ensures that a property file or resource bundle (both
 of which act like maps from keys to values) is only accessed with valid keys.
 Accesses without a valid key either return \code{null} or a default value, which
 can lead to a \code{NullPointerException} or hard-to-trace behavior.
 The Property File Checker (Section \refwithpage{genpropkey-checker}) ensures
 that the used keys are found in the corresponding property file or resource
 bundle.

 We also provide two specialized checkers.
 An Internationalization Checker (Section \refwithpage{i18n-checker})
 verifies that code is properly internationalized.
 A Compiler Message Key Checker (Section \refwithpage{compilermsgs-checker})
 verifies that compiler message keys used in the Checker Framework are
 declared in a property file.
 This is an example of a simple specialization of the property
 file checker, and the Checker Framework source code shows how it is used.

 It is easy to customize the property key checker for other related purposes.
 Take a look at the source code of the Compiler Message Key Checker and adapt it for
 your purposes.


 \sectionAndLabel{General Property File Checker}{genpropkey-checker}

 The general Property File Checker ensures that a resource key is located
 in a specified property file or resource bundle.


 The annotation \refqualclass{checker/propkey/qual}{PropertyKey}
 indicates that the qualified \code{CharSequence} is a valid key
 found in the property file or resource bundle.
 You do not need to annotate \code{String} literals.
 The checker looks up every \code{String} literal in the specified
 property file or resource bundle, and adds annotations as appropriate.

 If you pass a \code{CharSequence} (including \<String>) variable to be
 eventually used as a key, you
 also need to annotate all these variables with \code{@PropertyKey}.


 The checker can be invoked by running the following
 command:

 \begin{Verbatim}
   javac -processor org.checkerframework.checker.propkey.PropertyKeyChecker
         -Abundlenames=MyResource MyFile.java ...
 \end{Verbatim}

 You must specify the resources, which map keys to strings.
 The checker supports two types of resource:
 resource bundles and property files.  You can specify one or both of the
 following two command-line options:

 \begin{enumerate}

 \item \code{-Abundlenames=\emph{resource\_name}}

   \emph{resource\_name} is the name of the resource to be used with
   \sunjavadoc{java.base/java/util/ResourceBundle.html\#getBundle(java.lang.String,java.util.Locale,java.lang.ClassLoader)}{ResourceBundle.getBundle()}.
   The checker uses the default \code{Locale} and \code{ClassLoader} in the
   compilation system.
   (For a tutorial about \code{ResourceBundle}s, see
   \myurl{https://docs.oracle.com/javase/tutorial/i18n/resbundle/concept.html}.)
   % WAS:  http://java.sun.com/developer/technicalArticles/Intl/ResourceBundles/
   % https://docs.oracle.com/javase/tutorial/ui/features/i18n.html is not what
   % I am looking for to replace it.
   Multiple resource bundle names are separated by colons '\code{:}'.

 \item \code{-Apropfiles=\emph{prop\_file}}

   \emph{prop\_file} is the name of a properties file that maps
   keys to values.  The file format is described in
   the Javadoc for
   \sunjavadoc{java.base/java/util/Properties.html\#load(java.io.Reader)}{Properties.load()}.
   Multiple files are separated by colons '\code{:}'.

 \end{enumerate}


 \sectionAndLabel{Internationalization Checker (I18n Checker)}{i18n-checker}

 The Internationalization Checker, or I18n Checker, verifies that your code is properly
 internationalized.  Internationalization is the process of designing software so that
 it can be adapted to different languages and locales without needing to change the code.
 Localization is the process of adapting internationalized software to specific languages
 and locales.

 Internationalization is sometimes called i18n, because the word starts with ``i'',
 ends with ``n'', and has 18 characters in between.  Localization is similarly
 sometimes abbreviated as l10n.

 The checker focuses on one aspect of internationalization:  user-visible text
 should be presented in the user's own language, such as English, French, or
 German.  This is achieved by looking up keys in a localization resource,
 which maps keys to user-visible text.  For instance, one version of a
 resource might map \code{"CANCEL\_STRING"} to
 \code{"Cancel"}, and another version of the same resource might map
 \code{"CANCEL\_STRING"} to \code{"Abbrechen"}.

 There are other aspects to localization, such as formatting of dates (3/5
 vs.~5/3 for March 5), that the checker does not check.

 The Internationalization Checker verifies these two properties:

 \begin{enumerate}

 \item
   Any user-visible text should be obtained from a localization resource.
   For example, \code{String} literals should not be output to the user.

 \item
   When looking up keys in a localization resource, the key should exist in
   that resource.  This check catches incorrect or misspelled localization
   keys.

 \end{enumerate}

 If you use the Internationalization Checker, you may want to also use the
 Internationalization Format String Checker, or I18n Format String Checker
 (Chapter~\ref{i18n-formatter-checker}).
 It verifies that internationalization format strings are well-formed and
 used with arguments of the proper type, so that
 \sunjavadoc{java.base/java/text/MessageFormat.html\#format(java.lang.String,java.lang.Object...)}{MessageFormat.format}
 does not fail at run time.

 \subsectionAndLabel{Internationalization annotations}{i18n-annotations}

 The Internationalization Checker supports two annotations:

 \begin{description}
 \item[\refqualclass{checker/i18n/qual}{Localized}]
 indicates that the qualified
 \code{CharSequence} is a message that has been localized and/or formatted with
 respect to the used locale.

 \item[\refqualclass{checker/i18n/qual}{LocalizableKey}]
 indicates that the
 qualified \code{CharSequence} or \code{Object} is a valid key found in the
 localization resource.
 This annotation is a specialization of the \code{@PropertyKey} annotation, that
 gets checked by the general Property Key Checker.
 \end{description}

 You may need to add the \code{@Localized} annotation to more methods in the
 JDK or other libraries, or in your own code.


 \subsectionAndLabel{Running the Internationalization Checker}{i18n-running}

 The Internationalization Checker can be invoked by running the following
 command:

 %BEGIN LATEX
 \begin{smaller}
 %END LATEX
 \begin{Verbatim}
   javac -processor org.checkerframework.checker.i18n.I18nChecker -Abundlenames=MyResource MyFile.java ...
 \end{Verbatim}
 %BEGIN LATEX
 \end{smaller}
 %END LATEX

 You must specify the localization resource, which maps keys to user-visible
 text.  Like the general Property Key Checker, the Internationalization Checker
 supports two types of localization resource:
 \code{ResourceBundle}s using the
 \code{-Abundlenames=\emph{resource\_name}} option
 or property files using the
 \code{-Apropfiles=\emph{prop\_file}} option.


 \sectionAndLabel{Compiler Message Key Checker}{compilermsgs-checker}

 The Checker Framework uses compiler message keys to output error messages.
 These keys are substituted by localized strings for user-visible error messages.
 Using keys instead of the localized strings in the source code enables easier
 testing, as the expected message keys can stay unchanged while the localized
 strings can still be modified.
 We use the Compiler Message Key Checker to ensure that all internal
 keys are correctly localized.
 Instead of using the Property File Checker, we use a specialized checker,
 giving us more precise documentation of the intended use of \code{String}s.

 The single annotation used by this checker is
 \refqualclass{checker/compilermsgs/qual}{CompilerMessageKey}.
 The Checker Framework is completely annotated;
 for example, class \code{org.checkerframework.framework.source.Result}
 uses \code{@CompilerMessageKey} in methods \code{failure} and \code{warning}.
 For most users of the Checker Framework there will be no need to annotate any
 \code{String}s, as the checker looks up all \code{String} literals and adds
 annotations as appropriate.

 The Compiler Message Key Checker can be invoked by running the following
 command:

 \begin{Verbatim}
   javac -processor org.checkerframework.checker.compilermsgs.CompilerMessagesChecker
         -Apropfiles=messages.properties MyFile.java ...
 \end{Verbatim}

 You must specify the resource, which maps compiler message keys to user-visible
 text.  The checker supports the same options as the general property key checker.
 Within the Checker Framework we only use property files,
 so the \code{-Apropfiles=\emph{prop\_file}} option should be used.

 % LocalWords:  NullPointerException genpropkey compilermsgs propkey PropertyKey
 % LocalWords:  Abundlenames getBundle ResourceBundle ClassLoader Apropfiles
 % LocalWords:  Abbrechen LocalizableKey CompilerMessageKey java I18n i18n
 %  LocalWords:  l10n
	\htmlhr
	\chapterAndLabel{Property File Checker}{propkey-checker}

	The Property File Checker ensures that a property file or resource bundle (both
	of which act like maps from keys to values) is only accessed with valid keys.
	Accesses without a valid key either return \code{null} or a default value, which
	can lead to a \code{NullPointerException} or hard-to-trace behavior.
	The Property File Checker (Section \refwithpage{genpropkey-checker}) ensures
	that the used keys are found in the corresponding property file or resource
	bundle.

	We also provide two specialized checkers.
	An Internationalization Checker (Section \refwithpage{i18n-checker})
	verifies that code is properly internationalized.
	A Compiler Message Key Checker (Section \refwithpage{compilermsgs-checker})
	verifies that compiler message keys used in the Checker Framework are
	declared in a property file.
	This is an example of a simple specialization of the property
	file checker, and the Checker Framework source code shows how it is used.

	It is easy to customize the property key checker for other related purposes.
	Take a look at the source code of the Compiler Message Key Checker and adapt it for
	your purposes.



	\sectionAndLabel{General Property File Checker}{genpropkey-checker}

	The general Property File Checker ensures that a resource key is located
	in a specified property file or resource bundle.


	The annotation \refqualclass{checker/propkey/qual}{PropertyKey}
	indicates that the qualified \code{CharSequence} is a valid key
	found in the property file or resource bundle.
	You do not need to annotate \code{String} literals.
	The checker looks up every \code{String} literal in the specified
	property file or resource bundle, and adds annotations as appropriate.

	If you pass a \code{CharSequence} (including \<String>) variable to be
	eventually used as a key, you
	also need to annotate all these variables with \code{@PropertyKey}.


	The checker can be invoked by running the following
	command:

	\begin{Verbatim}
	javac -processor org.checkerframework.checker.propkey.PropertyKeyChecker
	-Abundlenames=MyResource MyFile.java ...
	\end{Verbatim}

	You must specify the resources, which map keys to strings.
	The checker supports two types of resource:
	resource bundles and property files. You can specify one or both of the
	following two command-line options:

	\begin{enumerate}

	\item \code{-Abundlenames=\emph{resource\_name}}

	\emph{resource\_name} is the name of the resource to be used with
	\sunjavadoc{java.base/java/util/ResourceBundle.html\#getBundle(java.lang.String,java.util.Locale,java.lang.ClassLoader)}{ResourceBundle.getBundle()}.
	The checker uses the default \code{Locale} and \code{ClassLoader} in the
	compilation system.
	(For a tutorial about \code{ResourceBundle}s, see
	\myurl{https://docs.oracle.com/javase/tutorial/i18n/resbundle/concept.html}.)
	% WAS: http://java.sun.com/developer/technicalArticles/Intl/ResourceBundles/
	% https://docs.oracle.com/javase/tutorial/ui/features/i18n.html is not what
	% I am looking for to replace it.
	Multiple resource bundle names are separated by colons '\code{:}'.

	\item \code{-Apropfiles=\emph{prop\_file}}

	\emph{prop\_file} is the name of a properties file that maps
	keys to values. The file format is described in
	the Javadoc for
	\sunjavadoc{java.base/java/util/Properties.html\#load(java.io.Reader)}{Properties.load()}.
	Multiple files are separated by colons '\code{:}'.

	\end{enumerate}



	\sectionAndLabel{Internationalization Checker (I18n Checker)}{i18n-checker}

	The Internationalization Checker, or I18n Checker, verifies that your code is properly
	internationalized. Internationalization is the process of designing software so that
	it can be adapted to different languages and locales without needing to change the code.
	Localization is the process of adapting internationalized software to specific languages
	and locales.

	Internationalization is sometimes called i18n, because the word starts with ``i'',
	ends with ``n'', and has 18 characters in between. Localization is similarly
	sometimes abbreviated as l10n.

	The checker focuses on one aspect of internationalization: user-visible text
	should be presented in the user's own language, such as English, French, or
	German. This is achieved by looking up keys in a localization resource,
	which maps keys to user-visible text. For instance, one version of a
	resource might map \code{"CANCEL\_STRING"} to
	\code{"Cancel"}, and another version of the same resource might map
	\code{"CANCEL\_STRING"} to \code{"Abbrechen"}.

	There are other aspects to localization, such as formatting of dates (3/5
	vs.~5/3 for March 5), that the checker does not check.

	The Internationalization Checker verifies these two properties:

	\begin{enumerate}

	\item
	Any user-visible text should be obtained from a localization resource.
	For example, \code{String} literals should not be output to the user.

	\item
	When looking up keys in a localization resource, the key should exist in
	that resource. This check catches incorrect or misspelled localization
	keys.

	\end{enumerate}

	If you use the Internationalization Checker, you may want to also use the
	Internationalization Format String Checker, or I18n Format String Checker
	(Chapter~\ref{i18n-formatter-checker}).
	It verifies that internationalization format strings are well-formed and
	used with arguments of the proper type, so that
	\sunjavadoc{java.base/java/text/MessageFormat.html\#format(java.lang.String,java.lang.Object...)}{MessageFormat.format}
	does not fail at run time.

	\subsectionAndLabel{Internationalization annotations}{i18n-annotations}

	The Internationalization Checker supports two annotations:

	\begin{description}
	\item[\refqualclass{checker/i18n/qual}{Localized}]
	indicates that the qualified
	\code{CharSequence} is a message that has been localized and/or formatted with
	respect to the used locale.

	\item[\refqualclass{checker/i18n/qual}{LocalizableKey}]
	indicates that the
	qualified \code{CharSequence} or \code{Object} is a valid key found in the
	localization resource.
	This annotation is a specialization of the \code{@PropertyKey} annotation, that
	gets checked by the general Property Key Checker.
	\end{description}

	You may need to add the \code{@Localized} annotation to more methods in the
	JDK or other libraries, or in your own code.


	\subsectionAndLabel{Running the Internationalization Checker}{i18n-running}

	The Internationalization Checker can be invoked by running the following
	command:

	%BEGIN LATEX
	\begin{smaller}
	%END LATEX
	\begin{Verbatim}
	javac -processor org.checkerframework.checker.i18n.I18nChecker -Abundlenames=MyResource MyFile.java ...
	\end{Verbatim}
	%BEGIN LATEX
	\end{smaller}
	%END LATEX

	You must specify the localization resource, which maps keys to user-visible
	text. Like the general Property Key Checker, the Internationalization Checker
	supports two types of localization resource:
	\code{ResourceBundle}s using the
	\code{-Abundlenames=\emph{resource\_name}} option
	or property files using the
	\code{-Apropfiles=\emph{prop\_file}} option.



	\sectionAndLabel{Compiler Message Key Checker}{compilermsgs-checker}

	The Checker Framework uses compiler message keys to output error messages.
	These keys are substituted by localized strings for user-visible error messages.
	Using keys instead of the localized strings in the source code enables easier
	testing, as the expected message keys can stay unchanged while the localized
	strings can still be modified.
	We use the Compiler Message Key Checker to ensure that all internal
	keys are correctly localized.
	Instead of using the Property File Checker, we use a specialized checker,
	giving us more precise documentation of the intended use of \code{String}s.

	The single annotation used by this checker is
	\refqualclass{checker/compilermsgs/qual}{CompilerMessageKey}.
	The Checker Framework is completely annotated;
	for example, class \code{org.checkerframework.framework.source.Result}
	uses \code{@CompilerMessageKey} in methods \code{failure} and \code{warning}.
	For most users of the Checker Framework there will be no need to annotate any
	\code{String}s, as the checker looks up all \code{String} literals and adds
	annotations as appropriate.

	The Compiler Message Key Checker can be invoked by running the following
	command:

	\begin{Verbatim}
	javac -processor org.checkerframework.checker.compilermsgs.CompilerMessagesChecker
	-Apropfiles=messages.properties MyFile.java ...
	\end{Verbatim}

	You must specify the resource, which maps compiler message keys to user-visible
	text. The checker supports the same options as the general property key checker.
	Within the Checker Framework we only use property files,
	so the \code{-Apropfiles=\emph{prop\_file}} option should be used.

	% LocalWords: NullPointerException genpropkey compilermsgs propkey PropertyKey
	% LocalWords: Abundlenames getBundle ResourceBundle ClassLoader Apropfiles
	% LocalWords: Abbrechen LocalizableKey CompilerMessageKey java I18n i18n
	% LocalWords: l10n