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    */
GConfNativePeer()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    */
nodeExist(String node)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    */
setString(String key, String value)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    */
unset(String key)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    */
getKey(String key)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    */
getKeys(String node)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    */
getChildrenNodes(String node)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    */
escapeString(String plain)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    */
unescapeString(String escaped)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    */
suggestSync()154   public void suggestSync() throws BackingStoreException
155   {
156     gconf_suggest_sync();
157   }
158 
finalize()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    */
init_id_cache()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    */
init_class()189   native synchronized static final private void init_class();
190 
191   /**
192    * Class finalizer.
193    */
finalize_class()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
gconf_dir_exists(String node)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
gconf_set_string(String key, String value)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
gconf_get_string(String key)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    */
gconf_unset(String key)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    */
gconf_suggest_sync()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
gconf_all_nodes(String node)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
gconf_all_keys(String node)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
gconf_escape_key(String plain)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
gconf_unescape_key(String escaped)279   static final protected String gconf_unescape_key(String escaped);
280 
281   static
282     {
283       System.loadLibrary("gconfpeer");
init_id_cache()284       init_id_cache();
285     }
286 }
287