epubjs
Version:
Render ePub documents in the browser, across many devices
92 lines (91 loc) • 18.1 kB
HTML
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Properties</title><link rel="stylesheet" href="core.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/></head><body><div class="sect1" title="Properties"><div class="titlepage"><div><div><h1 class="title"><a id="learnjava3-CHP-11-SECT-5"/>Properties</h1></div></div></div><p>The <a id="I_indexterm11_id746927" class="indexterm"/><code class="literal">java.util.Properties</code>
class is a specialized hash table for strings. Properties are generally
used to hold textual configuration data. Examples of this are the Java
System properties, which are passed to a Java application on the command
line. We’ll cover those later in this section. More generally, you can use
a <code class="literal">Properties</code> table to hold arbitrary
configuration information for an application in an easily accessible
format. The neat thing about a <code class="literal">Properties</code> object is that it can load and store
its information in a plain text or XML text format using streams (see
<a class="xref" href="ch12.html" title="Chapter 12. Input/Output Facilities">Chapter 12</a> for information on streams).</p><p>Any string values can be stored as key/value pairs in a <code class="literal">Properties</code> table. However, the convention is to
use a dot-separated naming hierarchy to group property names into logical
structures. (Unfortunately, this is just a convention, and you can’t
really work with groups of properties in a hierarchical way as this might
imply.) For example, you can create an empty <code class="literal">Properties</code> object and add <code class="literal">String</code> key/value pairs just as you could with a
<code class="literal">Map</code>:</p><a id="I_11_tt731"/><pre class="programlisting"> <code class="n">Properties</code> <code class="n">props</code> <code class="o">=</code> <code class="k">new</code> <code class="n">Properties</code><code class="o">();</code>
<code class="n">props</code><code class="o">.</code><code class="na">setProperty</code><code class="o">(</code><code class="s">"myApp.xsize"</code><code class="o">,</code> <code class="s">"52"</code><code class="o">);</code>
<code class="n">props</code><code class="o">.</code><code class="na">setProperty</code><code class="o">(</code><code class="s">"myApp.ysize"</code><code class="o">,</code> <code class="s">"79"</code><code class="o">);</code></pre><p>Thereafter, you can retrieve values with the <a id="I_indexterm11_id747003" class="indexterm"/><code class="literal">getProperty()</code>
method:</p><a id="I_11_tt732"/><pre class="programlisting"> <code class="n">String</code> <code class="n">xsize</code> <code class="o">=</code> <code class="n">props</code><code class="o">.</code><code class="na">getProperty</code><code class="o">(</code> <code class="s">"myApp.xsize"</code> <code class="o">);</code></pre><p>If the named property doesn’t exist, <code class="literal">getProperty()</code> returns <code class="literal">null</code>. You can get an <code class="literal">Enumeration</code> of the property names with the
<a id="I_indexterm11_id747042" class="indexterm"/><code class="literal">propertyNames()</code>
method:</p><a id="I_11_tt733"/><pre class="programlisting"> <code class="k">for</code> <code class="o">(</code> <code class="n">Enumeration</code> <code class="n">e</code> <code class="o">=</code> <code class="n">props</code><code class="o">.</code><code class="na">propertyNames</code><code class="o">();</code> <code class="n">e</code><code class="o">.</code><code class="na">hasMoreElements</code><code class="o">();</code> <code class="o">)</code> <code class="o">{</code>
<code class="n">String</code> <code class="n">name</code> <code class="o">=</code> <code class="n">e</code><code class="o">.</code><code class="na">nextElement</code><code class="o">();</code>
<code class="o">...</code>
<code class="o">}</code></pre><p>When you create a <code class="literal">Properties</code>
object, you can specify a second object for default property
values:</p><a id="I_11_tt734"/><pre class="programlisting"> <code class="n">Properties</code> <code class="n">defaults</code> <code class="o">=</code> <code class="o">...</code>
<code class="n">Properties</code> <code class="n">props</code> <code class="o">=</code> <code class="k">new</code> <code class="n">Properties</code><code class="o">(</code> <code class="n">defaults</code> <code class="o">);</code></pre><p>Now, when you call <code class="literal">getProperty()</code>,
the method searches the default table if it doesn’t find the named
property in the current table. An alternative version of <code class="literal">getProperty()</code> also accepts a default value; this
value is returned instead of <code class="literal">null</code> if
the property is not found in the current or default lists:</p><a id="I_11_tt735"/><pre class="programlisting"> <code class="n">String</code> <code class="n">xsize</code> <code class="o">=</code> <code class="n">props</code><code class="o">.</code><code class="na">getProperty</code><code class="o">(</code> <code class="s">"myApp.xsize"</code><code class="o">,</code> <code class="s">"50"</code> <code class="o">);</code></pre><div class="sect2" title="Loading and Storing"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-11-SECT-5.1"/>Loading and Storing</h2></div></div></div><p><a id="idx10634" class="indexterm"/> <a id="idx10650" class="indexterm"/> <a id="idx10667" class="indexterm"/> <a id="idx10670" class="indexterm"/>You can save a <code class="literal">Properties</code> table to an <code class="literal">OutputStream</code> using the <a id="I_indexterm11_id747177" class="indexterm"/><code class="literal">save()</code> method. The
property information is output in a flat ASCII format. We’ll talk about
I/O in the next chapter, but bear with us for now. Continuing with the
previous example, output the property information using the <code class="literal">System.out</code> stream as follows:</p><a id="I_11_tt736"/><pre class="programlisting"> <code class="n">props</code><code class="o">.</code><code class="na">save</code><code class="o">(</code> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">,</code> <code class="s">"Application Parameters"</code> <code class="o">);</code></pre><p><code class="literal">System.out</code> is a standard output
stream that prints to the console or command line of an application. We
could also save the information to a file using a <code class="literal">FileOutputStream</code> as the first argument to
<code class="literal">save()</code>. The second argument to
<code class="literal">save()</code> is a <code class="literal">String</code> that is used as a header for the data.
The previous code outputs something like the following to <code class="literal">System.out</code>:</p><a id="I_11_tt737"/><pre class="programlisting"> <code class="err">#</code><code class="n">Application</code> <code class="n">Parameters</code>
<code class="err">#</code><code class="n">Mon</code> <code class="n">Feb</code> <code class="mi">12</code> <code class="mi">09</code><code class="o">:</code><code class="mi">24</code><code class="o">:</code><code class="mi">23</code> <code class="n">CST</code> <code class="mi">2001</code>
<code class="n">myApp</code><code class="o">.</code><code class="na">ysize</code><code class="o">=</code><code class="mi">79</code>
<code class="n">myApp</code><code class="o">.</code><code class="na">xsize</code><code class="o">=</code><code class="mi">52</code></pre><p>The <a id="I_indexterm11_id747253" class="indexterm"/><code class="literal">load()</code> method reads the
previously saved contents of a <code class="literal">Properties</code> object from an <code class="literal">InputStream</code>:</p><a id="I_11_tt738"/><pre class="programlisting"> <code class="n">FileInputStream</code> <code class="n">fin</code><code class="o">;</code>
<code class="o">...</code>
<code class="n">Properties</code> <code class="n">props</code> <code class="o">=</code> <code class="k">new</code> <code class="n">Properties</code><code class="o">()</code>
<code class="n">props</code><code class="o">.</code><code class="na">load</code><code class="o">(</code> <code class="n">fin</code> <code class="o">);</code></pre><p>The <a id="I_indexterm11_id747286" class="indexterm"/><code class="literal">list()</code> method is useful
for debugging. It prints the contents to an <code class="literal">OutputStream</code> in a format that is more
human-readable but not retrievable by <code class="literal">load()</code>. It truncates long lines with an
ellipsis (<code class="literal">...</code>).</p><p>The <code class="literal">Properties</code> class also
contains <a id="I_indexterm11_id747324" class="indexterm"/><code class="literal">storeToXML()</code> and
<a id="I_indexterm11_id747334" class="indexterm"/><code class="literal">loadFromXML()</code> methods.
These operate just like the <code class="literal">save()</code>
and <code class="literal">load()</code> methods but write an XML
file like the following:</p><a id="I_programlisting11_id747357"/><pre class="programlisting"> <code class="o"><?</code><code class="n">xml</code> <code class="n">version</code><code class="o">=</code><code class="s">"1.0"</code> <code class="n">encoding</code><code class="o">=</code><code class="s">"UTF-8"</code><code class="o">?></code>
<code class="o"><!</code><code class="n">DOCTYPE</code> <code class="n">properties</code> <code class="n">SYSTEM</code> <code class="s">"http://java.sun.com/dtd/properties.dtd"</code>
<code class="o">></code>
<code class="o"><</code><code class="n">properties</code><code class="o">></code>
<code class="o"><</code><code class="n">comment</code><code class="o">></code><code class="n">My</code> <code class="n">Properties</code><code class="o"></</code><code class="n">comment</code><code class="o">></code>
<code class="o"><</code><code class="n">entry</code> <code class="n">key</code><code class="o">=</code><code class="s">"myApp.ysize"</code><code class="o">></code><code class="mi">79</code><code class="o"></</code><code class="n">entry</code><code class="o">></code>
<code class="o"><</code><code class="n">entry</code> <code class="n">key</code><code class="o">=</code><code class="s">"myApp.xsize"</code><code class="o">></code><code class="mi">52</code><code class="o"></</code><code class="n">entry</code><code class="o">></code>
<code class="o"></</code><code class="n">properties</code><code class="o">></code></pre><p>We’ll cover XML in detail in <a class="xref" href="ch24.html" title="Chapter 24. XML">Chapter 24</a>.<a id="I_indexterm11_id747373" class="indexterm"/><a id="I_indexterm11_id747380" class="indexterm"/><a id="I_indexterm11_id747387" class="indexterm"/><a id="I_indexterm11_id747394" class="indexterm"/></p></div><div class="sect2" title="System Properties"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-11-SECT-5.2"/>System Properties</h2></div></div></div><p><a id="idx10635" class="indexterm"/> <a id="idx10668" class="indexterm"/> <a id="idx10672" class="indexterm"/>The <code class="literal">java.lang.System</code>
class provides access to basic system environment information through
the static <a id="I_indexterm11_id747453" class="indexterm"/><code class="literal">System.getProperties()</code>
method. This method returns a <code class="literal">Properties</code> table that contains system
properties. System properties take the place of environment variables in
some programming environments. <a class="xref" href="ch11s05.html#learnjava3-CHP-11-TABLE-8" title="Table 11-8. System properties">Table 11-8</a> summarizes system properties that
are guaranteed to be defined in any Java environment.</p><div class="table"><a id="learnjava3-CHP-11-TABLE-8"/><p class="title">Table 11-8. System properties</p><div class="table-contents"><table summary="System properties" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/></colgroup><thead><tr><th style="text-align: left" valign="top"><p>System
property</p></th><th style="text-align: left"><p>Meaning</p></th></tr></thead><tbody><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747525" class="indexterm"/> <code class="literal">java.vendor</code>
</p></td><td style="text-align: left"><p>Vendor-specific string</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747550" class="indexterm"/> <code class="literal">java.vendor.url</code> </p></td><td style="text-align: left"><p>URL of vendor</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747575" class="indexterm"/> <code class="literal">java.version</code>
</p></td><td style="text-align: left"><p>Java version</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747601" class="indexterm"/> <code class="literal">java.home</code>
</p></td><td style="text-align: left"><p>Java installation
directory</p></td></tr><tr><td style="text-align: left" valign="top"><p> <code class="literal">java.class.version</code> </p></td><td style="text-align: left"><p>Java class version</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747645" class="indexterm"/> <code class="literal">java.class.path</code> </p></td><td style="text-align: left"><p>The classpath</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747670" class="indexterm"/> <code class="literal">os.name</code>
</p></td><td style="text-align: left"><p>Operating system name</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747695" class="indexterm"/> <code class="literal">os.arch</code>
</p></td><td style="text-align: left"><p>Operating system
architecture</p></td></tr><tr><td style="text-align: left" valign="top"><p> <code class="literal">os.version</code> </p></td><td style="text-align: left"><p>Operating system
version</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747740" class="indexterm"/> <code class="literal">file.separator</code>
</p></td><td style="text-align: left"><p>File separator (such as <code class="literal">/</code> or <code class="literal">\</code>)</p></td></tr><tr><td style="text-align: left" valign="top"><p> <code class="literal">path.separator</code> </p></td><td style="text-align: left"><p>Path separator (such as <code class="literal">:</code> or <code class="literal">;</code>)</p></td></tr><tr><td style="text-align: left" valign="top"><p> <code class="literal">line.separator</code> </p></td><td style="text-align: left"><p>Line separator (such as <code class="literal">\n</code> or <code class="literal">\r\n</code>)</p></td></tr><tr><td style="text-align: left" valign="top"><p> <code class="literal">user.name</code> </p></td><td style="text-align: left"><p>User account name</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm11_id747854" class="indexterm"/> <code class="literal">user.home</code>
</p></td><td style="text-align: left"><p>User’s home directory</p></td></tr></tbody></table></div></div><p>Java applets and other Java applications that run with
restrictions may be prevented from reading the following properties:
<code class="literal">java.home</code>, <code class="literal">java.class.path</code>, <code class="literal">user.name</code>, <code class="literal">user.home</code>, and <code class="literal">user.dir</code>. As you’ll see later, these
restrictions are implemented by a <code class="literal">SecurityManager</code> object.</p><p>Your application can set system properties with the static method
<code class="literal">System.setProperty()</code> . You can also
set your own system properties when you run the Java interpreter, using
the <code class="literal">-D</code> option:</p><a id="I_11_tt740"/><pre class="programlisting"> <code class="o">%</code> <strong class="userinput"><code><code class="n">java</code> <code class="o">-</code><code class="n">Dfoo</code><code class="o">=</code><code class="n">bar</code> <code class="o">-</code><code class="n">Dcat</code><code class="o">=</code><code class="n">Boojum</code> <code class="n">MyApp</code></code></strong></pre><p>Because it is common to use system properties to provide
parameters such as numbers and colors, Java provides some convenience
routines for retrieving property values and parsing them into their
appropriate types. The classes <code class="literal">Boolean</code>, <code class="literal">Integer</code>, <code class="literal">Long</code>, and <code class="literal">Color</code> each come with a “get” method that looks
up and parses a system property. For example, <code class="literal">Integer.getInteger("foo")</code> looks for a system
property called <code class="literal">foo</code> and then returns
it as an <code class="literal">Integer</code>.<a id="I_indexterm11_id747978" class="indexterm"/><a id="I_indexterm11_id747985" class="indexterm"/><a id="I_indexterm11_id747992" class="indexterm"/></p></div></div></body></html>