ucar.util.prefs
Class XMLStore

java.lang.Object
  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