libjava/classpath/gnu/java/util/prefs/gconf/GConfNativePeer.java

   1 /* GConfNativePeer.java -- GConf based preference peer for native methods
   2  Copyright (C) 2006 Free Software Foundation, Inc.
   3
   4  This file is part of GNU Classpath.
   5
   6  GNU Classpath is free software; you can redistribute it and/or modify
   7  it under the terms of the GNU General Public License as published by
   8  the Free Software Foundation; either version 2, or (at your option)
   9  any later version.
  10
  11  GNU Classpath is distributed in the hope that it will be useful, but
  12  WITHOUT ANY WARRANTY; without even the implied warranty of
  13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  General Public License for more details.
  15
  16  You should have received a copy of the GNU General Public License
  17  along with GNU Classpath; see the file COPYING.  If not, write to the
  18  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19  02110-1301 USA.
  20
  21  Linking this library statically or dynamically with other modules is
  22  making a combined work based on this library.  Thus, the terms and
  23  conditions of the GNU General Public License cover the whole
  24  combination.
  25
  26  As a special exception, the copyright holders of this library give you
  27  permission to link this library with independent modules to produce an
  28  executable, regardless of the license terms of these independent
  29  modules, and to copy and distribute the resulting executable under
  30  terms of your choice, provided that you also meet, for each linked
  31  independent module, the terms and conditions of the license of that
  32  module.  An independent module is a module which is not derived from
  33  or based on this library.  If you modify this library, you may extend
  34  this exception to your version of the library, but you are not
  35  obligated to do so.  If you do not wish to do so, delete this
  36  exception statement from your version. */
  37
  38
  39 package gnu.java.util.prefs.gconf;
  40
  41 import java.util.List;
  42 import java.util.prefs.BackingStoreException;
  43
  44 /**
  45  * Native peer for GConf based preference backend.
  46  *
  47  * @author Mario Torre <neugens@limasoftware.net>
  48  */
  49 public final class GConfNativePeer
  50 {
  51   /**
  52    * Object to achieve locks for methods that need to be synchronized.
  53    */
  54   private static final Object[] semaphore = new Object[0];
  55
  56   /**
  57    * Creates a new instance of GConfNativePeer
  58    */
  59   public GConfNativePeer()
  60   {
  61     synchronized (semaphore)
  62       {
  63         init_class();
  64       }
  65   }
  66
  67   /**
  68    * Queries whether the node <code>node</code> exists in theGConf database.
  69    * Returns <code>true</code> or <code>false</code>.
  70    *
  71    * @param node the node to check.
  72    */
  73   public boolean nodeExist(String node)
  74   {
  75     return gconf_client_dir_exists(node);
  76   }
  77
  78   /**
  79    * Add the node <code>node</code> to the list of nodes the GConf will watch.
  80    * An event is raised everytime this node is changed. You can add a node
  81    * multiple times.
  82    *
  83    * @param node the node to track.
  84    */
  85   public void startWatchingNode(String node)
  86   {
  87     gconf_client_add_dir(node);
  88   }
  89
  90   /**
  91    * Remove the node <code>node</code> to the list of nodes the GConf is
  92    * watching. Note that if a node has been added multiple times, you must
  93    * remove it the same number of times before the remove takes effect.
  94    *
  95    * @param node the node you don't want to track anymore.
  96    */
  97   public void stopWatchingNode(String node)
  98   {
  99     gconf_client_remove_dir(node);
 100   }
 101
 102   /**
 103    * Change the value of key to val. Automatically creates the key if it didn't
 104    * exist before (ie it was unset or it only had a default value).
 105    * Key names must be valid GConf key names, that is, there can be more
 106    * restrictions than for normal Preference Backend.
 107    *
 108    * @param key the key to alter (or add).
 109    * @param value the new value for this key.
 110    * @return true if the key was updated, false otherwise.
 111    */
 112   public boolean setString(String key, String value)
 113   {
 114     return gconf_client_set_string(key, value);
 115   }
 116
 117   /**
 118    * Unsets the value of key; if key is already unset, has no effect. Depending
 119    * on the GConf daemon, unsetting a key may have the side effect to remove it
 120    * completely form the database.
 121    *
 122    * @param key the key to unset.
 123    * @return true on success, false if the key was not updated.
 124    */
 125   public boolean unset(String key)
 126   {
 127     return gconf_client_unset(key);
 128   }
 129
 130   /**
 131    * Gets the value of a configuration key.
 132    *
 133    * @param key the configuration key.
 134    * @return the values of this key, null if the key is not valid.
 135    */
 136   public String getKey(String key)
 137   {
 138     return gconf_client_get_string(key);
 139   }
 140
 141   /**
 142    * Lists the key in the given node. Does not list subnodes. Keys names are the
 143    * stripped names (name relative to the current node) of the keys stored in
 144    * this node.
 145    *
 146    * @param node the node where keys are stored.
 147    * @return a java.util.List of keys. If there are no keys in the given node, a
 148    *         list of size 0 is returned.
 149    */
 150   public List getKeys(String node) throws BackingStoreException
 151   {
 152     return gconf_client_all_keys(node);
 153   }
 154
 155   /**
 156    * Lists the subnodes in <code>node</code>. The returned list contains
 157    * allocated strings. Each string is the name relative tho the given node.
 158    *
 159    * @param node the node to get subnodes from. If there are no subnodes in the
 160    *          given node, a list of size 0 is returned.
 161    */
 162   public List getChildrenNodes(String node) throws BackingStoreException
 163   {
 164     return gconf_client_all_nodes(node);
 165   }
 166
 167   /**
 168    * Escape the given string so the it is a valid GConf name.
 169    */
 170   public static String escapeString(String plain)
 171   {
 172     return gconf_escape_key(plain);
 173   }
 174
 175   /**
 176    * Unescape a string escaped with {@link #escapeString}.
 177    */
 178   public static String unescapeString(String escaped)
 179   {
 180     return gconf_unescape_key(escaped);
 181   }
 182
 183   /**
 184    * Suggest to the backend GConf daemon to synch with the database.
 185    */
 186   public void suggestSync() throws BackingStoreException
 187   {
 188     gconf_client_suggest_sync();
 189   }
 190
 191   protected void finalize() throws Throwable
 192   {
 193     try
 194       {
 195         synchronized (semaphore)
 196           {
 197             finalize_class();
 198           }
 199       }
 200     finally
 201       {
 202         super.finalize();
 203       }
 204   }
 205
 206   /* ***** native methods ***** */
 207
 208   /*
 209    * Basicly, these are one to one mappings to GConfClient functions.
 210    * GConfClient instances are handled by the native layer, and are hidden from
 211    * the main java class.
 212    */
 213
 214   /**
 215    * Initialize the GConf native peer and enable the object cache.
 216    * It is meant to be used by the static initializer.
 217    */
 218   native static final private void init_id_cache();
 219
 220   /**
 221    * Initialize the GConf native peer. This is meant to be used by the
 222    * class constructor.
 223    */
 224   native static final private void init_class();
 225
 226   /**
 227    * Class finalizer.
 228    */
 229   native static final private void finalize_class();
 230
 231   /**
 232    * Queries the GConf database to see if the given node exists, returning
 233    * true if the node exist, false otherwise.
 234    *
 235    * @param node the node to query for existence.
 236    * @return true if the node exist, false otherwise.
 237    */
 238   native static final protected boolean gconf_client_dir_exists(String node);
 239
 240   /**
 241    * Adds the given node to the list of nodes that GConf watches for
 242    * changes.
 243    *
 244    * @param node the node to watch for changes.
 245    */
 246   native static final protected void gconf_client_add_dir(String node);
 247
 248   /**
 249    * Removes the given node from the list of nodes that GConf watches for
 250    * changes.
 251    *
 252    * @param node the node to remove from from the list of watched nodes.
 253    */
 254   native static final protected void gconf_client_remove_dir(String node);
 255
 256   /**
 257    * Sets the given key/value pair into the GConf database.
 258    * The key must be a valid GConf key.
 259    *
 260    * @param key the key to store in the GConf database
 261    * @param value the value to associate to the given key.
 262    * @return true if the change has effect, false otherwise.
 263    */
 264   native static final protected boolean gconf_client_set_string(String key,
 265                                                                 String value);
 266
 267   /**
 268    * Returns the key associated to the given key. Null is returned if the
 269    * key is not valid.
 270    *
 271    * @param key the key to return the value of.
 272    * @return The value associated to the given key, or null.
 273    */
 274   native static final protected String gconf_client_get_string(String key);
 275
 276   /**
 277    * Usets the given key, removing the key from the database.
 278    *
 279    * @param key the key to remove.
 280    * @return true if the operation success, false otherwise.
 281    */
 282   native static final protected boolean gconf_client_unset(String key);
 283
 284   /**
 285    * Suggest to the GConf native peer a sync with the database.
 286    *
 287    */
 288   native static final protected void gconf_client_suggest_sync()
 289     throws BackingStoreException;
 290
 291   /**
 292    * Returns a list of all nodes under the given node.
 293    *
 294    * @param node the source node.
 295    * @return A list of nodes under the given source node.
 296    */
 297   native
 298   static final protected List gconf_client_all_nodes(String node)
 299     throws BackingStoreException;
 300
 301   /**
 302    * Returns a list of all keys stored in the given node.
 303    *
 304    * @param node the source node.
 305    * @return A list of all keys stored in the given node.
 306    */
 307   native
 308   static final protected List gconf_client_all_keys(String node)
 309     throws BackingStoreException;
 310
 311   /**
 312    * Escape the input String so that it's a valid element for GConf.
 313    *
 314    * @param plain the String to escape.
 315    * @return An escaped String for use with GConf.
 316    */
 317   native
 318   static final protected String gconf_escape_key(String plain);
 319
 320   /**
 321    * Converts a string escaped with gconf_escape_key back into its
 322    * original form.
 323    *
 324    * @param escaped key as returned by gconf_escape_key
 325    * @return An unescaped key.
 326    */
 327   native
 328   static final protected String gconf_unescape_key(String escaped);
 329
 330   static
 331     {
 332       System.loadLibrary("gconfpeer");
 333       init_id_cache();
 334     }
 335 }