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