ucar.util.prefs
Class XMLStore

java.lang.Object
  extended by ucar.util.prefs.XMLStore

public class XMLStore
extends Object

This implements an XML-based backing store for PreferencesExt. XMLStores can be chained together to provide independent collections of "stored defaults", eg store1 -> store2 -> store3. In this case, a call to getXXX( key) first looks in store1, and if not found, then in store2, etc. A call to putXXX(key, value) first checks to see if the (key, value) pair already exists in any of the chained stores; if not, then it is added to store1. Normally, only store1 would be changed and saved.

A chain of stored defaults might look like:

 try {
   XMLStore store3 = XMLStore.createFromResource("/auxdata/system.xml", null);
   XMLStore store2 = XMLStore.createFromFile("/usr/local/metapps/GDV/site.xml", store3);
   XMLStore store1 = XMLStore.createFromFile("/home/username/.GDV/user.xml", store2);
   PreferencesExt prefs = store1.getPreferences();
 } catch (IOException e) {
   System.out.println("XMLStore Creation failed "+e);
 }
 
If you plan to call Preferences.userRoot(), you must explicilty set it, eg:
   PreferencesExt.setUserRoot( prefs);
 

Before exiting the application, in order to save changes, you must call:

 try {
   store1.save();
 } catch (IOException e) {
   System.out.println("XMLStore Save failed "+e);
 }
  

Author:
John Caron
See Also:
PreferencesExt, Preferences

Constructor Summary
XMLStore()
           
 
Method Summary
static XMLStore createFromFile(String fileName, XMLStore storedDefaults)
          Create an XMLStore reading from the specified filename.
static XMLStore createFromInputStream(InputStream is1, InputStream is2, XMLStore storedDefaults)
          Create an XMLStore reading from an input stream.
static XMLStore createFromResource(String resourceName, XMLStore storedDefaults)
          Create a read-only XMLStore reading from the specified resource, opened as a Resource stream using the XMLStore ClassLoader.
 PreferencesExt getPreferences()
          Get the root Preferences node.
static String makeStandardFilename(String appName, String storeName)
          Convenience routine for creating an XMLStore file in a standard place.
 void save()
          Save the current state of the Preferences tree to disk, using the original filename.
 void save(OutputStream out)
          Save the current state of the Preferences tree to the given OutputStream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLStore

public XMLStore()
Method Detail

createFromFile

public static XMLStore createFromFile(String fileName,
                                      XMLStore storedDefaults)
                               throws IOException
Create an XMLStore reading from the specified filename.

Parameters:
fileName - The XMLStore is stored in this files.
storedDefaults - This contains the "stored defaults", or null if none.
Returns:
new XMLStore object
Throws:
IOException - on error

createFromInputStream

public static XMLStore createFromInputStream(InputStream is1,
                                             InputStream is2,
                                             XMLStore storedDefaults)
                                      throws IOException
Create an XMLStore reading from an input stream. Because of some peculiariteis, you must open the input stream wtice, and pass both in.

Parameters:
is1 - the first copy of the input stream.
is2 - the second copy of the input stream.
storedDefaults - This contains the "stored defaults", or null if none.
Returns:
new XMLStore object
Throws:
IOException - on error

createFromResource

public static XMLStore createFromResource(String resourceName,
                                          XMLStore storedDefaults)
                                   throws IOException
Create a read-only XMLStore reading from the specified resource, opened as a Resource stream using the XMLStore ClassLoader. This allows you to find files that are in jar files on the application CLASSPATH.

Parameters:
resourceName - The XMLStore is stored in this resource. By convention it has .xml suffix.
storedDefaults - This contains the "stored defaults", or null if none.
Returns:
new XMLStore object
Throws:
IOException - if Resource not found or error reading it

makeStandardFilename

public static String makeStandardFilename(String appName,
                                          String storeName)
Convenience routine for creating an XMLStore file in a standard place.

Initialize:

  1. $user.home = System.getProperty("user.home"), if not exist, use "."
  2. create directory "$(user_home)/appName/" , if not exist, create it
  3. return "$(user_home)/appName/storeName" for use in createFromFile()

Parameters:
appName - application name
storeName - store name
Returns:
standard file name

getPreferences

public PreferencesExt getPreferences()
Get the root Preferences node. All manipulation is done through it.


save

public void save()
          throws IOException
Save the current state of the Preferences tree to disk, using the original filename. The XMLStore must have been constructed from a writeable XML file.

Throws:
UnsupportedOperationException: - if XMLStore was created from createFromResource.
IOException - on read error

save

public void save(OutputStream out)
          throws IOException
Save the current state of the Preferences tree to the given OutputStream.

Throws:
IOException


Copyright © 1999-2011 UCAR/Unidata. All Rights Reserved.