Add more nullability annotations (#68)

* add more nullability annotations

* more annotations

* more annotations

* random newline

* remove padding vars; update doc link

mcumgr-core/src/main/java/io/runtime/mcumgr/McuManager.java

@@ -288,7 +288,7 @@ public <T extends McuMgrResponse> T send(@NotNull byte[] data, @NotNull Class<T>
      * @throws McuMgrException if the payload map could not be serialized into CBOR. See cause.
      */
     @NotNull
-    public static byte[] buildPacket(McuMgrScheme scheme, int op, int flags, int groupId,
+    public static byte[] buildPacket(@NotNull McuMgrScheme scheme, int op, int flags, int groupId,
                                      int sequenceNum, int commandId,
                                      @Nullable Map<String, Object> payloadMap)
             throws McuMgrException {

mcumgr-core/src/main/java/io/runtime/mcumgr/McuMgrHeader.java

@@ -20,6 +20,7 @@
  */
 @SuppressWarnings({"unused", "WeakerAccess"})
 public class McuMgrHeader {
+
     public final static int HEADER_LENGTH = 8;
 
     private int mOp;
@@ -38,6 +39,7 @@ public McuMgrHeader(int op, int flags, int len, int groupId, int sequenceNum, in
         mCommandId = commandId;
     }
 
+    @NotNull
     public byte[] toBytes() {
         return build(mOp, mFlags, mLen, mGroupId, mSequenceNum, mCommandId);
     }
@@ -90,14 +92,25 @@ public void setCommandId(int commandId) {
         this.mCommandId = commandId;
     }
 
+    @NotNull
     @Override
     public String toString() {
-        return "Header (Op: " + mOp + ", Flags: " + mFlags + ", Len: " + mLen + ", Group: " + mGroupId + ", Seq: " + mSequenceNum + ", Command: " + mCommandId + ")";
+        return "Header (Op: " + mOp + ", Flags: " + mFlags + ", Len: " + mLen + ", Group: " +
+                mGroupId + ", Seq: " + mSequenceNum + ", Command: " + mCommandId + ")";
     }
 
-    public static McuMgrHeader fromBytes(byte[] header) {
-        if (header == null || header.length != HEADER_LENGTH) {
-            return null;
+    /**
+     * Parse the mcumgr header from a byte array.
+     * This function will parse the first 8 bytes from the array, discounting any additional bytes.
+     *
+     * @param header the byte array to parse the header from.
+     * @return The parsed mcumgr header.
+     * @throws IllegalArgumentException when the byte array length is less than 8 bytes
+     */
+    @NotNull
+    public static McuMgrHeader fromBytes(@NotNull byte[] header) {
+        if (header.length < HEADER_LENGTH) {
+            throw new IllegalArgumentException("Failed to parse mcumgr header from bytes; too short - length=" + header.length);
         }
         int op          = ByteUtil.byteArrayToUnsignedInt(header, 0, Endian.BIG, 1);
         int flags       = ByteUtil.byteArrayToUnsignedInt(header, 1, Endian.BIG, 1);

mcumgr-core/src/main/java/io/runtime/mcumgr/crash/CoreDumpHeader.java

@@ -30,6 +30,7 @@ public CoreDumpHeader(int magic, int size) {
      * @return The core dump header.
      * @throws IOException If the magic number was invalid.
      */
+    @NotNull
     public static CoreDumpHeader fromBytes(@NotNull byte[] data) throws IOException {
         return fromBytes(data, OFFSET);
     }
@@ -41,6 +42,7 @@ public static CoreDumpHeader fromBytes(@NotNull byte[] data) throws IOException
      * @return The core dump header.
      * @throws IOException If the magic number was invalid.
      */
+    @NotNull
     public static CoreDumpHeader fromBytes(@NotNull byte[] data, int offset) throws IOException {
         int magic = ByteUtil.byteArrayToUnsignedInt(data, offset, Endian.LITTLE, 4);
         if (magic != CoreDump.MAGIC) {

mcumgr-core/src/main/java/io/runtime/mcumgr/crash/CoreDumpTlv.java

@@ -15,6 +15,7 @@ public class CoreDumpTlv {
 
     private static final int OFFSET = 8;
 
+    @NotNull
     private List<CoreDumpTlvEntry> mEntries;
 
     public CoreDumpTlv(@NotNull List<CoreDumpTlvEntry> entries) {
@@ -81,6 +82,11 @@ public List<CoreDumpTlvEntry> getEntriesOfType(int type) {
         return entries;
     }
 
+    /**
+     * Get the list of core dump TLV entries.
+     * @return the list of TLV entries
+     */
+    @NotNull
     public List<CoreDumpTlvEntry> getEntries() {
         return mEntries;
     }

mcumgr-core/src/main/java/io/runtime/mcumgr/crash/CoreDumpTlvEntry.java

@@ -22,7 +22,6 @@ public class CoreDumpTlvEntry {
     private static final int MIN_SIZE = 8;
 
     private int mType;      // uint8_t
-    //private byte __pad;   // uint8_t
     private int mLength;    // uint16_t
     private long mOff;      // uint32_t
 
@@ -77,6 +76,7 @@ public static CoreDumpTlvEntry fromBytes(@NotNull byte[] data, int offset) throw
         return new CoreDumpTlvEntry(type, length, off, value);
     }
 
+    @NotNull
     @Override
     public String toString() {
         return String.format("{type=%s, length=%s, off=%s, value=%s}", mType, mLength, mOff,

mcumgr-core/src/main/java/io/runtime/mcumgr/image/McuMgrImage.java

@@ -19,7 +19,7 @@
  * image header and type-length-value trailer for image meta-data.
  * <p>
  * For more info about McuBoot and image format see:
- * <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
+ * <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
  */
 @SuppressWarnings({"WeakerAccess", "unused"})
 public class McuMgrImage {

mcumgr-core/src/main/java/io/runtime/mcumgr/image/McuMgrImageHeader.java

@@ -18,50 +18,62 @@
  * bootloader.
  * <p>
  * For more info about McuBoot and image format see:
- * <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
+ * <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
  */
 @SuppressWarnings({"unused", "WeakerAccess"})
 public class McuMgrImageHeader {
 
     private static final int IMG_HEADER_MAGIC      = 0x96f3b83d;
     private static final int IMG_HEADER_MAGIC_V1   = 0x96f3b83c;
 
-    private static final int HEADER_LENGTH = 4 + 4 + 2 + 2 + 4 + 4 + 4;
+    private static final int HEADER_LENGTH = 24;
     private int mMagic;
     private int mLoadAddr;
     private short mHdrSize;
-    private short __mPad1;
     private int mImgSize;
     private int mFlags;
+    @NotNull
     private McuMgrImageVersion mVersion;
-    private int __mPad2;
 
-    private McuMgrImageHeader() {}
+    private McuMgrImageHeader(int magic,
+                              int loadAddr,
+                              short hdrSize,
+                              int imgSize,
+                              int flags,
+                              @NotNull McuMgrImageVersion version) {
+        mMagic = magic;
+        mLoadAddr = loadAddr;
+        mHdrSize = hdrSize;
+        mImgSize = imgSize;
+        mFlags = flags;
+        mVersion = version;
+    }
 
+    @NotNull
     public static McuMgrImageHeader fromBytes(@NotNull byte[] b) throws McuMgrException {
         return fromBytes(b, 0);
     }
 
+    @NotNull
     public static McuMgrImageHeader fromBytes(@NotNull byte[] b, int offset) throws McuMgrException {
         if (b.length - offset < getSize()) {
             throw new McuMgrException("The byte array is too short to be a McuMgrImageHeader");
         }
 
-        McuMgrImageHeader header = new McuMgrImageHeader();
-        header.mMagic = ByteUtil.byteArrayToUnsignedInt(b, offset, Endian.LITTLE, 4);
+        int magic = ByteUtil.byteArrayToUnsignedInt(b, offset, Endian.LITTLE, 4);
 
-        if (header.mMagic != IMG_HEADER_MAGIC && header.mMagic != IMG_HEADER_MAGIC_V1) {
-            throw new McuMgrException("Wrong magic number: header=" + header.mMagic + ", magic=" +
+        if (magic != IMG_HEADER_MAGIC && magic != IMG_HEADER_MAGIC_V1) {
+            throw new McuMgrException("Wrong magic number: header=" + magic + ", magic=" +
                     IMG_HEADER_MAGIC + " or " + IMG_HEADER_MAGIC_V1);
         }
 
-        header.mLoadAddr = ByteUtil.byteArrayToUnsignedInt(b, 4 + offset, Endian.LITTLE, 4);
-        header.mHdrSize = (short) ByteUtil.byteArrayToUnsignedInt(b, 8 + offset, Endian.LITTLE, 2);
-        header.mImgSize = ByteUtil.byteArrayToUnsignedInt(b, 12 + offset, Endian.LITTLE, 4);
-        header.mFlags = ByteUtil.byteArrayToUnsignedInt(b, 16 + offset, Endian.LITTLE, 4);
-        header.mVersion = McuMgrImageVersion.fromBytes(b, 20 + offset);
+        int loadAddr = ByteUtil.byteArrayToUnsignedInt(b, 4 + offset, Endian.LITTLE, 4);
+        short hdrSize = (short) ByteUtil.byteArrayToUnsignedInt(b, 8 + offset, Endian.LITTLE, 2);
+        int imgSize = ByteUtil.byteArrayToUnsignedInt(b, 12 + offset, Endian.LITTLE, 4);
+        int flags = ByteUtil.byteArrayToUnsignedInt(b, 16 + offset, Endian.LITTLE, 4);
+        McuMgrImageVersion version = McuMgrImageVersion.fromBytes(b, 20 + offset);
 
-        return header;
+        return new McuMgrImageHeader(magic, loadAddr, hdrSize, imgSize, flags, version);
     }
 
     public static int getSize() {
@@ -88,6 +100,7 @@ public int getFlags() {
         return mFlags;
     }
 
+    @NotNull
     public McuMgrImageVersion getVersion() {
         return mVersion;
     }

mcumgr-core/src/main/java/io/runtime/mcumgr/image/McuMgrImageVersion.java

@@ -6,6 +6,8 @@
 
 package io.runtime.mcumgr.image;
 
+import org.jetbrains.annotations.NotNull;
+
 import io.runtime.mcumgr.exception.McuMgrException;
 import io.runtime.mcumgr.util.ByteUtil;
 import io.runtime.mcumgr.util.Endian;
@@ -15,33 +17,40 @@
  * bootloader.
  * <p>
  * For more info about McuBoot and image format see:
- * <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
+ * <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
  */
 @SuppressWarnings("unused")
 public class McuMgrImageVersion {
+
     private byte mMajor;
     private byte mMinor;
     private short mRevision;
     private int mBuildNum;
 
-    private McuMgrImageVersion() {}
+    private McuMgrImageVersion(byte major, byte minor, short revision, int buildNum) {
+        mMajor = major;
+        mMinor = minor;
+        mRevision = revision;
+        mBuildNum = buildNum;
+    }
 
-    public static McuMgrImageVersion fromBytes(byte[] b) throws McuMgrException {
+    @NotNull
+    public static McuMgrImageVersion fromBytes(@NotNull byte[] b) throws McuMgrException {
         return fromBytes(b, 0);
     }
 
-    public static McuMgrImageVersion fromBytes(byte[] b, int offset) throws McuMgrException {
+    @NotNull
+    public static McuMgrImageVersion fromBytes(@NotNull byte[] b, int offset) throws McuMgrException {
         if (b.length - offset < getSize()) {
             throw new McuMgrException("The byte array is too short to be a McuMgrImageVersion");
         }
 
-        McuMgrImageVersion version = new McuMgrImageVersion();
-        version.mMajor = b[offset++];
-        version.mMinor = b[offset++];
-        version.mRevision = (short) ByteUtil.byteArrayToUnsignedInt(b, offset, Endian.LITTLE, 2);
-        version.mBuildNum = ByteUtil.byteArrayToUnsignedInt(b, offset + 2, Endian.LITTLE, 4);
+        byte major = b[offset++];
+        byte minor = b[offset++];
+        short revision = (short) ByteUtil.byteArrayToUnsignedInt(b, offset, Endian.LITTLE, 2);
+        int buildNum = ByteUtil.byteArrayToUnsignedInt(b, offset + 2, Endian.LITTLE, 4);
 
-        return version;
+        return new McuMgrImageVersion(major, minor, revision, buildNum);
     }
 
     public static int getSize() {

mcumgr-core/src/main/java/io/runtime/mcumgr/image/tlv/McuMgrImageTlv.java

@@ -20,7 +20,7 @@
  * Mynewt bootloader.
  * <p>
  * For more info about McuBoot and image format see:
- * <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
+ * <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
  */
 @SuppressWarnings({"unused", "WeakerAccess"})
 public class McuMgrImageTlv {

mcumgr-core/src/main/java/io/runtime/mcumgr/image/tlv/McuMgrImageTlvInfo.java

@@ -15,7 +15,7 @@
  * Mynewt bootloader.
  * <p>
  * For more info about McuBoot and image format see:
- * <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
+ * <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
  */
 @SuppressWarnings("unused")
 public class McuMgrImageTlvInfo {

mcumgr-core/src/main/java/io/runtime/mcumgr/image/tlv/McuMgrImageTlvTrailerEntry.java

@@ -17,7 +17,7 @@
  * Apache Mynewt bootloader.
  * <p>
  * For more info about McuBoot and image format see:
- * <a href="https://runtimeco.github.io/mcuboot/design.html">https://runtimeco.github.io/mcuboot/design.html</a>
+ * <a href="https://juullabs-oss.github.io/mcuboot/design.html">https://juullabs-oss.github.io/mcuboot/design.html</a>
  */
 public class McuMgrImageTlvTrailerEntry {
     public final byte type;

mcumgr-core/src/main/java/io/runtime/mcumgr/managers/CrashManager.java

@@ -53,6 +53,7 @@ public CrashManager(@NotNull McuMgrTransport transporter) {
      * @return The response
      * @throws McuMgrException on failure.
      */
+    @NotNull
     public McuMgrResponse test(@NotNull Test test) throws McuMgrException {
         HashMap<String, Object> payloadMap = new HashMap<>();
         payloadMap.put("t", test.toString());

mcumgr-core/src/main/java/io/runtime/mcumgr/managers/FsManager.java

@@ -135,6 +135,7 @@ public McuMgrFsUploadResponse upload(@NotNull String name, @NotNull byte[] data,
     /*
      * Build the upload payload map.
      */
+    @NotNull
     private HashMap<String, Object> buildUploadPayload(@NotNull String name, @NotNull byte[] data, int offset) {
         // Get the length of data (in bytes) to put into the upload packet. This calculated as:
         // min(MTU - packetOverhead, imageLength - uploadOffset)
@@ -175,6 +176,7 @@ private HashMap<String, Object> buildUploadPayload(@NotNull String name, @NotNul
      * @return The object used to control this upload.
      * @see TransferController
      */
+    @NotNull
     public TransferController fileUpload(@NotNull String name, @NotNull byte[] data, @NotNull UploadCallback callback) {
         return startUpload(new FileUpload(name, data, callback));
     }
@@ -215,6 +217,7 @@ protected UploadResponse write(@NotNull byte[] data, int offset) throws McuMgrEx
      * @return The object used to control this upload.
      * @see TransferController
      */
+    @NotNull
     public TransferController fileDownload(@NotNull String name, @NotNull byte[] data, @NotNull DownloadCallback callback) {
         return startDownload(new FileDownload(name, callback));
     }

mcumgr-core/src/main/java/io/runtime/mcumgr/managers/ImageManager.java

@@ -149,6 +149,7 @@ public McuMgrImageUploadResponse upload(@NotNull byte[] data, int offset) throws
     /*
      * Build the upload payload.
      */
+    @NotNull
     private HashMap<String, Object> buildUploadPayload(@NotNull byte[] data, int offset) {
         // Get chunk of image data to send
         int dataLength = Math.min(mMtu - calculatePacketOverhead(data, offset), data.length - offset);
@@ -387,6 +388,7 @@ public McuMgrResponse coreErase() throws McuMgrException {
      * @see TransferController
      * @see CoreDump
      */
+    @NotNull
     public TransferController coreDownload(@NotNull DownloadCallback callback) {
         return startDownload(new CoreDownload(callback));
     }
@@ -422,6 +424,7 @@ public DownloadResponse read(int offset) throws McuMgrException {
      * @return The object used to control this upload.
      * @see TransferController
      */
+    @NotNull
     public TransferController imageUpload(@NotNull byte[] imageData, @NotNull UploadCallback callback) {
         return startUpload(new ImageUpload(imageData, callback));
     }

mcumgr-core/src/main/java/io/runtime/mcumgr/managers/LogManager.java

@@ -127,7 +127,6 @@ public McuMgrLogResponse show(@Nullable String logName, @Nullable Long minIndex,
         return send(OP_READ, ID_READ, payloadMap, McuMgrLogResponse.class);
     }
 
-
     /**
      * Clear the logs on a device (asynchronous).
      *
@@ -221,6 +220,7 @@ public McuMgrLogListResponse logsList() throws McuMgrException {
      *
      * @return A mapping of log name to state.
      */
+    @NotNull
     public synchronized Map<String, State> getAll() {
         HashMap<String, State> logStates = new HashMap<>();
         try {
@@ -259,10 +259,8 @@ public synchronized Map<String, State> getAll() {
      * @param state The log state to collect logs from.
      * @return The log state with updated next index and entry list.
      */
-    public State getAllFromState(State state) {
-        if (state == null) {
-            throw new NullPointerException("State must not be null!");
-        }
+    @NotNull
+    public State getAllFromState(@NotNull State state) {
         // Loop until we run out of entries or encounter a problem
         while (true) {
             // Get the next set of entries for this log
@@ -309,7 +307,8 @@ public State getAllFromState(State state) {
      * @param state The state to get logs from.
      * @return The show response.
      */
-    public McuMgrLogResponse showNext(State state) {
+    @Nullable
+    public McuMgrLogResponse showNext(@NotNull State state) {
         LOG.debug("Show logs: name={}, nextIndex={}", state.getName(), state.getNextIndex());
         try {
             McuMgrLogResponse response = show(state.getName(), state.getNextIndex(), null);