commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dflo...@apache.org
Subject cvs commit: jakarta-commons-sandbox/i18n/xdocs quickstart.xml navigation.xml index.xml
Date Tue, 05 Oct 2004 17:47:55 GMT
dflorey     2004/10/05 10:47:55

  Modified:    i18n/xdocs navigation.xml index.xml
  Added:       i18n/xdocs quickstart.xml
  Log:
  Documentation added
  
  Revision  Changes    Path
  1.2       +1 -0      jakarta-commons-sandbox/i18n/xdocs/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/i18n/xdocs/navigation.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- navigation.xml	4 Oct 2004 13:41:10 -0000	1.1
  +++ navigation.xml	5 Oct 2004 17:47:55 -0000	1.2
  @@ -5,6 +5,7 @@
       <body>
           <menu name="Commons&#xA0;Transaction">
               <item name="Overview"                      href="/index.html" />
  +            <item name="Getting started"                href="/quickstart.html" />
               <item name="API&#xA0;Documentation"        href="/apidocs/index.html"/>
               <item name="Downloads"                     href="/downloads.html"/>
           </menu>
  
  
  
  1.2       +9 -2      jakarta-commons-sandbox/i18n/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/i18n/xdocs/index.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- index.xml	4 Oct 2004 13:41:10 -0000	1.1
  +++ index.xml	5 Oct 2004 17:47:55 -0000	1.2
  @@ -9,8 +9,15 @@
   
    <body>
   
  -<section name="The I18n Component">
  -<p>Provides a set of classes dealing with internationalization issues.</p>
  +<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>
  +	<p>Based on this concept localized exceptions are introduced that make dealing with
internationalization a pleasure...</p>
  +	<p>A message manager takes care of initializing the messages from an XML document.

  +	It can handle a number of different message resource so that you can quickly reload messages
based
  +	on a single resource.</p>
   </section>
   
   <section name="Releases">
  
  
  
  1.1                  jakarta-commons-sandbox/i18n/xdocs/quickstart.xml
  
  Index: quickstart.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
   <properties>
    <title>Quickstart</title>
    <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
   </properties>
  
   <body>
   
  <section name="Getting started">
  <p>In order to get an impression of how this component works, we will start with an
  	example showing the capabilities of this package.</p>
  <p>To get started you need at least the jar of this component and the dependent xml-importer-jar
for reading
  	xml documents in your classpath.</p>
  </section>
  <section name="Defining the messages">
  	<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>
    &lt;message id="welcome">
      &lt;locale language="en"> 
  	  &lt;entry key="text">Welcome&lt;/entry>
      &lt;/locale> 
      &lt;locale language="de"> 
        &lt;entry key="text">Willkommen&lt;/entry>
      &lt;/locale> 
    &lt;/message>
    &lt;message id="usage">
      &lt;locale language="en"> 
        &lt;entry key="title">Usage&lt;/entry>
        &lt;entry key="text">The application requires the following parameters:&lt;/entry>
        &lt;/locale> 
      &lt;locale language="de"> 
        &lt;entry key="title">Benutzung&lt;/entry>
        &lt;entry key="text">Die folgenden Parameter werden erwartet:&lt;/entry>
      &lt;/locale> 
    &lt;/message>
    &lt;message id="validationFailed">
      &lt;locale language="en">
        &lt;entry key="title">Parameter {0} invalid&lt;/entry>
        &lt;entry key="text">The given value of the parameter {0} is invalid&lt;/entry>
        &lt;entry key="summary">Value of parameter {0} invalid&lt;/entry>
        &lt;entry key="details">The given value {1} of parameter {0} is invalid.&lt;/entry>
      &lt;/locale>
      &lt;locale language="de">
        &lt;entry key="title">Parametervalidierung fehlgeschlagen.&lt;/entry>
        &lt;entry key="text">Die Validierung des Parameters {0} ist fehlgeschlagen.&lt;/entry>
        &lt;entry key="summary">Validierung des Parameters {0} fehlgeschlagen.&lt;/entry>
        &lt;entry key="details">Der Wert {1} des Parameters {0} ist ung├╝ltig.&lt;/entry>
      &lt;/locale>
    &lt;/message>	
  &lt;/messages>
  	</source>
  <p>This is an example that shows how to create localized bundles. As you can see each
  	message is identified by a message id and contains the bundled messages for the 
  	defined locales. The language identifiers are well known from the <code>Locale</code>
class
  	and support language variants and the appropriate fallback mechanism.</p>
  <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="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>MessageManager</code> with these messages.</p>
  <source>
  ...
  try {
  	FileInputStream inputStream = new FileInputStream("myMessages.xml");
  	MessageManager.install("myMessages", inputStream);
  } catch ( FileNotFoundException e ) {
  	// handle exception
  }
  ...
  </source>
  <p>As you can see it is very easy to install new messages. All you need is an appropriate
  	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>
  </section>
  <section name="Using message bundles">
  	<p>Now we are ready to go! First of all we want to print out a simple localized welcome
  		message to the user. There are different way to do so: We can call the
  	<code>MessageManager</code> directly by asking for a specific entry of a message:</p>
  <source>
  ...
  System.out.println(MessageManager.getText("welcome", "text", new Object[0], Locale.getDefault()));
  ...
  </source>
  <p>If you are familiar with text formatting in Java you will have guessed correctly
that you
  	have the ability to pass arguments to the localized text. In our case we don't pass any
  	arguments but just an empty object array.</p>
  <p>The previous example might be useful if you want to print out some localized message
quick
  	and dirty, but the recommended way is the following:</p>
  <source>
  ...
  LocalizedText welcome = new LocalizedText("welcome");
  // Using the default locale
  System.out.println(welcome.getText());
  // Using some other 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>
  	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"));
  ...
  </source>
  <p>As the <code>MessageManager</code> can not find the message with id
<code>undefined</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>
  	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>
  object containing title, text, summary and details of the exception. In addition you can
specify the causing exception:</p>
  <source>
  ...
  try {
  	doSomething();
  } catch ( SomeException exception ) {
  	throw new LocalizedException(
  		new LocalizedError("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>
  </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>
  
  </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