Swiftdiff options
| author | Nick Hudson <nick.hudson@isode.com> | 2012-02-02 15:19:36 (GMT) |
|---|---|---|
| committer | Kevin Smith <git@kismith.co.uk> | 2012-02-13 16:59:43 (GMT) |
| commit | 5d1245e7ecde8c5b41279bdad6df930084ff35a6 (patch) | |
| tree | 60de739a060e29492513a12daf592798441539eb /src | |
| parent | 9d6f73f13b981fb9430765b171d7b419cbe632cc (diff) | |
| download | stroke-5d1245e7ecde8c5b41279bdad6df930084ff35a6.zip stroke-5d1245e7ecde8c5b41279bdad6df930084ff35a6.tar.bz2 | |
Update ByteArray with "readFromFile" implementation and more javadoc
This change provides implementation for the previously empty
"readFromFile" method, which is based on the code inside Swiften's
ByteArray.readByteArrayFromFile().
Note that, as for the Swiften method, no errors are reported if an
attempt to read from a file fails; it just leaves the contents of the
object unchanged.
Some javadoc was also provided, especially noting that the various
String methods are only safe so long as you're working with UTF-8
Strings.
Test-information:
Existing Stroke unit tests still pass
Signed-off-by: Nick Hudson <nick.hudson@isode.com>
Diffstat (limited to 'src')
| -rw-r--r-- | src/com/isode/stroke/base/ByteArray.java | 149 |
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; |