|
1 /* |
|
2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Landmark store manager for handling landmark stores |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 package com.nokia.mj.impl.location; |
|
20 |
|
21 |
|
22 import com.nokia.mj.impl.location.NativeError; |
|
23 import java.util.Vector; |
|
24 import java.io.IOException; |
|
25 |
|
26 import javax.microedition.location.LandmarkStore; |
|
27 import com.nokia.mj.impl.rt.support.Finalizer; |
|
28 |
|
29 |
|
30 /** |
|
31 * Landmark store manager for handling landmark stores |
|
32 * |
|
33 * This class provides functionalities to open, create and delete landmark |
|
34 * stores. The class is a singleton instance which can be access using |
|
35 * the getInstance() method from everywhere and any time possible. |
|
36 */ |
|
37 public class LandmarkStoreManager |
|
38 { |
|
39 // Singleton instance for this class |
|
40 private static LandmarkStoreManager sInstance; |
|
41 |
|
42 // Landmark store map |
|
43 private final LandmarkStoreMap iStoreMap; |
|
44 |
|
45 // Handle to this class' native peer |
|
46 private final int iManagerHandle; |
|
47 |
|
48 // Handle to native Function source |
|
49 private final int iFunctionSourceHandle; |
|
50 |
|
51 private Finalizer mFinalizer; |
|
52 |
|
53 // Error messages |
|
54 private static final String LANDMARKSTORE_OPERATION_ERROR |
|
55 = "Unable to do landmarkStore operation"; |
|
56 |
|
57 private static final String LIST_LANDMARK_STORES_ERROR |
|
58 = "Unable to list landmarkStores: "; |
|
59 |
|
60 /** |
|
61 * Returns an instance from this class |
|
62 */ |
|
63 public static synchronized LandmarkStoreManager getInstance() |
|
64 { |
|
65 // Method level synhronization makes this thread-safe |
|
66 if (sInstance == null) |
|
67 { |
|
68 sInstance = new LandmarkStoreManager(); |
|
69 } |
|
70 return sInstance; |
|
71 } |
|
72 |
|
73 /** |
|
74 * Hidden constructor. Creates an instance from this class |
|
75 * the constructor also creates the native side peer object |
|
76 */ |
|
77 private LandmarkStoreManager() |
|
78 { |
|
79 // Register this object for finalization |
|
80 mFinalizer = registerForFinalization(); |
|
81 // Create native peer |
|
82 iFunctionSourceHandle = |
|
83 LAPIManager.getInstance().getFunctionSourceHandle(); |
|
84 iManagerHandle = _createNativePeer(iFunctionSourceHandle); |
|
85 // Check if the creation failed and throw error |
|
86 if (iManagerHandle < NativeError.KErrNone) |
|
87 { |
|
88 throw new OutOfMemoryError(LANDMARKSTORE_OPERATION_ERROR); |
|
89 } |
|
90 |
|
91 iStoreMap = new LandmarkStoreMap(); |
|
92 } |
|
93 |
|
94 Finalizer registerForFinalization() |
|
95 { |
|
96 return new Finalizer() |
|
97 { |
|
98 public void finalizeImpl() |
|
99 { |
|
100 doFinalize(); |
|
101 } |
|
102 }; |
|
103 |
|
104 } |
|
105 |
|
106 /** |
|
107 * Disposes the LandmarkStore Manager native peer, if the handles are valid. |
|
108 * Invalid (negative) handles indicate that their creation failed in |
|
109 * the first place. |
|
110 */ |
|
111 final void doFinalize() |
|
112 { |
|
113 _dispose(iFunctionSourceHandle, iManagerHandle); |
|
114 } |
|
115 |
|
116 /** |
|
117 * Returns an opened store. null is returned if the specified store |
|
118 * has not been opened yet. Stores can be opened using openStore() method |
|
119 * |
|
120 * @param aLocator The locator indicating where the store is. null locator |
|
121 * is interpreted as the default store |
|
122 * @return The opened landmark store instance |
|
123 */ |
|
124 public LandmarkStore getStore(Locator aLocator) |
|
125 { |
|
126 String uri = aLocator != null ? aLocator.getStoreURI() : ""; |
|
127 return iStoreMap.getStore(uri); |
|
128 } |
|
129 |
|
130 /** |
|
131 * Registers an opened landmark store to this manager |
|
132 * |
|
133 * @param aStore The store which is to be registered |
|
134 * @param aStoreUri The uri of the registered store. Note that |
|
135 * this cannot acquired from the store object because |
|
136 * getURI() method must be package private |
|
137 */ |
|
138 public void registerStore(LandmarkStore aStore, String aStoreUri) |
|
139 { |
|
140 iStoreMap.registerStore(aStore, aStoreUri); |
|
141 } |
|
142 |
|
143 /** |
|
144 * Opens a landmark store. The invocation calls native side landmark store |
|
145 * manager to open a specific landmark store. If the locator provides a |
|
146 * null URI, the default store will be opened. Otherwise a named store will |
|
147 * be opened if it is available |
|
148 * |
|
149 * @param aLocator The locator indicating where the store is |
|
150 * @return Handle to the native side landmark store peer object |
|
151 */ |
|
152 public int openStore(Locator aLocator) |
|
153 { |
|
154 String uri = aLocator != null ? aLocator.getStoreURI() : null; |
|
155 // Open the native side landmark store |
|
156 int handle = _openStore(iFunctionSourceHandle, iManagerHandle, uri); |
|
157 // return the handle to the caller which is responsible for |
|
158 // interpreting possible errors when opening the store |
|
159 return handle; |
|
160 } |
|
161 |
|
162 /** |
|
163 * Creates a landmark store. The invocation calls native side landmark store |
|
164 * manager to create a specific landmark store. The URI must not be null |
|
165 * |
|
166 * @param aLocator The locator indicating where the store is |
|
167 * @return NativeError.KErrNone if no error occured. Otherwise one of the |
|
168 * system-wide error codes |
|
169 */ |
|
170 public int createStore(Locator aLocator) |
|
171 { |
|
172 if (aLocator == null) |
|
173 { |
|
174 throw new NullPointerException(); |
|
175 } |
|
176 |
|
177 String uri = aLocator.getStoreURI(); |
|
178 // Create the store to the native database |
|
179 return _createStore(iFunctionSourceHandle, iManagerHandle, uri); |
|
180 } |
|
181 |
|
182 /** |
|
183 * Deletes a landmark store. The invocation calls native side landmark store |
|
184 * manager to delete a specific landmark store. The URI must not be null. |
|
185 * Note that all landmarks and categories will be removed from this store |
|
186 * |
|
187 * Note that this does not dispose the native side object. It only closes |
|
188 * the store so the store must be disposed separately an informed to this |
|
189 * class. |
|
190 * |
|
191 * @param aLocator The locator indicating where the store is |
|
192 * @return NativeError.KErrNone if no error occured. Otherwise one of the |
|
193 * system-wide error codes |
|
194 */ |
|
195 public int deleteStore(Locator aLocator) |
|
196 { |
|
197 if (aLocator == null) |
|
198 { |
|
199 throw new NullPointerException(); |
|
200 } |
|
201 |
|
202 String uri = aLocator.getStoreURI(); |
|
203 // Unregister the landmark store if there is an open store. This |
|
204 // quarantees that the closed store will not be provided to any |
|
205 // requesting client |
|
206 iStoreMap.unregisterStore(uri); |
|
207 |
|
208 // Delete the store from the native database |
|
209 return _deleteStore(iFunctionSourceHandle, iManagerHandle, uri); |
|
210 } |
|
211 |
|
212 /** |
|
213 * Removes a native side landmark store peer object from this class |
|
214 * @param aStoreHandle A handle to the store which is to be removed |
|
215 */ |
|
216 public void removeStore(String aStoreUri, int aStoreHandle) |
|
217 { |
|
218 // Unregister the landmark store if there is an open store. This |
|
219 // quarantees that the closed store will not be provided to any |
|
220 // requesting client. Store URI must not be null. |
|
221 // "" indicates the default store |
|
222 if (aStoreUri != null) |
|
223 { |
|
224 iStoreMap.unregisterStore(aStoreUri); |
|
225 } |
|
226 |
|
227 _removeStore(iFunctionSourceHandle, iManagerHandle, aStoreHandle); |
|
228 } |
|
229 |
|
230 /** |
|
231 * Lists the landmark stores in the device. The store names are returned |
|
232 * as a vector holding Locator objects. The names can be acquired using |
|
233 * Locator.getName() method |
|
234 * |
|
235 * @return Vector holding the list of landmark stores in the device |
|
236 */ |
|
237 public Vector listStores() throws IOException |
|
238 { |
|
239 int[] errors = new int[1]; |
|
240 // Get store unified resource identifiers from the native |
|
241 String[] storeUris = _listStores(iFunctionSourceHandle, iManagerHandle, |
|
242 errors); |
|
243 // Check for errors and throw an IOException if something went wrong |
|
244 NativeError.checkIO(errors[0], LIST_LANDMARK_STORES_ERROR); |
|
245 |
|
246 Vector locators = null; |
|
247 // Create locator list from the stores |
|
248 if (storeUris != null && storeUris.length > 0) |
|
249 { |
|
250 locators = new Vector(storeUris.length); |
|
251 for (int i = 0; i < storeUris.length; i++) |
|
252 { |
|
253 // Create a new locator explicitly using the constuctor since |
|
254 // the URIs from the native side are already valid ones |
|
255 try |
|
256 { |
|
257 Locator locator = new Locator(storeUris[i]); |
|
258 locators.addElement(locator); |
|
259 } |
|
260 catch (IllegalArgumentException e) |
|
261 { |
|
262 // Ignore invalid store URIs |
|
263 } |
|
264 } |
|
265 } |
|
266 // Return the list of store locators. null indicates that there are no |
|
267 // stores in the device |
|
268 return locators; |
|
269 } |
|
270 |
|
271 /** |
|
272 * Creates the native peer for this object |
|
273 * @param aEventSourceHandle Handle to event source |
|
274 * @retutn Handle to the native side peer object |
|
275 */ |
|
276 private native int _createNativePeer(int aEventSourceHandle); |
|
277 |
|
278 /** |
|
279 * Opens a native side landmark store |
|
280 * @param aEventSourceHandle Handle to event source |
|
281 * @param aManagerHandle Handle to the landmark store manager |
|
282 * @param aURI Unified Resource Locator pointing where the store is |
|
283 * @return Handle to the opened store. NativeError.KErrNotFound is returned |
|
284 * if the specified store does not exist |
|
285 */ |
|
286 private native int _openStore(int aEventSourceHandle, int aManagerHandle, |
|
287 String aURI); |
|
288 |
|
289 /** |
|
290 * Creates a new landmark store to the native side |
|
291 * @param aEventSourceHandle Handle to event source |
|
292 * @param aManagerHandle Handle to the landmark store manager |
|
293 * @param aURI Unified Resource Locator pointing where the store is |
|
294 * @return NativeError.KErrNone if the was no error. Otherwise, one of the |
|
295 * system wide error codes |
|
296 */ |
|
297 private native int _createStore(int aEventSourceHandle, int aManagerHandle, |
|
298 String aURI); |
|
299 |
|
300 /** |
|
301 * Deletes an existing native landmark database |
|
302 * @param aEventSourceHandle Handle to event source |
|
303 * @param aManagerHandle Handle to the landmark store manager |
|
304 * @param aURI Unified Resource Locator pointing where the store is |
|
305 * @return NativeError.KErrNone if the was no error. Otherwise, one of the |
|
306 * system wide error codes |
|
307 */ |
|
308 private native int _deleteStore(int aEventSourceHandle, int aManagerHandle, |
|
309 String aURI); |
|
310 |
|
311 /** |
|
312 * Removes a landmark store native side peer object from this class |
|
313 * If the specified store was not found this call is simply ignored |
|
314 * @param aEventSourceHandle Handle to event source |
|
315 * @param aManagerHandle Handle to the landmark store manager |
|
316 * @param aStoreHandle Handle to the store which should be removed |
|
317 */ |
|
318 private native void _removeStore(int aEventSourceHandle, |
|
319 int aManagerHandle, int aStoreHandle); |
|
320 |
|
321 /** |
|
322 * Returns a list of landmark store uris |
|
323 * @param aEventSourceHandle Handle to event source |
|
324 * @param aManagerHandle Handle to the landmark store manager |
|
325 * @param aErrors Error array. On return, contains the occured errors |
|
326 * @return Array holding the uris of the native landmark databases |
|
327 */ |
|
328 private native String[] _listStores(int aEventSourceHandle, |
|
329 int aManagerHandle, int[] aErrors); |
|
330 |
|
331 /** |
|
332 * Disposes this object native side peer |
|
333 * @param aEventSourceHandle Handle to the event source |
|
334 * @param aManagerHandle Handle to the native side peer object |
|
335 */ |
|
336 private native void _dispose(int aEventSourceHandle, int aManagerHandle); |
|
337 } |
|
338 |
|
339 // End of file |