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 * An OnGetListener can be registered via the resource get call.
578 * Event listeners are notified asynchronously
580 public interface OnGetListener {
581 public void onGetCompleted(List<OcHeaderOption> headerOptionList,
582 OcRepresentation ocRepresentation);
584 public void onGetFailed(Throwable ex);
588 * An OnPutListener can be registered via the resource put call.
589 * Event listeners are notified asynchronously
591 public interface OnPutListener {
592 public void onPutCompleted(List<OcHeaderOption> headerOptionList,
593 OcRepresentation ocRepresentation);
595 public void onPutFailed(Throwable ex);
599 * An OnPostListener can be registered via the resource post call.
600 * Event listeners are notified asynchronously
602 public interface OnPostListener {
603 public void onPostCompleted(List<OcHeaderOption> headerOptionList,
604 OcRepresentation ocRepresentation);
606 public void onPostFailed(Throwable ex);
610 * An OnDeleteListener can be registered via the resource delete call.
611 * Event listeners are notified asynchronously
613 public interface OnDeleteListener {
614 public void onDeleteCompleted(List<OcHeaderOption> headerOptionList);
616 public void onDeleteFailed(Throwable ex);
620 * An OnObserveListener can be registered via the resource observe call.
621 * Event listeners are notified asynchronously
623 public interface OnObserveListener {
627 public static final int REGISTER = 0;
631 public static final int DEREGISTER = 1;
635 public static final int NO_OPTION = 2;
637 public void onObserveCompleted(List<OcHeaderOption> headerOptionList,
638 OcRepresentation ocRepresentation,
641 public void onObserveFailed(Throwable ex);
645 protected void finalize() throws Throwable {
651 private native void dispose();
653 private long mNativeHandle;
656 * Method to discovery Topics
658 * @param queryParamsMap map which can have the query parameter name and value
659 * @param onTopicFoundListener event handler The handler method will be invoked with a map
660 * of attribute name and values.
661 * @param qualityOfService the quality of communication.
662 * @throws OcException
664 public void discoveryMQTopics(Map<String, String> queryParamsMap,
665 OnMQTopicFoundListener onTopicFoundListener,
666 QualityOfService qualityOfService) throws OcException {
668 if (qualityOfService == null) {
669 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
672 this.discoveryMQTopicsImpl(queryParamsMap, onTopicFoundListener,
673 qualityOfService.getValue());
676 private synchronized native void discoveryMQTopicsImpl(
677 Map<String, String> queryParamsMap,
678 OnMQTopicFoundListener onTopicFoundListener,
679 int qualityOfService) throws OcException;
682 * Method to create Topic into MQ Brober.
684 * @param ocRepresentation representation of the MQ Broker.
685 * @param uri new MQ Topic uri which want to create.
686 * @param queryParamsMap map which can have the query parameter name and value.
687 * @param onTopicCreatedListener event handler The handler method will be invoked with a map
688 * of attribute name and values.
689 * @param qualityOfService the quality of communication.
690 * @throws OcException
692 public void createMQTopic(OcRepresentation ocRepresentation,
694 Map<String, String> queryParamsMap,
695 OnMQTopicCreatedListener onTopicCreatedListener,
696 QualityOfService qualityOfService) throws OcException {
698 if (qualityOfService == null) {
699 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
702 this.createMQTopicImpl(ocRepresentation, uri, queryParamsMap,
703 onTopicCreatedListener, qualityOfService.getValue());
706 private synchronized native void createMQTopicImpl(
707 OcRepresentation ocRepresentation,
709 Map<String, String> queryParamsMap,
710 OnMQTopicCreatedListener onTopicCreatedListener,
711 int qualityOfService) throws OcException;
714 * Method to set subscribe on the Topic.
716 * @param queryParamsMap map which can have the query parameter name and value.
717 * @param onObserveListener event handler The handler method will be invoked with a map
718 * of attribute name and values.
719 * @param qualityOfService the quality of communication.
720 * @throws OcException
722 public void subscribeMQTopic(Map<String, String> queryParamsMap,
723 OnObserveListener onObserveListener,
724 QualityOfService qualityOfService) throws OcException {
726 if (qualityOfService == null) {
727 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
730 this.subscribeMQTopicImpl(queryParamsMap,
732 qualityOfService.getValue());
735 private synchronized native void subscribeMQTopicImpl(Map<String, String> queryParamsMap,
736 OnObserveListener onObserveListener,
737 int qualityOfService) throws OcException;
740 * Method to cancel the observation on the Topic.
742 * @param qualityOfService the quality of communication.
743 * @throws OcException
745 public void unsubscribeMQTopic(QualityOfService qualityOfService) throws OcException{
747 if (qualityOfService == null) {
748 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
751 this.unsubscribeMQTopicImpl(qualityOfService.getValue());
754 private native void unsubscribeMQTopicImpl(
755 int qualityOfService) throws OcException;
758 * Method to requestMQPublish on a Topic
760 * @param queryParamsMap Map which can have the query parameter name and value
761 * @param onPostListener event handler The event handler will be invoked with a map of
762 * attribute name and values.
763 * @param qualityOfService the quality of communication.
764 * @throws OcException
766 public void requestMQPublish(Map<String, String> queryParamsMap,
767 OnPostListener onPostListener,
768 QualityOfService qualityOfService) throws OcException {
770 if (qualityOfService == null) {
771 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
774 this.requestMQPublishImpl(queryParamsMap,
776 qualityOfService.getValue());
779 private native void requestMQPublishImpl(Map<String, String> queryParamsMap,
780 OnPostListener onPostListener,
781 int qualityOfService) throws OcException;
784 * Method to publishMQTopic on a Topic
786 * @param ocRepresentation representation of the resource
787 * @param queryParamsMap Map which can have the query parameter name and value
788 * @param onPostListener event handler The event handler will be invoked with a map of
789 * attribute name and values.
790 * @param qualityOfService the quality of communication.
791 * @throws OcException
793 public void publishMQTopic(OcRepresentation ocRepresentation,
794 Map<String, String> queryParamsMap,
795 OnPostListener onPostListener,
796 QualityOfService qualityOfService) throws OcException {
798 if (qualityOfService == null) {
799 throw new OcException(ErrorCode.INVALID_PARAM, "qualityOfService cannot be null");
802 this.publishMQTopicImpl(ocRepresentation,
805 qualityOfService.getValue());
808 private native void publishMQTopicImpl(OcRepresentation ocRepresentation,
809 Map<String, String> queryParamsMap,
810 OnPostListener onPostListener,
811 int qualityOfService) throws OcException;
814 * An OnMQTopicFoundListener can be registered via the OcResource.discoveryMQTopics call.
815 * Event listeners are notified asynchronously
817 public interface OnMQTopicFoundListener {
818 public void onTopicDiscoveried(OcResource resource);
819 public void onDiscoveryTopicFailed(Throwable ex, String uri);
823 * An OnMQTopicCreatedListener can be registered via the OcResource.createMQTopic call.
824 * Event listeners are notified asynchronously
826 public interface OnMQTopicCreatedListener {
827 public void onTopicResourceCreated(OcResource resource);
828 public void onCreateTopicFailed(Throwable ex, String uri);
832 * An OnMQTopicSubscribeListener can be registered via the OcResource.subscribeMQTopic call.
833 * Event listeners are notified asynchronously
835 public interface OnMQTopicSubscribeListener {
839 public static final int SUBSCRIBER = 0;
843 public static final int UNSUBSCRIBER = 1;
847 public static final int NO_OPTION = 2;
848 public void onSubScribeCompleted(List<OcHeaderOption> headerOptionList,
849 OcRepresentation ocRepresentation,
851 public void onUnsubScribeCompleted(OcRepresentation ocRepresentation,
853 public void onSubScribeFailed(Throwable ex);