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    * Creates a new instance of GConfNativePeer
  53    */
  54   public GConfNativePeer()
  55   {
  56     init_class();
  57   }
  58
  59   /**
  60    * Queries whether the node <code>node</code> exists in theGConf database.
  61    * Returns <code>true</code> or <code>false</code>.
  62    *
  63    * @param node the node to check.
  64    */
  65   public boolean nodeExist(String node)
  66   {
  67     return gconf_dir_exists(node);
  68   }
  69
  70   /**
  71    * Change the value of key to val. Automatically creates the key if it didn't
  72    * exist before (ie it was unset or it only had a default value).
  73    * Key names must be valid GConf key names, that is, there can be more
  74    * restrictions than for normal Preference Backend.
  75    *
  76    * @param key the key to alter (or add).
  77    * @param value the new value for this key.
  78    * @return true if the key was updated, false otherwise.
  79    */
  80   public boolean setString(String key, String value)
  81   {
  82     return gconf_set_string(key, value);
  83   }
  84
  85   /**
  86    * Unsets the value of key; if key is already unset, has no effect. Depending
  87    * on the GConf daemon, unsetting a key may have the side effect to remove it
  88    * completely form the database.
  89    *
  90    * @param key the key to unset.
  91    * @return true on success, false if the key was not updated.
  92    */
  93   public boolean unset(String key)
  94   {
  95     return gconf_unset(key);
  96   }
  97
  98   /**
  99    * Gets the value of a configuration key.
 100    *
 101    * @param key the configuration key.
 102    * @return the values of this key, null if the key is not valid.
 103    */
 104   public String getKey(String key)
 105   {
 106     return gconf_get_string(key);
 107   }
 108
 109   /**
 110    * Lists the key in the given node. Does not list subnodes. Keys names are the
 111    * stripped names (name relative to the current node) of the keys stored in
 112    * this node.
 113    *
 114    * @param node the node where keys are stored.
 115    * @return a java.util.List of keys. If there are no keys in the given node, a
 116    *         list of size 0 is returned.
 117    */
 118   public List<String> getKeys(String node) throws BackingStoreException
 119   {
 120     return gconf_all_keys(node);
 121   }
 122
 123   /**
 124    * Lists the subnodes in <code>node</code>. The returned list contains
 125    * allocated strings. Each string is the name relative tho the given node.
 126    *
 127    * @param node the node to get subnodes from. If there are no subnodes in the
 128    *          given node, a list of size 0 is returned.
 129    */
 130   public List<String> getChildrenNodes(String node) throws BackingStoreException
 131   {
 132     return gconf_all_nodes(node);
 133   }
 134
 135   /**
 136    * Escape the given string so the it is a valid GConf name.
 137    */
 138   public static String escapeString(String plain)
 139   {
 140     return gconf_escape_key(plain);
 141   }
 142
 143   /**
 144    * Unescape a string escaped with {@link #escapeString}.
 145    */
 146   public static String unescapeString(String escaped)
 147   {
 148     return gconf_unescape_key(escaped);
 149   }
 150
 151   /**
 152    * Suggest to the backend GConf daemon to synch with the database.
 153    */
 154   public void suggestSync() throws BackingStoreException
 155   {
 156     gconf_suggest_sync();
 157   }
 158
 159   protected void finalize() throws Throwable
 160   {
 161     try
 162       {
 163         finalize_class();
 164       }
 165     finally
 166       {
 167         super.finalize();
 168       }
 169   }
 170
 171   /* ***** native methods ***** */
 172
 173   /*
 174    * Basicly, these are one to one mappings to GConfClient functions.
 175    * GConfClient instances are handled by the native layer, and are hidden from
 176    * the main java class.
 177    */
 178
 179   /**
 180    * Initialize the GConf native peer and enable the object cache.
 181    * It is meant to be used by the static initializer.
 182    */
 183   native synchronized static final private void init_id_cache();
 184
 185   /**
 186    * Initialize the GConf native peer. This is meant to be used by the
 187    * class constructor.
 188    */
 189   native synchronized static final private void init_class();
 190
 191   /**
 192    * Class finalizer.
 193    */
 194   native synchronized static final private void finalize_class();
 195
 196   /**
 197    * Queries the GConf database to see if the given node exists, returning
 198    * true if the node exist, false otherwise.
 199    *
 200    * @param node the node to query for existence.
 201    * @return true if the node exist, false otherwise.
 202    */
 203   native synchronized
 204   static final protected boolean gconf_dir_exists(String node);
 205
 206   /**
 207    * Sets the given key/value pair into the GConf database.
 208    * The key must be a valid GConf key.
 209    *
 210    * @param key the key to store in the GConf database
 211    * @param value the value to associate to the given key.
 212    * @return true if the change has effect, false otherwise.
 213    */
 214   native synchronized
 215   static final protected boolean gconf_set_string(String key, String value);
 216
 217   /**
 218    * Returns the key associated to the given key. Null is returned if the
 219    * key is not valid.
 220    *
 221    * @param key the key to return the value of.
 222    * @return The value associated to the given key, or null.
 223    */
 224   native synchronized
 225   static final protected String gconf_get_string(String key);
 226
 227   /**
 228    * Usets the given key, removing the key from the database.
 229    *
 230    * @param key the key to remove.
 231    * @return true if the operation success, false otherwise.
 232    */
 233   native synchronized static final protected boolean gconf_unset(String key);
 234
 235   /**
 236    * Suggest to the GConf native peer a sync with the database.
 237    *
 238    */
 239   native synchronized static final protected void gconf_suggest_sync()
 240     throws BackingStoreException;
 241
 242   /**
 243    * Returns a list of all nodes under the given node.
 244    *
 245    * @param node the source node.
 246    * @return A list of nodes under the given source node.
 247    */
 248   native
 249   static synchronized final protected List<String> gconf_all_nodes(String node)
 250     throws BackingStoreException;
 251
 252   /**
 253    * Returns a list of all keys stored in the given node.
 254    *
 255    * @param node the source node.
 256    * @return A list of all keys stored in the given node.
 257    */
 258   native synchronized
 259   static final protected List<String> gconf_all_keys(String node)
 260     throws BackingStoreException;
 261
 262   /**
 263    * Escape the input String so that it's a valid element for GConf.
 264    *
 265    * @param plain the String to escape.
 266    * @return An escaped String for use with GConf.
 267    */
 268   native synchronized
 269   static final protected String gconf_escape_key(String plain);
 270
 271   /**
 272    * Converts a string escaped with gconf_escape_key back into its
 273    * original form.
 274    *
 275    * @param escaped key as returned by gconf_escape_key
 276    * @return An unescaped key.
 277    */
 278   native synchronized
 279   static final protected String gconf_unescape_key(String escaped);
 280
 281   static
 282     {
 283       System.loadLibrary("gconfpeer");
 284       init_id_cache();
 285     }
 286 }