forked from fge/msg-simple
-
Notifications
You must be signed in to change notification settings - Fork 5
Expand file tree
/
Copy pathoverview.html
More file actions
134 lines (114 loc) · 5.08 KB
/
overview.html
File metadata and controls
134 lines (114 loc) · 5.08 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
<!--
~ Copyright (c) 2014, Francis Galiegue (fgaliegue@gmail.com)
~
~ This software is dual-licensed under:
~
~ - the Lesser General Public License (LGPL) version 3.0 or, at your option, any
~ later version;
~ - the Apache Software License (ASL) version 2.0.
~
~ The text of this file and of both licenses is available at the root of this
~ project or, if you have the jar distribution, in directory META-INF/, under
~ the names LGPL-3.0.txt and ASL-2.0.txt respectively.
~
~ Direct link to the sources:
~
~ - LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt
~ - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt
-->
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/html">
<head>
<title>msg-simple: a better ResourceBundle</title>
</head>
<body>
<h2>What is it</h2>
<p>This package is an alternative to the JDK's {@link java.util.ResourceBundle}
with the following characteristics:</p>
<ul>
<li>extensible API;</li>
<li>can read property files using any character set;</li>
<li>full backwards-compatibility with {@link java.util.ResourceBundle};</li>
<li>i18n/locale support;</li>
<li>stackable message sources; can prepend as well as append;</li>
<li>static message sources or on-demand loading message sources, with
configurable timeout and expiry;</li>
<li>{@link java.util.Formatter} support, in addition to {@link
java.text.MessageFormat} support;</li>
<li>error-proof: missing messages or bad format arguments won't throw
exceptions (only null arguments will, with appropriate error messages);</li>
<li>builtin assertions into message bundles (null checks, condition checks);
</li>
<li>on-demand loading and caching of message bundles.</li>
</ul>
<h2>Quick start</h2>
<p>If you wish to reuse an existing {@link java.util.ResourceBundle}, the class
you will use is {@link com.github.fge.msgsimple.bundle.PropertiesBundle}. It
contains static factory methods to provide a ready-to-use {@link
com.github.fge.msgsimple.bundle.MessageBundle}:</p>
<pre>
// Load a properties bundle using UTF-8 and no expiry
final MessageBundle bundle = PropertiesBundle.forPath("path/to/messages");
// Load a properties bundle using UTF-8 and an expiry of 15 minutes
final MessageBundle bundle = PropertiesBundle.forPath("path/to/messages",
15L, TimeUnit.MINUTES);
// Load a legacy resource bundle (ISO-8859-1 charset, no expiry)
final MessageBundle bundle
= PropertiesBundle.legacyResourceBundle("path/to/messages");
</pre>
<p>You are now ready to print out messages:</p>
<pre>
// Message using the default locale
bundle.getMessage("message.key");
// Message using an alternative locale
bundle.getMessage(Locale.CANADA, "message.key");
bundle.getMessage(LocaleUtils.parseLocale("it_IT_sicily", "message.key");
// message using a Formatter
bundle.printf("message.key", arg1, arg2);
// message using MessageFormat
bundle.format("message.key", arg1, arg2);
// etc etc
</pre>
<p>You can also use preconditions:</p>
<pre>
// Checks the reference for null; throws NullPointerException if it is;
final MyClass obj = bundle.checkNotNull(ref, "err.nullMyClass");
// Checks whether the condition is true; throws IllegalArgumentException
// otherwise
bundle.checkArgumentPrintf(something.isOk(), "err.something.notOk", arg1,
arg2);
</pre>
<h2>Extending the API</h2>
<p>The API is very simple to extend. There are two interfaces:</p>
<ul>
<li>{@link com.github.fge.msgsimple.source.MessageSource} represents a
message source;</li>
<li>{@link com.github.fge.msgsimple.provider.MessageSourceProvider}
represents a related set of message sources;</li>
<li>{@link com.github.fge.msgsimple.provider.MessageSourceLoader} represents
an on-demand loader for dynamic message sources.</li>
</ul>
<p>This library provides two message source implementations: {@link
com.github.fge.msgsimple.source.MapMessageSource} is a "quickpatch" source
backed by a {@link java.util.Map}, and {@link
com.github.fge.msgsimple.source.PropertiesMessageSource}, which reads a property
file using the encoding of your choice.</p>
<p>It also provides two implementations of message source providers: {@link
com.github.fge.msgsimple.provider.StaticMessageSourceProvider} (static,
unchanging message sources) and {@link
com.github.fge.msgsimple.provider.LoadingMessageSourceProvider} (on-demand
loading). Using the latter, you can specify an expiry time and a loading
timeout.</p>
<h2>Automatic loading</h2>
<p>If you have several message bundles and don't want to create a singleton just
to distribute them across several classes, you can instead provide an
implementation of {@link com.github.fge.msgsimple.load.MessageBundleLoader}.
When you need to access this bundle, from anywhere in your code, you can then
use the {@link com.github.fge.msgsimple.load.MessageBundles} class, which will
take care of instantiating the loader and provide you with the bundle:</p>
<pre>
private static final MessageBundle BUNDLE
= MessageBundles.getBundle(MyBundleLoader.class);
</pre>
</body>
</html>