1 /******************************************************************
3 * Copyright 2015 Samsung Electronics All Rights Reserved.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
19 ******************************************************************/
21 package org.iotivity.service.client;
23 import org.iotivity.service.RcsDestroyedObjectException;
24 import org.iotivity.service.RcsException;
25 import org.iotivity.service.RcsIllegalStateException;
26 import org.iotivity.service.RcsObject;
27 import org.iotivity.service.RcsPlatformException;
28 import org.iotivity.service.RcsResourceAttributes;
29 import org.iotivity.service.RcsValue;
33 * This represents a remote resource and provides simple ways to interact with
35 * Basically this is a client of a remote resource that runs on other device.
37 * The class supports features to help get information of a remote resource
38 * such as monitoring and caching.
40 * @see RcsDiscoveryManager
43 public final class RcsRemoteResourceObject extends RcsObject {
45 private native boolean nativeIsMonitoring();
47 private native boolean nativeIsCaching();
49 private native boolean nativeIsObservable();
51 private native void nativeStartMonitoring(OnStateChangedListener listener);
53 private native void nativeStopMonitoring();
55 private native ResourceState nativeGetState();
57 private native void nativeStartCaching(OnCacheUpdatedListener listener);
59 private native void nativeStopCaching();
61 private native CacheState nativeGetCacheState();
63 private native boolean nativeIsCachedAvailable();
65 private native RcsResourceAttributes nativeGetCachedAttributes();
67 private native void nativeGetRemoteAttributes(
68 OnRemoteAttributesReceivedListener listener);
70 private native void nativeSetRemoteAttributes(
71 RcsResourceAttributes attributes,
72 OnRemoteAttributesReceivedListener listener);
74 private native String nativeGetUri();
76 private native String nativeGetAddress();
78 private native String[] nativeGetTypes();
80 private native String[] nativeGetInterfaces();
82 private RcsRemoteResourceObject() {
86 * This represents states of monitoring.
88 * @see #startMonitoring(OnStateChangedListener)
90 * @see OnStateChangedListener
93 public enum ResourceState {
94 /** Monitoring is not started. */
98 * Monitoring is started and checking state is in progress.
99 * This is the default state after startMonitoring.
103 /** The resource is alive. */
106 /** Failed to reach the resource. */
109 /** The resource is deleted. */
114 * This represents states of caching.
116 * @see #startCaching()
117 * @see #getCacheState()
119 public enum CacheState {
120 /** Caching is not started. */
124 * Caching is started, but the data is not ready yet. This is
125 * the default state after startCaching.
129 /** The data is ready. */
132 /** Failed to reach the resource. */
137 * Interface definition for a callback to be invoked when the cache is
140 * @see #startCaching(OnCacheUpdatedListener)
142 public interface OnCacheUpdatedListener {
145 * Called when the cache is updated.
148 * the updated attributes
151 public void onCacheUpdated(RcsResourceAttributes attributes, int eCode);
156 * Interface definition for a callback to be invoked when the response of
157 * getRemoteAttributes and setRemoteAttributes is received.
159 * @see #getRemoteAttributes(OnRemoteAttributesReceivedListener)
160 * @see #setRemoteAttributes(RcsResourceAttributes,
161 * OnRemoteAttributesReceivedListener)
163 public interface OnRemoteAttributesReceivedListener {
166 * Called when a response for the getRemoteAttributes request or
167 * setRemoteAttributes request is received.
170 * the resource attributes received from the remote resource
173 public void onAttributesReceived(RcsResourceAttributes attributes,
179 * Interface definition for a callback to be invoked when the monitoring
182 * @see #startMonitoring(OnStateChangedListener)
184 public interface OnStateChangedListener {
187 * Called when the monitoring state is changed.
189 * @param resourceState
193 public void onStateChanged(ResourceState resourceState);
196 private void assertAlive() throws RcsException {
198 throw new RcsDestroyedObjectException(
199 "The object is already destroyed!");
204 * Returns whether monitoring is enabled.
206 * @return true if monitoring the resource.
208 * @throws RcsDestroyedObjectException
209 * if the object is already destroyed
211 * @see #startMonitoring(OnStateChangedListener)
213 public boolean isMonitoring() throws RcsException {
215 return nativeIsMonitoring();
219 * Returns whether caching is enabled.
221 * @return true if caching the resource.
223 * @throws RcsDestroyedObjectException
224 * if the object is already destroyed
226 * @see #startCaching()
227 * @see #startCaching(OnCacheUpdatedListener)
230 public boolean isCaching() throws RcsException {
232 return nativeIsCaching();
236 * Returns whether resource is observable.
238 * @return true if resource is observable.
240 * @throws RcsDestroyedObjectException
241 * if the object is already destroyed
243 * @see org.iotivity.service.server.RcsResourceObject.Builder#setObservable(boolean)
245 public boolean isObservable() throws RcsException {
247 return nativeIsObservable();
251 * Starts monitoring the resource.
253 * Monitoring provides a feature to check the presence of a resource, even
254 * when the server is not announcing Presence using startPresnece.
257 * the listener to receive new state.
259 * @throws NullPointerException
260 * if listener is null
261 * @throws RcsIllegalStateException
262 * if monitoring is already started
263 * @throws RcsDestroyedObjectException
264 * if the object is already destroyed
267 * @see #isMonitoring()
268 * @see #stopMonitoring()
270 public void startMonitoring(OnStateChangedListener listener)
271 throws RcsException {
273 if (listener == null) {
274 throw new NullPointerException("listener is null.");
277 nativeStartMonitoring(listener);
281 * Stops monitoring the resource.
283 * It does nothing if monitoring is not started.
285 * @throws RcsDestroyedObjectException
286 * if the object is already destroyed
288 * @see #startMonitoring(OnStateChangedListener)
289 * @see #isMonitoring()
291 public void stopMonitoring() throws RcsException {
293 nativeStopMonitoring();
297 * Returns the current state of the resource.
299 * @return ResourceState - current resource state
301 * @throws RcsDestroyedObjectException
302 * if the object is already destroyed
304 * @see #startMonitoring(OnStateChangedListener)
305 * @see #isMonitoring()
306 * @see OnStateChangedListener
308 public ResourceState getState() throws RcsException {
310 return nativeGetState();
314 * Starts caching attributes of the resource.
316 * This will start data caching for the resource. Once caching started it
317 * will look for the data updation on the resource and updates the cache
320 * It is equivalent to calling {@link #startCaching(OnCacheUpdatedListener)}
323 * @throws RcsDestroyedObjectException
324 * if the object is already destroyed
326 * @see #startCaching(OnCacheUpdatedListener)
328 * @see #getCacheState()
329 * @see #getCachedAttribute(String)
330 * @see #getCachedAttributes()
331 * @see OnCacheUpdatedListener
333 public void startCaching() throws RcsException {
339 * Starts caching attributes of the resource.
341 * This will start data caching for the resource. Once caching started it
342 * will look for the data updation on the resource and updates the cache
346 * the listener to be notified when attributes are updated or
349 * @throws RcsDestroyedObjectException
350 * if the object is already destroyed
352 * @see #startCaching()
354 * @see #getCacheState()
355 * @see #getCachedAttribute(String)
356 * @see #getCachedAttributes()
357 * @see OnCacheUpdatedListener
359 public void startCaching(OnCacheUpdatedListener listener)
360 throws RcsException {
362 nativeStartCaching(listener);
368 * It does nothing if caching is not started.
370 * @throws RcsDestroyedObjectException
371 * if the object is already destroyed
373 * @see #startCaching()
374 * @see #startCaching(OnCacheUpdatedListener)
378 public void stopCaching() throws RcsException {
384 * Returns the current cache state.
386 * @return current cache state.
388 * @throws RcsDestroyedObjectException
389 * if the object is already destroyed
391 * @see #startCaching()
392 * @see #startCaching(OnCacheUpdatedListener)
395 public CacheState getCacheState() throws RcsException {
397 return nativeGetCacheState();
401 * Returns whether cached data is available.
403 * Cache will be available always once cache state had been
404 * {@link CacheState#READY} even if current state is
405 * {@link CacheState#LOST_SIGNAL} until stopped.
407 * @return true if cache data is available.
409 * @throws RcsDestroyedObjectException
410 * if the object is already destroyed
412 * @see #startCaching()
413 * @see #startCaching(OnCacheUpdatedListener)
415 * @see #getCacheState()
418 public boolean isCachedAvailable() throws RcsException {
420 return nativeIsCachedAvailable();
424 * Returns the cached attributes.
426 * Note that this works only when cache is available.
428 * @return the cached attributes.
430 * @throws RcsIllegalStateException
431 * if cache is not available
432 * @throws RcsDestroyedObjectException
433 * if the object is already destroyed
435 * @see #startCaching()
436 * @see #startCaching(OnCacheUpdatedListener)
438 * @see #getCacheState()
439 * @see #isCachedAvailable()
440 * @see #getCachedAttribute(String)
443 public RcsResourceAttributes getCachedAttributes() throws RcsException {
445 return nativeGetCachedAttributes();
449 * Returns the cached value to which the specified key is mapped, or null if
450 * no mapping for the key.
452 * Note that this works only when cache is available.
455 * the key whose associated value is to be returned
457 * @return the value to which the specified key is mapped, or null if no
458 * mapping for the key
460 * @throws NullPointerException
462 * @throws RcsIllegalStateException
463 * if cache is not available
464 * @throws RcsDestroyedObjectException
465 * if the object is already destroyed
467 * @see #startCaching()
468 * @see #startCaching(OnCacheUpdatedListener)
470 * @see #getCacheState()
471 * @see #isCachedAvailable()
472 * @see #getCachedAttributes()
475 public RcsValue getCachedAttribute(String key) throws RcsException {
478 throw new NullPointerException("key is null.");
481 return getCachedAttributes().get(key);
485 * Sends a request for the resource attributes directly to the resource.
488 * the listener to receive the response
490 * @throws NullPointerException
491 * if listener is null
492 * @throws RcsDestroyedObjectException
493 * if the object is already destroyed
494 * @throws RcsPlatformException
495 * if the operation failed
497 * @see OnRemoteAttributesReceivedListener
499 public void getRemoteAttributes(OnRemoteAttributesReceivedListener listener)
500 throws RcsException {
502 if (listener == null) {
503 throw new NullPointerException("listener is null.");
506 nativeGetRemoteAttributes(listener);
510 * Sends a set request with resource attributes to the resource.
512 * The SetRequest behavior depends on the server, whether updating its
516 * attributes to set for the remote resource.
518 * @throws NullPointerException
519 * if attributes or listener is null
520 * @throws RcsDestroyedObjectException
521 * if the object is already destroyed
522 * @throws RcsPlatformException
523 * if the operation failed
525 * @see OnRemoteAttributesReceivedListener
527 public void setRemoteAttributes(RcsResourceAttributes attributes,
528 OnRemoteAttributesReceivedListener listener) throws RcsException {
531 if (attributes == null) {
532 throw new NullPointerException("attributes is null.");
534 if (listener == null) {
535 throw new NullPointerException("listener is null.");
538 nativeSetRemoteAttributes(attributes, listener);
542 * Returns the uri of the resource.
544 * @return uri of the resource
546 * @throws RcsDestroyedObjectException
547 * if the object is already destroyed
549 public String getUri() throws RcsException {
551 return nativeGetUri();
555 * Returns the address of the resource .
557 * @return address of the resource
559 * @throws RcsDestroyedObjectException
560 * if the object is already destroyed
562 public String getAddress() throws RcsException {
564 return nativeGetAddress();
568 * Returns the resource types of the resource.
570 * @return resource types
572 * @throws RcsDestroyedObjectException
573 * if the object is already destroyed
575 public String[] getTypes() throws RcsException {
577 return nativeGetTypes();
581 * Returns the resource interfaces of the resource.
583 * @return resource interfaces
585 * @throws RcsDestroyedObjectException
586 * if the object is already destroyed
588 public String[] getInterfaces() throws RcsException {
590 return nativeGetInterfaces();
594 * Reclaims all resources used by this object.
595 * This must be called if the resource is not used any longer.
598 public void destroy() {