platform-core-home/documents/3.1/message_bundles.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1, Thu Feb 10 19:21:25 2005 UTC revision 1.2, Thu Feb 10 20:18:23 2005 UTC
# Line 29  Line 29 
29          <tr>          <tr>
30                  <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>                  <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
31    
32      <td WIDTH="98%"><b>Description</b> <p>This is a description of the new message      <td WIDTH="98%"><b>Description</b> <p>Standard Java ResourceBundles have quite
33          bundle format story for Eclipse.</p>          inefficient space characteristics. Since a running Eclipse tends to have
34        <p>Summary of the new format:</p>          many externalized messages we have implemented a new message bundle story
35        <ul>          to be used in Eclipse. The mechanism is quite simple and completely generic
36          <li>messages.properties - same as before except keys need to be valid          - it can be used anywhere.</p>
37            Java identifier names (replace "." with "_", etc)        <p>Summary of the new approach:</p>
         <li>Java file has a static String field for each message  
         <li>On startup, we set the values of the fields to be the strings from  
           the messages.properties files and then discard the properties file from  
           memory.  
       </ul> <p>When creating a new message:</p>  
38        <ul>        <ul>
39          <li>create a field in your Messages.java file</li>          <li>messages.properties - this file is same as before except all keys
40          <li>create a key/value pair in your messages.properties file</li>            need to be valid Java identifiers.
41          <li>the key MUST be the same as the field name</li>          <li>Each message file has a corresponding Java class.
42          <li>in your code, just use the field reference rather than a lookup (e.g.          <li>Each key/value pair in the file has a public static String field whose
43            Messages.my_key)</li>            name is the same as the message key.
44        </ul>          <li>When message bundles are loaded, the values of the fields are set
45        <p>&nbsp;</p></td>            to be the values from the messages.properties files.
46          </tr>          <li>The message properties files are purged from memory.
         <tr>  
                 <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">Performance</font></b></td>  
         </tr>  
         <tr>  
                 <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>  
   
     <td WIDTH="98%"><b>Time</b>  
       <p>The code is faster since accessing the messages is just a field access  
         rather than a lookup in the resource bundle. </p>  
       <p>Our performance results indicate the time to load and initialize bundle  
         are VM dependant but are 5% to 46% faster using the new mechanism.</p>  
       <p>&nbsp;</p>  
                 </td>  
         </tr>  
         <tr>  
                 <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>  
   
     <td WIDTH="98%"><b>Memory Footprint</b>  
       <p>With the new mechanism, the rough space savings is 88 + 5N per message  
         where N is the length of the keys. </p>  
       <p>We have calculated in the best-case scenerio for the Eclipse SDK if every  
         key in every properties file was referenced, then the savings would be  
         roughly 4.5M. (based on the January 11, 2005 integration build)</p>  
       <p>&nbsp;</p>  
                 </td>  
         </tr>  
         <tr>  
                 <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>  
   
     <td WIDTH="98%"><b>Other benefits</b> <ul>  
         <li>Easily catch missing keys - Message lookups are now field accesses  
           so you cannot reference a key that doesn't exist or you will get a compile  
           error. </li>  
         <li>Easily find typos in code when referencing keys - Each key is represented  
           by a field in the class so if the referencing code makes a spelling  
           error, then you will get a compile error.</li>  
         <li>Find unused keys - During the development cycle code is deleted, moved  
           and messages are changed. As a result there are keys in the messages.properties  
           file which are never referenced.These can easily be found now since  
           you can just do a search for references to the field. If there are no  
           references, then delete the field from the class and the key/value pair  
           from the file.</li>  
47        </ul>        </ul>
48        <p>&nbsp;</p></td>        <p>When creating a new message:</p>
         </tr>  
         <tr>  
                 <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>  
   
     <td WIDTH="98%"><b>Drawbacks</b>  
49          <ul>          <ul>
50          <li>There are now 2 files to maintain - Now the messages.properties and the java file must be kept in sync. There          <li>create a field in your Messages.java file</li>
51          is an opportunity for tooling to help with this; a validation tool could indicate problems with markers. Currently          <li>create a key/value pair in your messages.properties file where the
52          there are debug options which log entries which exsit in one file but not the other.</li>            key name matches the field name</li>
53            <li>to reference the message, simply reference the field (e.g. Messages.my_key)
54              rather than the standard lookup</li>
55          </ul>          </ul>
56          <p>&nbsp;        <p>&nbsp;</p></td>
         </p>  
         </td>  
57          </tr>          </tr>
   
58                  <tr>                  <tr>
59                  <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">File Formats</font></b></td>                  <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">File Formats</font></b></td>
60          </tr>          </tr>
# Line 196  Line 143 
143            </td>            </td>
144          </tr>          </tr>
145          <tr>          <tr>
146                    <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">Performance</font></b></td>
147            </tr>
148            <tr>
149                    <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
150    
151        <td WIDTH="98%"><p><b>Time</b> </p>
152          <ul>
153            <li>Using a message is marginally faster since it is just a field access
154              rather than a lookup in the resource bundle.</li>
155            <li>Time to load and initialize a bundle is VM dependant but we have seen
156              5% to 46% improvements. </li>
157          </ul>
158          <p>&nbsp;</p>
159          </td>
160            </tr>
161            <tr>
162                    <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
163    
164        <td WIDTH="98%"><p><b>Memory Footprint</b> </p>
165          <ul>
166            <li>This is very much a scalability play. The more you use, the more you
167              save.</li>
168            <li>The rough space savings is 88 + 4N bytes per message where N is the
169              number of characters in the key.</li>
170            <li>The absolute best-case scenerio for the Eclipse SDK, if every property
171              file is loaded and every key referenced, is roughly 4.5M of memory.
172              (based on the January 11, 2005 integration build)</li>
173            <li>Realistic scenarios for the Eclipse IDE should see savings on the
174              order of 500KB </li>
175          </ul>
176          <p>&nbsp;</p>
177          </td>
178            </tr>
179            <tr>
180                    <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
181    
182        <td WIDTH="98%"><b>Other benefits</b> <ul>
183            <li>Easily catch missing keys - Message lookups are now field accesses
184              so you cannot reference a key that doesn't exist or you will get a compile
185              error. </li>
186            <li>Easily find typos in code when referencing keys - Each key is represented
187              by a field in the class so if the referencing code makes a spelling
188              error, then you will get a compile error.</li>
189            <li>Find unused keys - During the development cycle code is deleted, moved
190              and messages are changed. As a result there are keys in the messages.properties
191              file which are never referenced.These can easily be found now since
192              you can just do a search for references to the field. If there are no
193              references, then delete the field from the class and the key/value pair
194              from the file.</li>
195          </ul>
196          <p>&nbsp;</p></td>
197            </tr>
198            <tr>
199                    <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
200    
201        <td WIDTH="98%"><b>Drawbacks</b>
202            <ul>
203            <li>There are now 2 files to maintain - Now the messages.properties and the java file must be kept in sync. There
204            is an opportunity for tooling to help with this; a validation tool could indicate problems with markers. Currently
205            there are debug options which log entries which exsit in one file but not the other.</li>
206            </ul>
207            <p>&nbsp;
208            </p>
209            </td>
210            </tr>
211    
212    
213            <tr>
214                  <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">Tools</font></b></td>                  <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">Tools</font></b></td>
215          </tr>          </tr>
216          <tr>          <tr>
# Line 203  Line 218 
218    
219      <td WIDTH="98%"><b>Conversion</b> <p>We have written a tool which aids in      <td WIDTH="98%"><b>Conversion</b> <p>We have written a tool which aids in
220          converting from the basic Java resource bundle look-up mechanism, to the          converting from the basic Java resource bundle look-up mechanism, to the
221          new format. </p>          new format. There is no requirement to do this conversion unless you want
222            to take advantage of the new mechanism.</p>
223        <p><em>Note that the message bundle access class is replaced when the tool        <p><em>Note that the message bundle access class is replaced when the tool
224          is run. If you define extra code, constants, etc in that class then please          is run. If you define extra code, constants, etc in that class then please
225          read the notes below to ensure that you don't have problems.</em></p>          read the notes below to ensure that you don't have problems.</em></p>
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2