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;
30 import org.iotivity.service.server.RcsResourceObject;
34 * This represents a remote resource and provides simple ways to interact with
36 * Basically this is a client of a remote resource that runs on other device.
38 * The class supports features to help get information of a remote resource
39 * such as monitoring and caching.
41 * @see RcsDiscoveryManager
44 public final class RcsRemoteResourceObject extends RcsObject {
46 private native boolean nativeIsMonitoring();
48 private native boolean nativeIsCaching();
50 private native boolean nativeIsObservable();
52 private native void nativeStartMonitoring(OnStateChangedListener listener);
54 private native void nativeStopMonitoring();
56 private native ResourceState nativeGetState();
58 private native void nativeStartCaching(OnCacheUpdatedListener listener);
60 private native void nativeStopCaching();
62 private native CacheState nativeGetCacheState();
64 private native boolean nativeIsCachedAvailable();
66 private native RcsResourceAttributes nativeGetCachedAttributes();
68 private native void nativeGetRemoteAttributes(
69 OnRemoteAttributesReceivedListener listener);
71 private native void nativeSetRemoteAttributes(
72 RcsResourceAttributes attributes,
73 OnRemoteAttributesReceivedListener listener);
75 private native String nativeGetUri();
77 private native String nativeGetAddress();
79 private native String[] nativeGetTypes();
81 private native String[] nativeGetInterfaces();
83 private RcsRemoteResourceObject() {
87 * This represents states of monitoring.
89 * @see #startMonitoring()
91 * @see OnStateChangedListener
94 public enum ResourceState {
96 NONE, /** < Monitoring is not started. */
98 * < Monitoring is started and checking state is in progress.
99 * This is the default state after startMonitoring.
101 ALIVE, /** < The resource is alive. */
102 LOST_SIGNAL, /** < Failed to reach the resource. */
103 DESTROYED /** < The resource is deleted. */
107 * This represents states of caching.
109 * @see #startCaching()
110 * @see #getCacheState()
112 public enum CacheState {
114 NONE, /** < Caching is not started. */
116 * < Caching is started, but the data is not ready yet. This is
117 * the default state after startCaching.
119 READY, /** < The data is ready. */
120 LOST_SIGNAL /** < Failed to reach the resource. */
124 * Interface definition for a callback to be invoked when the cache is
127 * @see #startCaching(OnCacheUpdatedListener)
129 public interface OnCacheUpdatedListener {
132 * Called when the cache is updated.
135 * the updated attributes
138 public void onCacheUpdated(RcsResourceAttributes attributes);
143 * Interface definition for a callback to be invoked when the response of
144 * getRemoteAttributes and setRemoteAttributes is received.
146 * @see #getRemoteAttributes(OnRemoteAttributesReceivedListener)
147 * @see #setRemoteAttributes(RcsResourceAttributes,
148 * OnRemoteAttributesReceivedListener)
150 public interface OnRemoteAttributesReceivedListener {
153 * Called when a response for the getRemoteAttributes request or
154 * setRemoteAttributes request is received.
157 * the resource attributes received from the remote resource
160 public void onAttributesReceived(RcsResourceAttributes attributes,
166 * Interface definition for a callback to be invoked when the monitoring
169 * @see #startMonitoring(OnStateChangedListener)
171 public interface OnStateChangedListener {
174 * Called when the monitoring state is changed.
176 * @param resourceState
180 public void onStateChanged(ResourceState resourceState);
183 private void assertAlive() throws RcsException {
185 throw new RcsDestroyedObjectException(
186 "The object is already destroyed!");
191 * Returns whether monitoring is enabled.
193 * @return true if monitoring the resource.
195 * @throws RcsDestroyedObjectException
196 * if the object is already destroyed
198 * @see #startMonitoring(OnStateChangedListener)
200 public boolean isMonitoring() throws RcsException {
202 return nativeIsMonitoring();
206 * Returns whether caching is enabled.
208 * @return true if caching the resource.
210 * @throws RcsDestroyedObjectException
211 * if the object is already destroyed
213 * @see #startCaching()
214 * @see #startCaching(OnCacheUpdatedListener)
217 public boolean isCaching() throws RcsException {
219 return nativeIsCaching();
223 * Returns whether resource is observable.
225 * @return true if resource is observable.
227 * @throws RcsDestroyedObjectException
228 * if the object is already destroyed
230 * @see RcsResourceObject.Builder#setObservable(boolean)
232 public boolean isObservable() throws RcsException {
234 return nativeIsObservable();
238 * Starts monitoring the resource.
240 * Monitoring provides a feature to check the presence of a resource, even
241 * when the server is not announcing Presence using startPresnece.
244 * the listener to receive new state.
246 * @throws NullPointerException
247 * if listener is null
248 * @throws RcsIllegalStateException
249 * if monitoring is already started
250 * @throws RcsDestroyedObjectException
251 * if the object is already destroyed
254 * @see #isMonitoring()
255 * @see #stopMonitoring()
257 public void startMonitoring(OnStateChangedListener listener)
258 throws RcsException {
260 if (listener == null) {
261 throw new NullPointerException("listener is null.");
264 nativeStartMonitoring(listener);
268 * Stops monitoring the resource.
270 * It does nothing if monitoring is not started.
272 * @throws RcsDestroyedObjectException
273 * if the object is already destroyed
275 * @see #startMonitoring(OnStateChangedListener)
276 * @see #isMonitoring()
278 public void stopMonitoring() throws RcsException {
280 nativeStopMonitoring();
284 * Returns the current state of the resource.
286 * @return ResourceState - current resource state
288 * @throws RcsDestroyedObjectException
289 * if the object is already destroyed
291 * @see #startMonitoring(OnStateChangedListener)
292 * @see #isMonitoring()
293 * @see OnStateChangedListener
295 public ResourceState getState() throws RcsException {
297 return nativeGetState();
301 * Starts caching attributes of the resource.
303 * This will start data caching for the resource. Once caching started it
304 * will look for the data updation on the resource and updates the cache
307 * It is equivalent to calling startCaching(CacheUpdatedCallback) with null.
309 * @throws RcsDestroyedObjectException
310 * if the object is already destroyed
312 * @see #startCaching(OnCacheUpdatedListener)
314 * @see #getCacheState()
315 * @see #getCachedAttribute(String)
316 * @see #getCachedAttributes()
317 * @see OnCacheUpdatedListener
319 public void startCaching() throws RcsException {
325 * Starts caching attributes of the resource.
327 * This will start data caching for the resource. Once caching started it
328 * will look for the data updation on the resource and updates the cache
332 * the listener to be notified when attributes are updated or
335 * @throws RcsDestroyedObjectException
336 * if the object is already destroyed
338 * @see #startCaching()
340 * @see #getCacheState()
341 * @see #getCachedAttribute(String)
342 * @see #getCachedAttributes()
343 * @see OnCacheUpdatedListener
345 public void startCaching(OnCacheUpdatedListener listener)
346 throws RcsException {
348 nativeStartCaching(listener);
354 * It does nothing if caching is not started.
356 * @throws RcsDestroyedObjectException
357 * if the object is already destroyed
359 * @see #startCaching()
360 * @see #startCaching(OnCacheUpdatedListener)
364 public void stopCaching() throws RcsException {
370 * Returns the current cache state.
372 * @return current cache state.
374 * @throws RcsDestroyedObjectException
375 * if the object is already destroyed
377 * @see #startCaching()
378 * @see #startCaching(OnCacheUpdatedListener)
381 public CacheState getCacheState() throws RcsException {
383 return nativeGetCacheState();
387 * Returns whether cached data is available.
389 * Cache will be available always once cache state had been READY even if
390 * current state is LOST_SIGNAL.
392 * @return true if cache data is available.
394 * @throws RcsDestroyedObjectException
395 * if the object is already destroyed
397 * @see #startCaching()
398 * @see #startCaching(OnCacheUpdatedListener)
400 * @see #getCacheState()
403 public boolean isCachedAvailable() throws RcsException {
405 return nativeIsCachedAvailable();
409 * Returns the cached attributes.
410 * This works only when cache is available.
412 * @return the cached attributes.
414 * @throws RcsIllegalStateException
415 * if cache is not available
416 * @throws RcsDestroyedObjectException
417 * if the object is already destroyed
419 * @see #startCaching()
420 * @see #startCaching(OnCacheUpdatedListener)
422 * @see #getCacheState()
423 * @see #isCachedAvailable()
424 * @see #getCachedAttribute(String)
427 public RcsResourceAttributes getCachedAttributes() throws RcsException {
429 return nativeGetCachedAttributes();
433 * Returns the cached value to which the specified key is mapped, or null if
434 * RcsResourceAttributes contains no mapping for the key.
436 * This works only when cache is available.
439 * the key whose associated value is to be returned
441 * @return the value to which the specified key is mapped, or null if no
442 * mapping for the key
444 * @throws NullPointerException
446 * @throws RcsIllegalStateException
447 * if cache is not available
448 * @throws RcsDestroyedObjectException
449 * if the object is already destroyed
451 * @see #startCaching()
452 * @see #startCaching(OnCacheUpdatedListener)
454 * @see #getCacheState()
455 * @see #isCachedAvailable()
456 * @see #getCachedAttributes()
459 public RcsValue getCachedAttribute(String key) throws RcsException {
462 throw new NullPointerException("key is null.");
465 return getCachedAttributes().get(key);
469 * Sends a request for the resource attributes directly to the server.
472 * the listener to receive the response
474 * @throws NullPointerException
475 * if listener is null
476 * @throws RcsDestroyedObjectException
477 * if the object is already destroyed
478 * @throws RcsPlatformException
479 * if the operation failed
481 * @see OnRemoteAttributesReceivedListener
483 public void getRemoteAttributes(OnRemoteAttributesReceivedListener listener)
484 throws RcsException {
486 if (listener == null) {
487 throw new NullPointerException("listener is null.");
490 nativeGetRemoteAttributes(listener);
494 * Sends a set request with resource attributes to the server.
496 * The SetRequest behavior depends on the server, whether updating its
500 * attributes to set for the remote resource.
502 * @throws NullPointerException
503 * if attributes or listener is null
504 * @throws RcsDestroyedObjectException
505 * if the object is already destroyed
506 * @throws RcsPlatformException
507 * if the operation failed
509 * @see OnRemoteAttributesReceivedListener
511 public void setRemoteAttributes(RcsResourceAttributes attributes,
512 OnRemoteAttributesReceivedListener listener) throws RcsException {
515 if (attributes == null) {
516 throw new NullPointerException("attributes is null.");
518 if (listener == null) {
519 throw new NullPointerException("listener is null.");
522 nativeSetRemoteAttributes(attributes, listener);
526 * Returns the uri of the resource.
528 * @return uri of the resource
530 * @throws RcsDestroyedObjectException
531 * if the object is already destroyed
533 public String getUri() throws RcsException {
535 return nativeGetUri();
539 * Returns the address of the resource .
541 * @return address of the resource
543 * @throws RcsDestroyedObjectException
544 * if the object is already destroyed
546 public String getAddress() throws RcsException {
548 return nativeGetAddress();
552 * Returns the resource types of the resource.
554 * @return resource types
556 * @throws RcsDestroyedObjectException
557 * if the object is already destroyed
559 public String[] getTypes() throws RcsException {
561 return nativeGetTypes();
565 * Returns the resource interfaces of the resource.
567 * @return resource interfaces
569 * @throws RcsDestroyedObjectException
570 * if the object is already destroyed
572 public String[] getInterfaces() throws RcsException {
574 return nativeGetInterfaces();
578 * Reclaims all resources used by this object.
579 * This must be called if the resource is not used any longer.
582 public void destroy() {