commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dflo...@apache.org
Subject svn commit: r154552 - in jakarta/commons/sandbox/i18n/trunk/xdocs: examples.xml index.xml navigation.xml quickstart.xml
Date Sun, 20 Feb 2005 18:12:56 GMT
Author: dflorey
Date: Sun Feb 20 10:12:55 2005
New Revision: 154552

URL: http://svn.apache.org/viewcvs?view=rev&rev=154552
Log: (empty)


Modified:
    jakarta/commons/sandbox/i18n/trunk/xdocs/examples.xml
    jakarta/commons/sandbox/i18n/trunk/xdocs/index.xml
    jakarta/commons/sandbox/i18n/trunk/xdocs/navigation.xml
    jakarta/commons/sandbox/i18n/trunk/xdocs/quickstart.xml

Modified: jakarta/commons/sandbox/i18n/trunk/xdocs/examples.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/sandbox/i18n/trunk/xdocs/examples.xml?view=diff&r1=154551&r2=154552
==============================================================================
--- jakarta/commons/sandbox/i18n/trunk/xdocs/examples.xml (original)
+++ jakarta/commons/sandbox/i18n/trunk/xdocs/examples.xml Sun Feb 20 10:12:55 2005
@@ -10,7 +10,60 @@
  <body>
  
 <section name="Using localized exceptions">
-<p></p>
+<p>
+The following example shows how to take advantage of detailed error information
+provided by localized exceptions. In the real world it is no good idea to create
+LocalizedExceptions but to create your own subclasses of LocalizedException.</p>
+<source>
+public class LocalizedExceptionExample {
+    private static final Logger logger = Logger.getLogger(LocalizedExceptionExample.class.getName());
+
+    public static void main(String[] args) {
+	    // Install the file providing the required messages for this example
+        XMLMessageProvider.install("org.apache.commons-i18n.examples", 
+        	Thread.currentThread().getContextClassLoader().getResourceAsStream("exampleMessages.xml"));
+
+		// Simulate the locale of the current user in a multi-user environment
+		// such as a web application
+        Locale currentUsersLocale = Locale.GERMAN;
+        
+        // This is the real part dealing with localized exceptions
+        try {
+            someMethodThrowingAnException();
+        } catch ( LocalizedException exception ) {
+			// Retrieve the detailed localized error message
+            ErrorBundle errorMessage = exception.getErrorMessage();
+
+            // Print the summary of this error to the log with level SEVERE
+            // using the VM default locale:
+            logger.log(Level.SEVERE, errorMessage.getSummary(Locale.getDefault()));
+
+            // Print the details of this error to the log with level FINE
+            // using the VM default locale:
+            logger.log(Level.FINE, errorMessage.getDetails(Locale.getDefault()));
+
+            // Provide the title of this error to the user in a highly visible way
+            // using the current users locale:
+            System.out.println("#### "+errorMessage.getTitle(currentUsersLocale)+" ####");
+
+            // Provide the text of this error to the user
+            // using the current users locale:
+            System.out.println(errorMessage.getText(currentUsersLocale));
+        }
+    }
+
+    /**
+     * @throws LocalizedException is thrown just to show the capabilities of LocalizedExceptions
+     */
+    private static void someMethodThrowingAnException() throws LocalizedException {
+        String userCausingTheException = "Daniel";
+        throw new LocalizedException(
+                new ErrorBundle("theCauseOfThisException",
+                new String[] { userCausingTheException } ));
+    }
+}
+</source>
+</p>
 </section>
 
 <section name="Custom message bundles">

Modified: jakarta/commons/sandbox/i18n/trunk/xdocs/index.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/sandbox/i18n/trunk/xdocs/index.xml?view=diff&r1=154551&r2=154552
==============================================================================
--- jakarta/commons/sandbox/i18n/trunk/xdocs/index.xml (original)
+++ jakarta/commons/sandbox/i18n/trunk/xdocs/index.xml Sun Feb 20 10:12:55 2005
@@ -9,22 +9,51 @@
 
  <body>
 
-<section name="The I18 Component">
-<p>Developing a localized application is supported by the Java language in a comfortable
way. 
-This package adds the feature of localized message bundles that consist of one or many localized
-texts that belong together. Think of an error message that consists of title, text, summary
and
-error details. These localized texts are bundled to a localized error and can be referenced
easily.</p>
+<section name="The I18n Component">
+<p>Developing a localized application is already supported by the Java language in
a comfortable way. 
+This package adds the feature of localized message bundles that group localized
+messages together. Think of a localized error description that consists of title, text, summary
and
+error details. These localized messages can be grouped together to form a localized error
bundle.</p>
+<p>This might be very useful in order to display these entries of the error description
to the user in different ways. 
+In a web based environment it might make sense to format the error title in a different way
than the details. When logging
+error messages it might be useful to use different log levels for the error summary or the
error details.</p>
+<p>Localized exceptions make use of this detailed error description. Have a look at
the <a href="examples.html">examples</a>
+to see localized exception in action.</p>
+<p>A <i>MessageManager</i> takes care of handling different pluggable <i>MessageProviders</i>
that deal with different
+message sources. This allows you to define the messages in your favourite format and 
+enables easy migration to the i18n-component.</p>
+<p>Each <i>MessageProvider</i> can handle a number of different resources
so that a bunch of messages 
+defined in a single resource (e.g. a file) can be updated or uninstalled.</p>
 <p>To get started go <a href="quickstart.html">here</a>.</p> 
-<p>Based on this concept localized exceptions are introduced that make dealing with
internationalization a pleasure...</p>
-<p>A message manager takes care of handling different pluggable message providers that
enable you to easily migrate to the i18n-component.</p>
-<p>It can handle a number of different message resources so that you can quickly reload
messages based
-on a single resource.</p>
+</section>
+
+<section name="Features at a glance">
+<p>
+ <ul>
+  <li>Messages that are part of an entity can be grouped together using bundles</li>
+  <li>The localization takes place lately when accessing message entries. This allows
printing the same message in different languages.</li>
+  <li>Localized exceptions enable a java applications to provide detailed localized
exception messages.</li>
+  <li>XML and ResourceBundle based message providers</li>
+  <li>Pluggable custom message providers enable access to existing data sources.</li>
+ </ul>
+</p>
 </section>
 
 <section name="Releases">
+<p>
+None. This is a <i>sandbox</i> component.
+</p>
     <p>
-       See the <a href="downloads.html">downloads</a> page for information on
obtaining releases.
+       See the <a href="downloads.html">downloads</a> page for information on
obtaining snapshop builds.
     </p>
+<p>
+ <ul>
+  <li>The code is unreleased</li>
+  <li>Methods and classes can and will appear and disappear without warning</li>
+  <li>If you like the code and want to push it towards a release, join the mailing
list!</li>
+ </ul>
+</p>
+    
 </section>
 
 <section name="Documentation">

Modified: jakarta/commons/sandbox/i18n/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/sandbox/i18n/trunk/xdocs/navigation.xml?view=diff&r1=154551&r2=154552
==============================================================================
--- jakarta/commons/sandbox/i18n/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/sandbox/i18n/trunk/xdocs/navigation.xml Sun Feb 20 10:12:55 2005
@@ -4,8 +4,9 @@
     <title>Commons&#xA0;I18n</title>
     <body>
         <menu name="Commons&#xA0;I18n">
-            <item name="Overview"                      href="/index.html" />
-            <item name="Getting started"                href="/quickstart.html" />
+            <item name="Overview" href="/index.html" />
+            <item name="Getting started" href="/quickstart.html" />
+            <item name="Examples" href="/examples.html" />
         </menu>
         &common-menus;
     </body>

Modified: jakarta/commons/sandbox/i18n/trunk/xdocs/quickstart.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/sandbox/i18n/trunk/xdocs/quickstart.xml?view=diff&r1=154551&r2=154552
==============================================================================
--- jakarta/commons/sandbox/i18n/trunk/xdocs/quickstart.xml (original)
+++ jakarta/commons/sandbox/i18n/trunk/xdocs/quickstart.xml Sun Feb 20 10:12:55 2005
@@ -10,19 +10,19 @@
  <body>
  
 <section name="Getting started">
-<p>In order to get an impression of how this component works, we will start with an
+<p>In order to get an impression how this component works, we will start with an
 	example showing the capabilities of this package.</p>
 </section>
 <section name="Defining the messages in an XML file">
-	<p>Using XML based files has many advantages:</p>
+<p>First of all we need to define some localized messages. There are two default message
providers 
+included that can be used to provide messages either in an XML-based format or in the well
known ResourceBundle format.</p>
+	<p>Using XML based files has some advantages:</p>
 	<ul>
-		<li>You can use the XML-editor of your choice to get assistance by typing the messages</li>
-		<li>All entries that belong together are grouped into a single XML element</li>
-		<li>All languages reside in a single file, so it is simpler to add a new language
(matter of taste?)</li>
-		<li>As the whole file gets parsed at initialization time, the localization is much
faster</li>
+		<li>You can use an XML-editor of your choice to get assistance while typing the messages</li>
+		<li>All entries that belong together are logically grouped into a single XML element</li>
+		<li>All provided languages reside in a single file, so it is easy to add a new language
(matter of taste?)</li>
+		<li>As the whole file gets parsed at initialization time, the localization is very
fast</li>
 	</ul>
-	<p>You have to initialize the message manager with an input stream giving access to

-	the xml document containing	the localized messages.</p>
 	<source>
 &lt;?xml version="1.0" encoding="UTF-8" ?>
 &lt;messages>
@@ -67,18 +67,13 @@
 <p>Each bundle can consist of a number of message entries that belong to this bundle.
You are free
 	to add as many entries to each bundle as you like. The I18n component contains 
 	a number of classes that simplify the access to entries of frequently used bundles.</p>
-</section>
-<section name="Pluggable message providers">
-<p>Since version 0.3 of this component you can add your own custom message providers.</p>
-<p>This is a big plus if you already have your localized messages in a database for
example.
-	You do not have to convert them into the supported XML or property-based format, but you
-	can write a simple <code>MessageProvider</code> by implementing a single method
and plug it in.</p>
+<p>After defining the messages we have to add them to the message provider dealing
with xml-based messages 
+by providing an input stream giving access to the xml document containing the localized messages.</p>
 </section>
 <section name="ResourceBundle based message provider">
-	<p>A new message provider made it into this component: The <code>ResourceBundleMessageProvider</code>.
-		This one enables you to keep your property files that may contain localized messages.</p>
-	<p>You can group entries messages by adding the key at the end of the existing message
key. The
-		following example shows how a property file should look like to work as the following XML
example:</p>
+	<p>The <code>ResourceBundleMessageProvider</code> enables you to keep
your property files that may contain localized messages.</p>
+	<p>You can group message entries by adding the key at the end of the existing message
key. The
+		following example shows how a property file should look like to provide the same messages
as the previous XML based example.</p>
 <p>As you know you'll need two files, each containing the messages for a specific locale.
This one might be
 	the default one calld myMessages.properties:</p>
 	<source>
@@ -102,8 +97,8 @@
 </source>
 </section>
 	<section name="Initializing the messages">
-<p>Now that we created a file containing the desired messages, we want to make use
of them.
-To do so we have to initialize the <code>MessageProvider</code> with these messages.</p>
+<p>Now that we created the desired messages, we want to make use of them.
+To do so we have to initialize the appropriate <code>MessageProvider</code> with
these messages.</p>
 	<p>Initializing messages depends on the <code>MessageProvider</code> that
you are using. In case of 
 		an <code>XMLMessageProvider</code> initialization looks like this:</p>
 <source>
@@ -116,12 +111,13 @@
 }
 ...
 </source>
-<p>As you can see it is very easy to install new messages. All you need is an appropriate
+<p>As you can see it is very easy to install new messages. All you need is to provide
a unique identifier and an 
 	input stream to access the xml messages.</p><p>Why is the manager initialized
with an input stream
 	and not using a file name? You might want to use the i18n component within web applications
 	where you want probably load messages from you .war archive. So an input stream is much
 	more flexible, even if it is a little bit more unconvenient than using
 	a file name in our use case.</p>
+<p>When installing messages we can specify an identifier that enables us to uninstall
or update these messages later on.</p>
 <p>In case of the brand new <code>ResourceBundleMessageProvider</code>
initialization looks even simpler:</p>
 <source>
 ...
@@ -147,32 +143,32 @@
 	and dirty, but the recommended way is the following:</p>
 <source>
 ...
-LocalizedText welcome = new LocalizedText("welcome");
+TextBundle welcome = new TextBundle("welcome");
 // Using the default locale
-System.out.println(welcome.getText());
-// Using some other locale
+System.out.println(welcome.getText(Locale.getDefault()));
+// Using some other specific locale
 System.out.println(welcome.getText(Locale.GERMAN));
 ...
 </source>
-<p>In this example we make use of the predefined message bundle called <code>LocalizedText</code>
+<p>In this example we make use of the predefined message bundle called <code>TextBundle</code>
 	that just consists of a single text element. The advantage of this approach is, that you
 	avoid misspelling as you have getter-methods for each entry. You also have the ability to
 	pass some default text that will be used if the message was not found:</p>
 <source>
 ...
-LocalizedText welcome = new LocalizedText("undefined");
-System.out.println(welcome.getText("notFound"));
+TextBundle welcome = new TextBundle("welcome");
+System.out.println(welcome.getText(Locale.GERMAN, "No welcome message found!"));
 ...
 </source>
-<p>As the <code>MessageManager</code> can not find the message with id
<code>undefined</code>,
+<p>As the <code>MessageManager</code> can not find the message with id
<code>welcome</code>,
 	a <code>MessageNotFoundeException</code> is thrown. This one is a <code>RuntimeException</code>
 	as this avoids bloating up the code with exception handling.</p> 
-	<p>The <code>LocalizedText</code>
+	<p>The <code>TextBundle</code>
 	handles this exception and returns the given default text instead.</p>
 </section>
 <section name="Using localized exceptions">
 <p>The concept of message bundles is very useful when it comes to exception handling.
-You can simple create a <code>LocalizedException</code> that will be constructed
with a <code>LocalizedError</code>
+You can simply create a <code>LocalizedException</code> that will be constructed
with an <code>ErrorBundle</code>
 object containing title, text, summary and details of the exception. In addition you can
specify the causing exception:</p>
 <source>
 ...
@@ -180,26 +176,20 @@
 	doSomething();
 } catch ( SomeException exception ) {
 	throw new LocalizedException(
-		new LocalizedError("somethingFailed", new Object[] { agrument1 }),
+		new ErrorBundle("somethingFailed", new Object[] { agrument1 }),
 		exception);
 }
 ...
 </source>
 <p>The big advantage of this approach is that you can create localized exceptions with
all arguments
 	that are describing the error in detail and print out localized details including this arguments
-	lateron. Have a look at the Slide Projector to see how this can simplify your life ;-)</p>
+	later on. Have a look at the <a href="examples.html">examples</a> to see how
this can simplify your life ;-)</p>
 </section>
-<section name="Releases">
-    <p>
-       See the <a href="downloads.html">downloads</a> page for information on
obtaining releases.
-    </p>
-</section>
-
-<section name="Documentation">
-  <p>
-     The <a href="apidocs/index.html">JavaDoc API documents</a> are available
online.
-  </p>
+<section name="Pluggable message providers">
+<p>You can add your own custom message providers.</p>
+<p>This is a big plus if you already have your localized messages in a database for
example.
+	You do not have to convert them into the supported XML or property-based format, but you
+	can write a simple <code>MessageProvider</code> by implementing a the <code>MessageProvider</code>
interface and plug it in.</p>
 </section>
-
 </body>
 </document>



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message