Source for gnu.java.util.prefs.gconf.GConfNativePeer

   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<String> 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<String> 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<String> 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<String> 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: }