com.webobjects.foundation
Class NSData

java.lang.Object
  |
  +--com.webobjects.foundation.NSData

All Implemented Interfaces:

Cloneable, NSCoding, Serializable

Direct Known Subclasses:

NSMutableData

public class NSData

extends Object

implements Cloneable, Serializable, NSCoding

NSData and its subclass NSMutableData provide data objects, object-oriented wrappers for byte buffers. Data objects let byte arrays take on the behavior of Foundation objects. NSData creates static data objects, and NSMutableData creates dynamic data objects.

Data objects can wrap data of any size. The object contains no information about the data itself (such as its type); the responsibility for deciding how to use the data lies with the client. In particular, it will not handle byte-order swapping when distributed between big-endian and little-endian machines.

The following table describes the NSData methods that provide the basis for all NSData's other methods; that is, all other methods are implemented in terms of these four. If you create a subclass of NSData, you need to ensure that only these base methods work properly. Having done so, you can be sure that all the subclass's inherited methods operate properly.

NSData's Base API

Method	Description
bytesNoCopy	Returns the internal byte array that contains the receiver's data. Used by mutable subclasses of NSData.
immutableBytes	Returns an immutable byte array that contains the receiver's data.
immutableRange	Returns an immutable NSRange object that specifies the receiver's length.
rangeNoCopy	Returns the internal NSRange object that specifies the receiver's length. Used by mutable subclasses of NSData.

To extract a data object that contains a subset of the bytes in another data object, use subdataWithRange. To determine if two data objects are equal, use isEqualToData, which does a byte-for-byte comparison.

writeToStream lets you write the contents of a data object to a stream (a java.io.OutputStream object).

See Also:

bytesNoCopy(), immutableBytes(), immutableRange(), rangeNoCopy(), isEqualToData(NSData otherData), subdataWithRange(NSRange range), writeToStream(java.io.OutputStream outputStream), Serialized Form

Inner classes inherited from class com.webobjects.foundation.NSCoding

NSCoding.Support

Field Summary

static NSData

EmptyData An empty data object, which can be shared to save memory.

Constructor Summary

NSData()
Creates an empty data object.

NSData(byte[] bytes)
Creates a data object with all the data in the byte array bytes.

NSData(byte[] bytes, int offset, int count)
Creates a data object with the bytes from the byte array bytes that fall in the range specified by offset and count.

NSData(byte[] bytes, NSRange range)
Creates a data object with the bytes from the byte array bytes that fall in the range specified by range.

NSData(byte[] bytes, NSRange range, boolean noCopy)
Creates a data object with the bytes from the byte array bytes that fall in the range specified by range.

NSData(File file)
Deprecated.

NSData(InputStream inputStream, int chunkSize)
Creates a data object with the data from the stream specified by inputStream.

NSData(NSData otherData)
Creates a data object containing the contents of another data object, otherData.

NSData(String value)
Deprecated.

NSData(String value, String encoding)
This constructor creates a new NSData object from a String

NSData(URL url)
Deprecated.

Method Summary

byte[]	bytes() Returns a byte array containing all of the receiver's contents
byte[]	bytes(int offset, int length) Returns a byte array containing all of the receiver's contents
byte[]	bytes(NSRange range) Returns a byte array containing all of the receiver's contents
protected byte[]	bytesNoCopy() Due to the internal implementation of NSData, the array returned by this primitive method may contain bytes that are not actually a part of the receiver's data.
byte[]	bytesNoCopy(NSMutableRange range) The receiver's actual data is composed of the returned array's bytes that lie within range.
Class	classForCoder() Conformance to NSCoding.
Object	clone() Since NSData objects are immutable, there's no need to make an actual clone.
static NSData	dataWithContentsOfFile(File file) Deprecated.
static NSData	dataWithContentsOfFile(String path) Deprecated.
static NSData	dataWithContentsOfMappedFile(File file) Deprecated.
static Object	decodeObject(NSCoder coder) Creates an NSData from the data in coder.
void	encodeWithCoder(NSCoder coder) Encodes the receiver using coder.
boolean	equals(Object object) Compares the receiving data object to object.
int	hashCode() Provide an appropriate hash code useful for storing the receiver in a hash-based data structure.
protected byte[]	immutableBytes() Privitive method that returns the receiver's data.
protected NSRange	immutableRange() Privitive method that returns the receiver's range.
boolean	isEqualToData(NSData otherData) Compares the receiving data object to otherData.
int	length() Returns the number of bytes contained by the receiver.
protected NSRange	rangeNoCopy() Primitive method used by mutable subclasses of NSData.
ByteArrayInputStream	stream() Returns a stream containing the receiver's data
NSData	subdataWithRange(NSRange range) Creates a data object containing a copy of the receiver's bytes that fall within the range specified by range.
String	toString() Returns a string representation of the receiver.
boolean	writeToFile(String path) Deprecated.
void	writeToStream(OutputStream stream) Writes the bytes in the receiver contents to the stream.
boolean	writeToURL(URL url, boolean atomically) Deprecated.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EmptyData

public static final NSData EmptyData

An empty data object, which can be shared to save memory.

Constructor Detail

NSData

public NSData()

Creates an empty data object.

NSData

public NSData(byte[] bytes)

Creates a data object with all the data in the byte array bytes.

Parameters:

bytes - input byte array

NSData

public NSData(byte[] bytes,
              NSRange range)

Creates a data object with the bytes from the byte array bytes that fall in the range specified by range.

Parameters:

bytes - input byte array

range - subrange of data within array

NSData

public NSData(byte[] bytes,
              int offset,
              int count)

Creates a data object with the bytes from the byte array bytes that fall in the range specified by offset and count.

Parameters:

bytes - input byte array

offset - offset of start of data within byte array

count - length of data starting at offset

NSData

public NSData(byte[] bytes,
              NSRange range,
              boolean noCopy)

Creates a data object with the bytes from the byte array bytes that fall in the range specified by range. The noCopy parameter specifies whether or not a copy of bytes is made.

Parameters:

bytes - input byte array

range - range of data in byte array

noCopy - specifies whether or not a copy of bytes is made

NSData

public NSData(NSData otherData)

Creates a data object containing the contents of another data object, otherData.

Parameters:

otherData - data object to be copied

NSData

public NSData(InputStream inputStream,
              int chunkSize)
       throws IOException

Creates a data object with the data from the stream specified by inputStream. The chunkSize parameter specifies the size, in bytes, of the block that the input stream returns when it reads. For maximum performance, you should set the chunk size to the approximate size of the data. This constructor reads the stream until it detects an end of file or encounters an exception, but it does not close the stream.

Parameters:

inputStream - data object with the data from the stream specified by inputStream

chunkSize - specifies the size, in bytes, of the block that the input stream returns

Throws:

IOException -

NSData

public NSData(File file)
       throws IOException

Deprecated.

Throws:

IOException -

IllegalArgumentException -

See Also:

NSData(InputStream inputStream, int chunkSize)

NSData

public NSData(URL url)
       throws IOException

Deprecated.

This method is deprecated in the Java Foundation Framework. Don't use this constructor. Use the following code instead:

 
 
 URLConnection connection = url.openConnection(); connection.connect(); 
 NSData myData = new NSData(connection.getInputStream(),chunkSize);
 
 

Parameters:

url - input url

Throws:

IOException -

NSData

public NSData(String value)

Deprecated.

This method is deprecated in the Java Foundation Framework.

Parameters:

value - input value as String

See Also:

NSData(InputStream inputStream, int chunkSize)

NSData

public NSData(String value,
              String encoding)

This constructor creates a new NSData object from a String

Parameters:

value - The textual data to use

encoding - The encoding type used to create the bytes.

Method Detail

bytes

public byte[] bytes()

Returns a byte array containing all of the receiver's contents

Returns:

a byte array containing all of the receiver's contents

bytes

public byte[] bytes(int offset,
                    int length)

Returns a byte array containing all of the receiver's contents

Parameters:

offset - input range specified by offset

length - number of bytes following offset to return

Returns:

a byte array containing the receiver's contents that fall within the range specified by offset and length

bytes

public byte[] bytes(NSRange range)

Returns a byte array containing all of the receiver's contents

Parameters:

range - input range specified by range

Returns:

a byte array containing the receiver's contents that fall within the range specified by range

bytesNoCopy

protected byte[] bytesNoCopy()

Due to the internal implementation of NSData, the array returned by this primitive method may contain bytes that are not actually a part of the receiver's data. The receiver's actual data is composed of the returned array's bytes that lie in the range returned by rangeNoCopy. It is used by mutable subclasses of NSData.

Returns:

returns the internal byte array that contains the receiver's data

See Also:

rangeNoCopy()

bytesNoCopy

public byte[] bytesNoCopy(NSMutableRange range)

The receiver's actual data is composed of the returned array's bytes that lie within range. WARNING NSData assumes the internal byte array is immutable. You should not change contents of this array.

Parameters:

range - input mutable range specified by range

Returns:

the internal byte array that contains the receiver's data and sets range's offset and length to those of the receiver's internal NSRange object

classForCoder

public Class classForCoder()

Conformance to NSCoding.

Specified by:

classForCoder in interface NSCoding

Returns:

a class that can substitute the name of a public superclass when being encoded.

See Also:

NSCoding.classForCoder()

clone

public Object clone()

Since NSData objects are immutable, there's no need to make an actual clone.

Overrides:

clone in class Object

Returns:

returns the receiver

dataWithContentsOfFile

public static NSData dataWithContentsOfFile(File file)
                                     throws IOException

Deprecated.

This method is deprecated in the Java Foundation Framework. Don't use this method. Use the following code instead:

 myData = new NSData(new FileInputStream(file), chunkSize);
 

Parameters:

file - input java.io.File object

Returns:

an NSData object initialized with the contents of file

Throws:

IOException -

dataWithContentsOfFile

public static NSData dataWithContentsOfFile(String path)
                                     throws IOException

Deprecated.

This method is deprecated in the Java Foundation Framework. Don't use this method. Use the following code instead:

 myData = new NSData(new FileInputStream(path), chunkSize);
 
 

Parameters:

path - input path of the file

Returns:

an NSData object initialized with the contents of file at path

Throws:

IOException -

dataWithContentsOfMappedFile

public static NSData dataWithContentsOfMappedFile(File file)
                                           throws IOException

Deprecated.

This method is deprecated in the Java Foundation Framework. Don't use this method. Use the following code instead.

 myData = new NSData(new FileInputStream(file), chunkSize);    
 
 

Parameters:

file - input java.io.File object

Returns:

an NSData object initialized with the contents of file

Throws:

IOException -

decodeObject

public static Object decodeObject(NSCoder coder)

Creates an NSData from the data in coder.

Parameters:

coder -

Returns:

the shared instance of NSKeyValueCoding.Null stored in the NSKeyValueCoding constant NullValue

See Also:

NSCoding

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Description copied from interface: NSCoding

Encodes the receiver using coder. Object type information along with an object's data is stored.

Specified by:

encodeWithCoder in interface NSCoding

Parameters:

coder -

equals

public boolean equals(Object object)

Compares the receiving data object to object. If object is an NSData and the contents of object are equal to the contents of the receiver, this method returns true. If not, it returns false. Two data objects are equal if they hold the same number of bytes, and if the bytes at the same position in the objects are the same.

Overrides:

equals in class Object

Parameters:

object - input data object

Returns:

receiving data object

hashCode

public int hashCode()

Provide an appropriate hash code useful for storing the receiver in a hash-based data structure.

Overrides:

hashCode in class Object

Returns:

hash code useful for storing the receiver in a hash-based data structure

immutableBytes

protected byte[] immutableBytes()

Privitive method that returns the receiver's data.

Returns:

an immutable byte array that contains the receiver's data

immutableRange

protected NSRange immutableRange()

Privitive method that returns the receiver's range.

Returns:

an immutable NSRange object that specifies the receiver's length.

isEqualToData

public boolean isEqualToData(NSData otherData)

Compares the receiving data object to otherData. Two data objects are equal if they hold the same number of bytes, and if the bytes at the same position in the objects are the same.

Parameters:

otherData - input data object of type NSData

Returns:

true if the contents of otherData are equal to the contents of the receiver, false

length

public int length()

Returns the number of bytes contained by the receiver.

Returns:

the number of bytes contained by the receiver

rangeNoCopy

protected NSRange rangeNoCopy()

Primitive method used by mutable subclasses of NSData.

Returns:

the internal NSRange object that specifies the offset and length of the receiver's data relative to the internal byte array (as returned by bytesNoCopy)

See Also:

bytesNoCopy(), bytesNoCopy(NSMutableRange dataRange)

stream

public ByteArrayInputStream stream()

Returns a stream containing the receiver's data

Returns:

a java.io.ByteArrayInputStream containing the receiver's data

subdataWithRange

public NSData subdataWithRange(NSRange range)

Creates a data object containing a copy of the receiver's bytes that fall within the range specified by range.

Parameters:

range - input range

Returns:

a data object containing a copy of the receiver's bytes that fall within the range specified by range

Throws:

RangeException - if range isn't within the receiver's range of bytes

toString

public String toString()

Returns a string representation of the receiver.

Overrides:

toString in class Object

Returns:

a string representation of the receiver that contains its length, its location, and some of its data.

writeToFile

public boolean writeToFile(String path)

Deprecated.

This method is deprecated in the Java Foundation Framework. Its action will be replaced by following code:

 

 try { 
     FileOutputStream fileOutputStream = new FileOutputStream(path);
     myData.writeToStream(fileOutputStream);
     fileOutputStream.close(); 
 }
 catch (IOException exception) {
     // Do something with the exception
 }
 
 

Parameters:

path - input path of the file

Returns:

returns true if write to file succeeds

writeToStream

public void writeToStream(OutputStream stream)
                   throws IOException

Writes the bytes in the receiver contents to the stream.

Parameters:

stream - the input bytes in the receiver

Throws:

java.io.IOException - if the write fails for any reason.

See Also:

throws java.io.IOException

writeToURL

public boolean writeToURL(URL url,
                          boolean atomically)

Deprecated.

This method is deprecated in the Java Foundation Framework. Its action will be replaced by following code:

 

 try { 
     FileOutputStream fileOutputStream = new FileOutputStream(url.getFile());
     myData.writeToStream(fileOutputStream);
     fileOutputStream.close(); 
 }
 catch (IOException exception) {
     // Do something with the exception
 }
 
 

Parameters:

url - input url

atomically - this parameter is ignored

Returns:

returns true if write to URL succeeds

See Also:

writeToStream(java.io.OutputStream outputStream)