2 *******************************************************************
4 * Copyright 2015 Intel Corporation.
6 *-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
8 * Licensed under the Apache License, Version 2.0 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
20 *-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
23 package org.iotivity.base;
25 import java.util.EnumSet;
26 import java.util.List;
30 * OcResource represents an OC resource. A resource could be a light controller, temperature sensor,
31 * smoke detector, etc. A resource comes with a well-defined contract or interface onto which you
32 * can perform different operations, such as turning on the light, getting the current temperature
33 * or subscribing for event notifications from the smoke detector. A resource can be composed of
34 * one or more resources.
36 public class OcResource {
37 public static final String CREATED_URI_KEY = "createduri";
39 private OcResource(long nativeHandle) {
40 this.mNativeHandle = nativeHandle;
44 * Method to get the attributes of a resource.
46 * @param queryParamsMap map which can have the query parameter name and value
47 * @param onGetListener The event handler will be invoked with a map of attribute name and
48 * values. The event handler will also have the result from this Get
49 * operation This will have error codes
50 * @throws OcException if failure
52 public native void get(Map<String, String> queryParamsMap,
53 OnGetListener onGetListener) throws OcException;
56 * Method to get the attributes of a resource.
58 * @param queryParamsMap map which can have the query parameter name and value
59 * @param onGetListener The event handler will be invoked with a map of attribute name and
60 * values. The event handler will also have the result from this Get
61 * operation This will have error codes
62 * @param qualityOfService the quality of communication
63 * @throws OcException if failure
65 public void get(Map<String, String> queryParamsMap,
66 OnGetListener onGetListener,
67 QualityOfService qualityOfService) throws OcException {
69 if (qualityOfService == null) {
70 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
73 this.get1(queryParamsMap, onGetListener, qualityOfService.getValue());
76 private native void get1(Map<String, String> queryParamsMap,
77 OnGetListener onGetListener,
78 int qualityOfService) throws OcException;
81 * Method to get the attributes of a resource.
83 * @param resourceType resourceType of the resource to operate on
84 * @param resourceInterface interface type of the resource to operate on
85 * @param queryParamsMap map which can have the query parameter name and value
86 * @param onGetListener The event handler will be invoked with a map of attribute name and
87 * values. The event handler will also have the result from this Get
88 * operation This will have error codes
89 * @throws OcException if failure
91 public void get(String resourceType,
92 String resourceInterface,
93 Map<String, String> queryParamsMap,
94 OnGetListener onGetListener) throws OcException {
102 private native void get2(String resourceType,
103 String resourceInterface,
104 Map<String, String> queryParamsMap,
105 OnGetListener onGetListener) throws OcException;
108 * Method to get the attributes of a resource.
110 * @param resourceType resourceType of the resource to operate on
111 * @param resourceInterface interface type of the resource to operate on
112 * @param queryParamsMap map which can have the query parameter name and value
113 * @param onGetListener The event handler will be invoked with a map of attribute name and
114 * values. The event handler will also have the result from this Get
115 * operation This will have error codes
116 * @param qualityOfService the quality of communication
117 * @throws OcException if failure
119 public void get(String resourceType,
120 String resourceInterface,
121 Map<String, String> queryParamsMap,
122 OnGetListener onGetListener,
123 QualityOfService qualityOfService) throws OcException {
125 if (qualityOfService == null) {
126 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
134 qualityOfService.getValue());
137 private native void get3(String resourceType,
138 String resourceInterface,
139 Map<String, String> queryParamsMap,
140 OnGetListener onGetListener,
141 int qualityOfService) throws OcException;
144 * Method to set the representation of a resource (via PUT)
146 * @param representation representation of the resource
147 * @param queryParamsMap Map which can have the query parameter name and value
148 * @param onPutListener event handler The event handler will be invoked with a map of attribute
150 * @throws OcException if failure
152 public native void put(OcRepresentation representation,
153 Map<String, String> queryParamsMap,
154 OnPutListener onPutListener) throws OcException;
157 * Method to set the representation of a resource (via PUT)
159 * @param ocRepresentation representation of the resource
160 * @param queryParamsMap Map which can have the query parameter name and value
161 * @param onPutListener event handler The event handler will be invoked with a map of
162 * attribute name and values.
163 * @param qualityOfService the quality of communication
164 * @throws OcException if failure
166 public void put(OcRepresentation ocRepresentation,
167 Map<String, String> queryParamsMap,
168 OnPutListener onPutListener,
169 QualityOfService qualityOfService) throws OcException {
171 if (qualityOfService == null) {
172 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
179 qualityOfService.getValue());
182 private native void put1(OcRepresentation ocRepresentation,
183 Map<String, String> queryParamsMap,
184 OnPutListener onPutListener,
185 int qualityOfService) throws OcException;
188 * Method to set the representation of a resource (via PUT)
190 * @param resourceType resource type of the resource to operate on
191 * @param resourceInterface interface type of the resource to operate on
192 * @param ocRepresentation representation of the resource
193 * @param queryParamsMap Map which can have the query parameter name and value
194 * @param onPutListener event handler The event handler will be invoked with a map of
195 * attribute name and values.
196 * @throws OcException if failure
198 public void put(String resourceType,
199 String resourceInterface,
200 OcRepresentation ocRepresentation,
201 Map<String, String> queryParamsMap,
202 OnPutListener onPutListener) throws OcException {
211 private native void put2(String resourceType,
212 String resourceInterface,
213 OcRepresentation ocRepresentation,
214 Map<String, String> queryParamsMap,
215 OnPutListener onPutListener) throws OcException;
218 * Method to set the representation of a resource (via PUT)
220 * @param resourceType resource type of the resource to operate on
221 * @param resourceInterface interface type of the resource to operate on
222 * @param ocRepresentation representation of the resource
223 * @param queryParamsMap Map which can have the query parameter name and value
224 * @param onPutListener event handler The event handler will be invoked with a map of
225 * attribute name and values.
226 * @param qualityOfService the quality of communication
227 * @throws OcException if failure
229 public void put(String resourceType,
230 String resourceInterface,
231 OcRepresentation ocRepresentation,
232 Map<String, String> queryParamsMap,
233 OnPutListener onPutListener,
234 QualityOfService qualityOfService) throws OcException {
236 if (qualityOfService == null) {
237 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
246 qualityOfService.getValue());
249 private native void put3(String resourceType,
250 String resourceInterface,
251 OcRepresentation ocRepresentation,
252 Map<String, String> queryParamsMap,
253 OnPutListener onPutListener,
254 int qualityOfService) throws OcException;
257 * Method to POST on a resource
259 * @param ocRepresentation representation of the resource
260 * @param queryParamsMap Map which can have the query parameter name and value
261 * @param onPostListener event handler The event handler will be invoked with a map of
262 * attribute name and values.
263 * @throws OcException if failure
265 public native void post(OcRepresentation ocRepresentation,
266 Map<String, String> queryParamsMap,
267 OnPostListener onPostListener) throws OcException;
270 * Method to POST on a resource
272 * @param ocRepresentation representation of the resource
273 * @param queryParamsMap Map which can have the query parameter name and value
274 * @param onPostListener event handler The event handler will be invoked with a map of
275 * attribute name and values.
276 * @param qualityOfService the quality of communication
277 * @throws OcException if failure
279 public void post(OcRepresentation ocRepresentation,
280 Map<String, String> queryParamsMap,
281 OnPostListener onPostListener,
282 QualityOfService qualityOfService) throws OcException {
284 if (qualityOfService == null) {
285 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
292 qualityOfService.getValue());
295 private native void post1(OcRepresentation ocRepresentation,
296 Map<String, String> queryParamsMap,
297 OnPostListener onPostListener,
298 int qualityOfService) throws OcException;
301 * Method to POST on a resource
303 * @param resourceType resource type of the resource to operate on
304 * @param resourceInterface interface type of the resource to operate on
305 * @param ocRepresentation representation of the resource
306 * @param queryParamsMap Map which can have the query parameter name and value
307 * @param onPostListener event handler The event handler will be invoked with a map of
308 * attribute name and values.
309 * @throws OcException if failure
311 public void post(String resourceType,
312 String resourceInterface,
313 OcRepresentation ocRepresentation,
314 Map<String, String> queryParamsMap,
315 OnPostListener onPostListener) throws OcException {
324 private native void post2(String resourceType,
325 String resourceInterface,
326 OcRepresentation ocRepresentation,
327 Map<String, String> queryParamsMap,
328 OnPostListener onPostListener) throws OcException;
331 * Method to POST on a resource
333 * @param resourceType resource type of the resource to operate on
334 * @param resourceInterface interface type of the resource to operate on
335 * @param ocRepresentation representation of the resource
336 * @param queryParamsMap Map which can have the query parameter name and value
337 * @param onPostListener event handler The event handler will be invoked with a map of
338 * attribute name and values.
339 * @param qualityOfService the quality of communication
340 * @throws OcException
342 public void post(String resourceType,
343 String resourceInterface,
344 OcRepresentation ocRepresentation,
345 Map<String, String> queryParamsMap,
346 OnPostListener onPostListener,
347 QualityOfService qualityOfService) throws OcException {
349 if (qualityOfService == null) {
350 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
359 qualityOfService.getValue());
362 private native void post3(String resourceType,
363 String resourceInterface,
364 OcRepresentation ocRepresentation,
365 Map<String, String> queryParamsMap,
366 OnPostListener onPostListener,
367 int qualityOfService) throws OcException;
370 * Method to perform DELETE operation
372 * @param onDeleteListener event handler The event handler will have headerOptionList
374 public native void deleteResource(OnDeleteListener onDeleteListener) throws OcException;
377 * Method to perform DELETE operation
379 * @param onDeleteListener event handler The event handler will have headerOptionList
380 * @param qualityOfService the quality of communication
382 public void deleteResource(OnDeleteListener onDeleteListener,
383 QualityOfService qualityOfService) throws OcException {
385 if (qualityOfService == null) {
386 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
389 this.deleteResource1(onDeleteListener,
390 qualityOfService.getValue());
393 private native void deleteResource1(OnDeleteListener onDeleteListener,
394 int qualityOfService) throws OcException;
397 * Method to set observation on the resource
399 * @param observeType allows the client to specify how it wants to observe
400 * @param queryParamsMap map which can have the query parameter name and value
401 * @param onObserveListener event handler The handler method will be invoked with a map
402 * of attribute name and values.
403 * @throws OcException
405 public void observe(ObserveType observeType,
406 Map<String, String> queryParamsMap,
407 OnObserveListener onObserveListener) throws OcException {
409 if (observeType == null) {
410 throw new OcException(ErrorCode.INVALID_PARAM, "observeType cannot be null");
414 observeType.getValue(),
419 private synchronized native void observe(int observeType,
420 Map<String, String> queryParamsMap,
421 OnObserveListener onObserveListener) throws OcException;
424 * Method to set observation on the resource
426 * @param observeType allows the client to specify how it wants to observe
427 * @param queryParamsMap map which can have the query parameter name and value
428 * @param onObserveListener event handler The handler method will be invoked with a map
429 * of attribute name and values.
430 * @param qualityOfService the quality of communication
431 * @throws OcException
433 public void observe(ObserveType observeType,
434 Map<String, String> queryParamsMap,
435 OnObserveListener onObserveListener,
436 QualityOfService qualityOfService) throws OcException {
438 if (observeType == null) {
439 throw new OcException(ErrorCode.INVALID_PARAM, "observeType cannot be null");
442 if (qualityOfService == null) {
443 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
447 observeType.getValue(),
450 qualityOfService.getValue());
453 private synchronized native void observe1(int observeType,
454 Map<String, String> queryParamsMap,
455 OnObserveListener onObserveListener,
456 int qualityOfService) throws OcException;
459 * Method to cancel the observation on the resource
461 * @throws OcException
463 public void cancelObserve() throws OcException{
464 this.cancelObserve(OcPlatform.getPlatformQualityOfService());
468 * Method to cancel the observation on the resource
470 * @param qualityOfService the quality of communication
471 * @throws OcException
473 public void cancelObserve(QualityOfService qualityOfService) throws OcException {
475 if (qualityOfService == null) {
476 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
479 this.cancelObserve1(qualityOfService.getValue());
482 private native void cancelObserve1(int qualityOfService) throws OcException;
485 * Method to set header options
487 * @param headerOptionList List<OcHeaderOption> where header information(header optionID and
488 * optionData is passed
489 * @throws OcException
491 public void setHeaderOptions(List<OcHeaderOption> headerOptionList) throws OcException {
493 if (headerOptionList == null) {
494 throw new OcException(ErrorCode.INVALID_PARAM, "headerOptionList cannot be null");
497 this.setHeaderOptions(headerOptionList.toArray(
498 new OcHeaderOption[headerOptionList.size()])
502 private native void setHeaderOptions(OcHeaderOption[] headerOptionList);
505 * Method to unset header options
507 public native void unsetHeaderOptions();
510 * Method to get the host address of this resource
512 * @return host address NOTE: This might or might not be exposed in future due to
515 public native String getHost();
518 * Method to get the URI for this resource
520 * @return resource URI
522 public native String getUri();
525 * Method to get the connectivity type of this resource
527 * @return EnumSet<OcConnectivityType></OcConnectivityType> connectivity type set
529 public EnumSet<OcConnectivityType> getConnectivityTypeSet() {
530 return OcConnectivityType.convertToEnumSet(
531 this.getConnectivityTypeN()
535 private native int getConnectivityTypeN();
538 * Method to provide ability to check if this resource is observable or not
540 * @return true indicates resource is observable; false indicates resource is not observable
542 public native boolean isObservable();
545 * Method to get the list of resource types
547 * @return List of resource types
549 public native List<String> getResourceTypes();
552 * Method to get the list of resource interfaces
554 * @return List of resource interface
556 public native List<String> getResourceInterfaces();
559 * Method to get a unique identifier for this resource across network interfaces. This will
560 * be guaranteed unique for every resource-per-server independent of how this was discovered.
562 * @return OcResourceIdentifier object, which can be used for all comparison and hashing
564 public native OcResourceIdentifier getUniqueIdentifier();
567 * Method to get a string representation of the resource's server ID.
569 * This is unique per- server independent on how it was discovered.
574 public native String getServerId();
577 * Method to get a string representation of the human friendly name defined by the vendor.
579 * @return human friendly name
581 public native String getDeviceName();
584 * An OnGetListener can be registered via the resource get call.
585 * Event listeners are notified asynchronously
587 public interface OnGetListener {
588 public void onGetCompleted(List<OcHeaderOption> headerOptionList,
589 OcRepresentation ocRepresentation);
591 public void onGetFailed(Throwable ex);
595 * An OnPutListener can be registered via the resource put call.
596 * Event listeners are notified asynchronously
598 public interface OnPutListener {
599 public void onPutCompleted(List<OcHeaderOption> headerOptionList,
600 OcRepresentation ocRepresentation);
602 public void onPutFailed(Throwable ex);
606 * An OnPostListener can be registered via the resource post call.
607 * Event listeners are notified asynchronously
609 public interface OnPostListener {
610 public void onPostCompleted(List<OcHeaderOption> headerOptionList,
611 OcRepresentation ocRepresentation);
613 public void onPostFailed(Throwable ex);
617 * An OnDeleteListener can be registered via the resource delete call.
618 * Event listeners are notified asynchronously
620 public interface OnDeleteListener {
621 public void onDeleteCompleted(List<OcHeaderOption> headerOptionList);
623 public void onDeleteFailed(Throwable ex);
627 * An OnObserveListener can be registered via the resource observe call.
628 * Event listeners are notified asynchronously
630 public interface OnObserveListener {
634 public static final int REGISTER = 0;
638 public static final int DEREGISTER = 1;
642 public static final int NO_OPTION = 2;
644 public void onObserveCompleted(List<OcHeaderOption> headerOptionList,
645 OcRepresentation ocRepresentation,
648 public void onObserveFailed(Throwable ex);
652 protected void finalize() throws Throwable {
658 private native void dispose();
660 private long mNativeHandle;
663 * Method to discovery Topics
665 * @param queryParamsMap map which can have the query parameter name and value
666 * @param onTopicFoundListener event handler The handler method will be invoked with a map
667 * of attribute name and values.
668 * @param qualityOfService the quality of communication.
669 * @throws OcException
671 public void discoveryMQTopics(Map<String, String> queryParamsMap,
672 OnMQTopicFoundListener onTopicFoundListener,
673 QualityOfService qualityOfService) throws OcException {
675 if (qualityOfService == null) {
676 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
679 this.discoveryMQTopicsImpl(queryParamsMap, onTopicFoundListener,
680 qualityOfService.getValue());
683 private synchronized native void discoveryMQTopicsImpl(
684 Map<String, String> queryParamsMap,
685 OnMQTopicFoundListener onTopicFoundListener,
686 int qualityOfService) throws OcException;
689 * Method to create Topic into MQ Brober.
691 * @param ocRepresentation representation of the MQ Broker.
692 * @param uri new MQ Topic uri which want to create.
693 * @param queryParamsMap map which can have the query parameter name and value.
694 * @param onTopicCreatedListener event handler The handler method will be invoked with a map
695 * of attribute name and values.
696 * @param qualityOfService the quality of communication.
697 * @throws OcException
699 public void createMQTopic(OcRepresentation ocRepresentation,
701 Map<String, String> queryParamsMap,
702 OnMQTopicCreatedListener onTopicCreatedListener,
703 QualityOfService qualityOfService) throws OcException {
705 if (qualityOfService == null) {
706 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
709 this.createMQTopicImpl(ocRepresentation, uri, queryParamsMap,
710 onTopicCreatedListener, qualityOfService.getValue());
713 private synchronized native void createMQTopicImpl(
714 OcRepresentation ocRepresentation,
716 Map<String, String> queryParamsMap,
717 OnMQTopicCreatedListener onTopicCreatedListener,
718 int qualityOfService) throws OcException;
721 * Method to set subscribe on the Topic.
723 * @param queryParamsMap map which can have the query parameter name and value.
724 * @param onObserveListener event handler The handler method will be invoked with a map
725 * of attribute name and values.
726 * @param qualityOfService the quality of communication.
727 * @throws OcException
729 public void subscribeMQTopic(Map<String, String> queryParamsMap,
730 OnObserveListener onObserveListener,
731 QualityOfService qualityOfService) throws OcException {
733 if (qualityOfService == null) {
734 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
737 this.subscribeMQTopicImpl(queryParamsMap,
739 qualityOfService.getValue());
742 private synchronized native void subscribeMQTopicImpl(Map<String, String> queryParamsMap,
743 OnObserveListener onObserveListener,
744 int qualityOfService) throws OcException;
747 * Method to cancel the observation on the Topic.
749 * @param qualityOfService the quality of communication.
750 * @throws OcException
752 public void unsubscribeMQTopic(QualityOfService qualityOfService) throws OcException{
754 if (qualityOfService == null) {
755 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
758 this.unsubscribeMQTopicImpl(qualityOfService.getValue());
761 private native void unsubscribeMQTopicImpl(
762 int qualityOfService) throws OcException;
765 * Method to requestMQPublish on a Topic
767 * @param queryParamsMap Map which can have the query parameter name and value
768 * @param onPostListener event handler The event handler will be invoked with a map of
769 * attribute name and values.
770 * @param qualityOfService the quality of communication.
771 * @throws OcException
773 public void requestMQPublish(Map<String, String> queryParamsMap,
774 OnPostListener onPostListener,
775 QualityOfService qualityOfService) throws OcException {
777 if (qualityOfService == null) {
778 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
781 this.requestMQPublishImpl(queryParamsMap,
783 qualityOfService.getValue());
786 private native void requestMQPublishImpl(Map<String, String> queryParamsMap,
787 OnPostListener onPostListener,
788 int qualityOfService) throws OcException;
791 * Method to publishMQTopic on a Topic
793 * @param ocRepresentation representation of the resource
794 * @param queryParamsMap Map which can have the query parameter name and value
795 * @param onPostListener event handler The event handler will be invoked with a map of
796 * attribute name and values.
797 * @param qualityOfService the quality of communication.
798 * @throws OcException
800 public void publishMQTopic(OcRepresentation ocRepresentation,
801 Map<String, String> queryParamsMap,
802 OnPostListener onPostListener,
803 QualityOfService qualityOfService) throws OcException {
805 if (qualityOfService == null) {
806 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
809 this.publishMQTopicImpl(ocRepresentation,
812 qualityOfService.getValue());
815 private native void publishMQTopicImpl(OcRepresentation ocRepresentation,
816 Map<String, String> queryParamsMap,
817 OnPostListener onPostListener,
818 int qualityOfService) throws OcException;
821 * An OnMQTopicFoundListener can be registered via the OcResource.discoveryMQTopics call.
822 * Event listeners are notified asynchronously
824 public interface OnMQTopicFoundListener {
825 public void onTopicDiscoveried(OcResource resource);
826 public void onDiscoveryTopicFailed(Throwable ex, String uri);
830 * An OnMQTopicCreatedListener can be registered via the OcResource.createMQTopic call.
831 * Event listeners are notified asynchronously
833 public interface OnMQTopicCreatedListener {
834 public void onTopicResourceCreated(OcResource resource);
835 public void onCreateTopicFailed(Throwable ex, String uri);
839 * An OnMQTopicSubscribeListener can be registered via the OcResource.subscribeMQTopic call.
840 * Event listeners are notified asynchronously
842 public interface OnMQTopicSubscribeListener {
846 public static final int SUBSCRIBER = 0;
850 public static final int UNSUBSCRIBER = 1;
854 public static final int NO_OPTION = 2;
855 public void onSubScribeCompleted(List<OcHeaderOption> headerOptionList,
856 OcRepresentation ocRepresentation,
858 public void onUnsubScribeCompleted(OcRepresentation ocRepresentation,
860 public void onSubScribeFailed(Throwable ex);