Commit 061c61d2 authored by Larry Sachs's avatar Larry Sachs Committed by Kishen Maloor

Adds java doc to org.iotivity.oc java classes

Signed-off-by: Larry Sachs's avatarLarry Sachs <larry.j.sachs@intel.com>
parent 108b9693
Pipeline #912 passed with stage
in 10 minutes and 7 seconds
......@@ -2,6 +2,11 @@ package org.iotivity.oc;
import org.iotivity.*;
/**
* OcCborEncoder provides methods to encode a CBOR representation.
* <p>
* All OcCborEncoder constructors are static. To close the cbor encoder, use done().
*/
public class OcCborEncoder {
private boolean isDone;
......@@ -26,6 +31,16 @@ public class OcCborEncoder {
nativeCborEncoder = nativeEncoder;
}
/**
* Returns a cbor encoder for a root or links array. Must be closed using done().
*
* @param type the EncoderType
* @return a OcCborEncoder instance
*
* @see EncoderType#ROOT
* @see EncoderType#LINKS_ARRAY
* @see OcCborEncoder#done
*/
static public OcCborEncoder createOcCborEncoder(EncoderType type) {
if (type == null) {
throw new IllegalArgumentException("EncoderType cannot be null");
......@@ -48,6 +63,18 @@ public class OcCborEncoder {
return cborEncoder;
}
/**
* Returns a cbor encoder for an un-keyed object, array or array item. Must be closed using done().
*
* @param type the EncoderType
* @param parent the enclosing cbor encoder
* @return a OcCborEncoder instance
*
* @see EncoderType#OBJECT
* @see EncoderType#ARRAY
* @see EncoderType#ARRAY_ITEM
* @see OcCborEncoder#done
*/
static public OcCborEncoder createOcCborEncoder(EncoderType type, OcCborEncoder parent) {
if (type == null) {
throw new IllegalArgumentException("EncoderType cannot be null");
......@@ -76,6 +103,18 @@ public class OcCborEncoder {
return cborEncoder;
}
/**
* Returns a cbor encoder for a keyed object or array. Must be closed using done().
*
* @param type the EncoderType
* @param parent the enclosing cbor encoder
* @param key the key of this cbor encoder
* @return a OcCborEncoder instance
*
* @see EncoderType#OBJECT
* @see EncoderType#ARRAY
* @see OcCborEncoder#done
*/
static public OcCborEncoder createOcCborEncoder(EncoderType type, OcCborEncoder parent, String key) {
if (type == null) {
throw new IllegalArgumentException("EncoderType cannot be null");
......@@ -104,6 +143,11 @@ public class OcCborEncoder {
return cborEncoder;
}
/**
* Closes an OcCborEncoder.
* <p>
* Must be called to properly close the cbor encoder.
*/
public void done() {
if (isDone) {
throw new UnsupportedOperationException(
......
......@@ -5,6 +5,16 @@ import java.util.concurrent.ConcurrentHashMap;
import org.iotivity.*;
/**
* OcCollection is a collection of a device.
* <p>
* Collections are typically added to a device in the registerResources() method of the platform's initialize handler.
*
* @see OcPlatform#systemInit
* @see OcDevice#addCollection
* @see OCMainInitHandler#registerResources
* @see OcLink
*/
public class OcCollection extends OcResource {
private Map<OcLink, OCLink> linkLookup = new ConcurrentHashMap<>();
......@@ -12,6 +22,16 @@ public class OcCollection extends OcResource {
private String[] supportedRts;
private String[] mandatoryRts;
/**
* Constructs an OcCollection.
* <p>
* @param device the device owning this collection
* @param name the name of this collection
* @param uri the uri of this collection
* @param rts array of the resource types
* @param sRts array of the supported resource types
* @param mRts array of the mandatory resource types
*/
public OcCollection(OcDevice device, String name, String uri, String[] rts, String[] sRts, String[] mRts) {
super();
if (device == null) {
......
......@@ -7,6 +7,16 @@ import java.util.concurrent.ConcurrentHashMap;
import org.iotivity.*;
/**
* OcDevice is a device of the platform.
* <p>
* Devices can only be added to the platform after the platform has been initialized.
* Devices are typically added to the platform in the platform's initialize handler.
*
* @see OcPlatform#platformInit
* @see OcPlatform#addDevice
* @see OCMainInitHandler#initialize
*/
public class OcDevice {
private Map<OcResource, OCResource> resourceLookup = new ConcurrentHashMap<>();
......@@ -19,6 +29,15 @@ public class OcDevice {
private int deviceIndex; // set by platform in addDevice()
/**
* Constructs an OcDevice.
* <p>
* @param uri the uri of the device
* @param rt the resource type of the device
* @param name the name of the device
* @param specVersion the spec version of the device
* @param dataModelVersion the data model version of the device
*/
public OcDevice(String uri, String rt, String name, String specVersion, String dataModelVersion) {
this.uri = (uri != null) ? uri : "";
this.rt = (rt != null) ? rt : "";
......@@ -27,38 +46,89 @@ public class OcDevice {
this.dataModelVersion = (dataModelVersion != null) ? dataModelVersion : "";
}
/**
* Returns the uri of this device.
* <p>
* @return uri
*/
public String getUri() {
return uri;
}
/**
* Returns the resource type of this device.
* <p>
* @return resource type
*/
public String getRt() {
return rt;
}
/**
* Returns the name of this device.
* <p>
* @return name
*/
public String getName() {
return name;
}
/**
* Returns the spec version of this device.
* <p>
* @return spec version
*/
public String getSpecVersion() {
return specVersion;
}
/**
* Returns the data model version of this device.
* <p>
* @return data model version
*/
public String getDataModelVersion() {
return dataModelVersion;
}
/**
* Returns the id of this device.
* <p>
* @return OCUuid
*
* @see OCUuid
*/
public OCUuid getId() {
return OCCoreRes.getDeviceId(deviceIndex);
}
public void setIntrospectionData(byte[] IDD) {
OCIntrospection.setIntrospectionData(deviceIndex, IDD);
/**
* Sets the introspection data of to this device.
* <p>
* @param idd the introspection data byte array
*/
public void setIntrospectionData(byte[] idd) {
OCIntrospection.setIntrospectionData(deviceIndex, idd);
}
/**
* Sets the immutable device id of to this device.
* <p>
* @param piid the immutable device id
*
* @see OCUuid
*/
public void setImmutableDeviceId(OCUuid piid) {
OCMain.setImmutableDeviceIdentifier(deviceIndex, piid);
}
/**
* Adds a resource to this device.
* <p>
* @param resource the resource to add
*
* @see OcResource
*/
public void addResource(OcResource resource) {
if (resource != null) {
if (resource instanceof OcCollection) {
......@@ -72,6 +142,14 @@ public class OcDevice {
}
}
/**
* Deletes a resource from this device.
* <p>
* @param resource the resource to delete
* @return true on success, false otherwise
*
* @see OcResource
*/
public boolean deleteResource(OcResource resource) {
if (resource != null) {
resourceLookup.remove(resource);
......@@ -85,18 +163,47 @@ public class OcDevice {
return false;
}
/**
* Adds a collection to this device.
* <p>
* @param collection the collection to add
*
* @see OcCollection
*/
public void addCollection(OcCollection collection) {
addResource(collection);
}
/**
* Deletes a collection from this device.
* <p>
* @param collection the collection to delete
* @return true on success, false otherwise
*
* @see OcCollection
*/
public boolean deleteCollection(OcCollection collection) {
return deleteResource(collection);
}
/**
* Returns the resources of this device.
* <p>
* @return Array of OcResource
*
* @see OcResource
*/
public OcResource[] getResources() {
return resourceLookup.keySet().toArray(new OcResource[0]);
}
/**
* Returns the collections of this device.
* <p>
* @return Array of OcCollection
*
* @see OcCollection
*/
public OcCollection[] getCollections() {
List<OcCollection> collections = new ArrayList<>();
for (OcResource resource : resourceLookup.keySet()) {
......@@ -108,19 +215,35 @@ public class OcDevice {
return collections.toArray(new OcCollection[0]);
}
/**
* Binds a resource type to this device.
* <p>
* @param rt the resource type
*/
public void bindResourceType(String rt) {
OCMain.deviceBindResourceType(deviceIndex, rt);
}
/**
* Resets this device.
*/
public void resetDevice() {
OCMain.resetDevice(deviceIndex);
}
public int initConnectivity(OcDevice device) {
/**
* Initializes connectivity to this device.
* <p>
* @return 0 on success, -1 otherwise
*/
public int initConnectivity() {
return OCConnectivity.init(deviceIndex);
}
public void shutdownConnectivity(OcDevice device) {
/**
* Ends connectivity to this device.
*/
public void shutdownConnectivity() {
OCConnectivity.shutdown(deviceIndex);
}
......
package org.iotivity.oc;
/**
* Callback for all discovered devices.
*
* @see OcUtils#discoverAllDevices
*/
public interface OcDeviceDiscoveryHandler {
/**
* Called after a discovered device has been populated with its discovered resources.
*
* @param remoteDevice the discovered device
*
* @see OcUtils#discoverAllDevices
* @see OcRemoteDevice
* @see OcRemoteResource
*/
public void discoveredDevice(OcRemoteDevice remoteDevice);
}
......@@ -2,6 +2,9 @@ package org.iotivity.oc;
import org.iotivity.*;
/**
* OcException is the base class of all org.iotivity.oc exceptions.
*/
public class OcException extends Exception {
public OcException(String message) {
......
......@@ -2,7 +2,7 @@ package org.iotivity.oc;
import org.iotivity.*;
public class OcGetRemoteDeviceHandler implements OCResponseHandler {
class OcGetRemoteDeviceHandler implements OCResponseHandler {
private static final String N_KEY = "n";
private static final String DI_KEY = "di";
......
......@@ -2,7 +2,7 @@ package org.iotivity.oc;
import org.iotivity.*;
public class OcGetRemoteResourcesHandler implements OCDiscoveryAllHandler {
class OcGetRemoteResourcesHandler implements OCDiscoveryAllHandler {
private OcRemoteDevice device;
private OcDeviceDiscoveryHandler deviceDiscoveryHandler;
......
......@@ -2,15 +2,36 @@ package org.iotivity.oc;
import org.iotivity.*;
/**
* OcLink is a resource link.
* <p>
* Links are typically added to a collection in the registerResources() method of the platform's initialize handler.
*
* @see OcPlatform#systemInit
* @see OcCollection#addLink
* @see OCMainInitHandler#registerResources
*/
public class OcLink {
private OcResource resource; // href is uri of resource
private OCLink nativeLink;
/**
* Constructs an OcLink.
* <p>
* @param resource the resource this link represents
*/
public OcLink(OcResource resource) {
this(resource, 0, null);
}
/**
* Constructs an OcLink.
* <p>
* @param resource the resource this link represents
* @param instance the instance of this link
* @param relations array of the relationships
*/
public OcLink(OcResource resource, long instance, String[] relations) {
if (resource != null) {
nativeLink = OCMain.newLink(resource.getNativeResource());
......
......@@ -2,12 +2,23 @@ package org.iotivity.oc;
import org.iotivity.*;
/**
* OcObt provides access to all the methods necessary for an On Boarding Tool.
*/
public class OcObt {
/**
* Creates and initializes an on boarding tool instance.
*/
public OcObt() {
OCObt.init();
}
/**
* Ends the lifetime of an on boarding tool instance.
* <p>
* Once shutdown() is called, this OcObt instance should not be used again.
*/
public void shutdown() {
OCObt.shutdown();
}
......
......@@ -6,6 +6,17 @@ import java.util.concurrent.atomic.AtomicInteger;
import org.iotivity.*;
/**
* OcPlatform is the basic building block of every IoTivity server or client.
* <p>
* A typical usage pattern would be:
* <pre>
* OcPlatform platform = OcPlatform.getInstance();
* OCMainInitHandler handler = new InitHandler(platform); // InitHandler is an instance of OCMainInitHandler
* platform.systemInit(handler);
* </pre>
* @see OCMainInitHandler
*/
public class OcPlatform {
private AtomicInteger deviceIndex = new AtomicInteger();
......@@ -16,6 +27,11 @@ public class OcPlatform {
private OcPlatform() {
}
/**
* Returns the single platform instance.
*
* @return the OcPlatform instance
*/
public static OcPlatform getInstance() {
if (instance == null) {
instance = new OcPlatform();
......@@ -24,12 +40,22 @@ public class OcPlatform {
return instance;
}
/**
* Ends the lifetime of the IoTivity server or client.
*/
public void systemShutdown() {
OCMain.mainShutdown();
deviceIndex.set(0);
deviceIndexLookup.clear();
}
/**
* Begins the lifetime of the IoTivity server or client.
*
* @param mainInitHandler an instance of OCMainInitHandler
*
* @see OCMainInitHandler
*/
public void systemInit(OCMainInitHandler mainInitHandler) {
int initReturnValue = OCMain.mainInit(mainInitHandler);
if (initReturnValue < 0) {
......@@ -37,15 +63,34 @@ public class OcPlatform {
}
}
/**
* Initializes the platform. Should be called from OCMainInitHandler.initialize().
*
* @param mfgName the manufacturer's name of this platform
* @return -1 on failure, &gt;=0 otherwise
*
* @see OCMainInitHandler#initialize
*/
public int platformInit(String mfgName) {
mfgName = (mfgName != null) ? mfgName : "";
return OCMain.initPlatform(mfgName);
}
/**
* Resets the platform.
*/
public void reset() {
OCMain.reset();
}
/**
* Adds a device to the platform.
*
* @param device the OcDevice to add to this platform
* @return -1 on failure, &gt;=0 otherwise
*
* @see OcDevice
*/
public int addDevice(OcDevice device) {
int ret = -1;
......
......@@ -6,6 +6,14 @@ import java.util.List;
import org.iotivity.*;
/**
* OcRemoteDevice is a device that has been discovered.
* <p>
* Remote devices can be discovered using the discovery api call.
*
* @see OcUtils#discoverAllDevices
* @see OcDeviceDiscoveryHandler#discoveredDevice
*/
public class OcRemoteDevice {
private OCUuid di;
......
......@@ -6,6 +6,14 @@ import java.util.List;
import org.iotivity.*;
/**
* OcRemoteResource is a resource of a discovered device.
* <p>
* Remote resources are discovered using the discovery api call.
* The device discovery api will also discover the resources of the remote device.
*
* @see OcUtils#discoverAllDevices
*/
public class OcRemoteResource {
private String anchor;
......
......@@ -2,6 +2,14 @@ package org.iotivity.oc;
import org.iotivity.*;
/**
* OcRepresentation provides access to extract values from a CBOR representation.
* <p>
* An OcRepresenation is typically constructed from the payload of an OCClientResponse in the handler() method of an OCResponseHandler.
*
* @see OCResponseHandler#handler
* @see OCClientResponse#getPayload
*/
public class OcRepresentation {
private OCRepresentation nativeRepresentation;
......
......@@ -5,6 +5,16 @@ import java.util.List;
import org.iotivity.*;
/**
* OcResource is a resource of a device.
* <p>
* Resources are typically added to a device in the registerResources() method of the platform's initialize handler.
*
* @see OcPlatform#systemInit
* @see OcDevice#addResource
* @see OCMainInitHandler#registerResources
* @see OcLink
*/
public class OcResource {
protected String name;
......@@ -26,6 +36,17 @@ public class OcResource {
protected OcResource() {
}
/**
* Constructs an OcResource.
* <p>
* @param device the device owning this resource
* @param name the name of this resource
* @param uri the uri of this resource
* @param resourceTypes array of the resource types
* @param interfaceMasks array of the interface masks
*
* @see OCInterfaceMask
*/
public OcResource(OcDevice device, String name, String uri, String[] resourceTypes, int[] interfaceMasks) {
if (device == null) {
throw new IllegalArgumentException("OcDevice cannot be null");
......
......@@ -2,6 +2,11 @@ package org.iotivity.oc;
import org.iotivity.*;
/**
* OcSecurityAce is the base class of all Security Access Control Entries.
* <p>
* Only a derived SecurityAce class can be instantiated.
*/
public abstract class OcSecurityAce {
protected OCSecurityAce nativeSecurityAce;
......
......@@ -4,6 +4,9 @@ import java.util.List;
import org.iotivity.*;
/**
* OcUtils is a collection of useful static methods.
*/
public class OcUtils {
// never instantiated
......@@ -138,6 +141,14 @@ public class OcUtils {
OCMain.freeServerEndpoints(endpoint);
}
/**
* Discovers all devices.
*
* @param deviceDiscoveryHandler the callback interface
* @return true if the discovery request is successful, false otherwise
*
* @see OcDeviceDiscoveryHandler#discoveredDevice
*/
public static boolean discoverAllDevices(OcDeviceDiscoveryHandler deviceDiscoveryHandler) {
return OcUtils.doIPMulticast("/oic/d", null, new OcGetRemoteDeviceHandler(deviceDiscoveryHandler));
}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.