summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--src/com/isode/stroke/base/ByteArray.java149
1 files changed, 134 insertions, 15 deletions
diff --git a/src/com/isode/stroke/base/ByteArray.java b/src/com/isode/stroke/base/ByteArray.java
index 9396805..8b140ed 100644
--- a/src/com/isode/stroke/base/ByteArray.java
+++ b/src/com/isode/stroke/base/ByteArray.java
@@ -1,25 +1,39 @@
/*
* Copyright (c) 2010 Remko Tronçon
- * Licensed under the GNU General Public License v3.
- * See Documentation/Licenses/GPLv3.txt for more information.
+ * All rights reserved.
*/
/*
- * Copyright (c) 2010, Isode Limited, London, England.
+ * Copyright (c) 2010-2012, Isode Limited, London, England.
* All rights reserved.
*/
package com.isode.stroke.base;
+import java.io.ByteArrayOutputStream;
+import java.io.FileInputStream;
+import java.io.FileNotFoundException;
+import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.util.Vector;
/**
- *
+ * Maintains an arbitrarily long array of bytes.
*/
public class ByteArray {
+ /**
+ * Construct a new, empty ByteArray that contains no data.
+ */
public ByteArray() {
}
+ /**
+ * Constructs a new ByteArray from the bytes corresponding to encoding
+ * the provided String as UTF-8.
+ * <p> Note that this should only be used for 'real' Strings (e.g. not
+ * for TLS data)
+ *
+ * @param s String, must not be null.
+ */
public ByteArray(String s) {
try {
fromBytes(s.getBytes("UTF-8"));
@@ -28,10 +42,21 @@ public class ByteArray {
}
}
+ /**
+ * Constructs a new ByteArray containing the bytes in a user-supplied
+ * byte[]
+ * @param c an array of bytes, which must not be null, but may contain
+ * zero elements.
+ */
public ByteArray(byte[] c) {
fromBytes(c);
}
+ /**
+ * Constructs a new ByteArray object by performing a deep copy of the
+ * contents of an existing ByteArray
+ * @param b another ByteArray; must not be null
+ */
public ByteArray(ByteArray b) {
fromBytes(b.getData());
}
@@ -48,22 +73,33 @@ public class ByteArray {
}*/
/**
- * @return array copy of internal data.
+ * Returns a byte[] containing the contents of this object.
+ * @return array copy of internal data, will never be null, but may
+ * contain zero elements.
*/
public byte[] getData() {
if (dataCopy_ == null) {
dataCopy_ = new byte[getSize()];
for (int i = 0; i < data_.size(); i++) {
- dataCopy_[i] = data_.get(i);
+ dataCopy_[i] = data_.get(i).byteValue();
}
}
return dataCopy_;
}
+ /**
+ * Returns the number of bytes in this ByteArray
+ * @return number of bytes
+ */
public int getSize() {
return data_.size();
}
+ /**
+ * Determines whether the ByteArray is empty
+ * @return <em>true</em> if there are no elements in the ByteArray,
+ * <em>false</em> otherwise.
+ */
public boolean isEmpty() {
return getSize() == 0;
}
@@ -71,27 +107,48 @@ public class ByteArray {
/*public void resize(size_t size) {
return data_.resize(size);
}*/
- /** Immutable add */
+ /**
+ * Creates a new ByteArray object containing all
+ * the elements from two existing ByteArrays (immutable add).
+ *
+ * @param a an existing ByteArray. Must not be null, but may be empty.
+ * @param b an existing ByteArray. Must not be null, but may be empty.
+ * @return a new ByteArray containing all the elements of <em>a</em>
+ * followed by all the elements of <em>b</em>.
+ */
public static ByteArray plus(ByteArray a, ByteArray b) {
ByteArray x = new ByteArray(a.getData());
x.append(b);
return x;
}
- /** Immutable add */
+ /* * Immutable add */
/*public ByteArray plus(ByteArray a, char b) {
ByteArray x = new ByteArray(a.getData());
x.append(b);
return x;
}*/
-
- /** Mutable add */
+
+ /**
+ * Updates the ByteArray by adding all the elements
+ * of another ByteArray to the end of the array (mutable add).
+ * @param b an existing ByteArray. Must not be null, but may be empty
+ * @return a reference to the updated object
+ */
public ByteArray append(ByteArray b) {
append(b.getData());
return this;
}
- /** Mutable add */
+ /**
+ * Updates the ByteArray by adding all the bytes
+ * in a byte[] to the end of the array (mutable add).
+ *
+ * @param b an array of bytes. Must not be null, but may contain zero
+ * elements.
+ *
+ * @return a reference to the updated object
+ */
private ByteArray append(byte[] b) {
for (int i = 0; i < b.length; i++) {
append(b[i]);
@@ -99,14 +156,24 @@ public class ByteArray {
return this;
}
- /** Mutable add */
+ /**
+ * Updates the ByteArray by adding a single byte
+ * value to the end of the array (mutable add).
+ * @param b a single byte
+ * @return a reference to the updated object
+ */
public ByteArray append(byte b) {
dataCopy_ = null; /* Invalidate cache */
- data_.add(b);
+ data_.add(Byte.valueOf(b));
return this;
}
- /** mutable add */
+ /**
+ * Updates the ByteArray by adding all the bytes
+ * obtained by UTF-8 encoding the provided String to the end of the array (mutable add).
+ * @param s a String that must not be null.
+ * @return a reference to the updated object.
+ */
public ByteArray append(String s) {
byte[] bytes;
try {
@@ -141,6 +208,15 @@ public class ByteArray {
public const_iterator end() const {
return data_.end();
}*/
+ /**
+ * Returns a String representation of this object by attempting to
+ * treat its component bytes as a UTF-8 String. If the ByteArray is empty,
+ * an empty String ("") will be returned. If the bytes inside the object
+ * are not valid UTF-8, then the resultant String may not be very
+ * user-friendly.
+ *
+ * @return a String representation of the bytes inside this object
+ */
@Override
public String toString() {
try {
@@ -150,10 +226,53 @@ public class ByteArray {
}
}
+ /**
+ * Appends the contents of a file to the end of an existing ByteStream
+ * object (mutable add).
+ *
+ * @param file the name of the file to be read. If the file cannot be
+ * opened for any reason, or if an error occurs during an attempt to
+ * read it, then the contents of the ByteStream are left
+ * unchanged (i.e. no exception is thrown).
+ */
public void readFromFile(String file) {
- //FIXME: port
+ FileInputStream fis = null;
+ ByteArrayOutputStream bos = null;
+ try {
+ fis = new FileInputStream(file);
+ bos = new ByteArrayOutputStream();
+ while (fis.available() != 0) {
+ bos.write(fis.read());
+ }
+ byte[] bytes = bos.toByteArray();
+ append(bytes);
+ }
+ catch (FileNotFoundException e) {
+ // Leave things as they were
+ return;
+ }
+ catch (IOException e) {
+ // Leave things as they were
+ return;
+ } finally {
+ try {
+ if(bos != null) bos.close();
+ }
+ catch (IOException e) {
+ // Needs a catch clause
+ }
+ try {
+ if(fis != null) fis.close();
+ }
+ catch (IOException e) {
+ // Needs a catch clause
+ }
+ }
}
+ /**
+ * Clears the contents of this ByteArray, leaving it with zero elements.
+ */
public void clear() {
data_ = new Vector<Byte>();
dataCopy_ = null;