NSData

Inherits from:
Object

Implements:
Cloneable
java.io.Serializable
NSCoding

Package:
com.webobjects.foundation

Class Description

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.

Table 0-5 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 only ensure that these base methods work properly. Having done so, you can be sure that all your subclass's inherited methods operate properly.

**Table 0-5 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 the subdataWithRange method. To determine if two data objects are equal, use the isEqualToData method, which does a byte-for-byte comparison.

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

Constants

NSData defines the following constant:

Constant	Type	Description
`EmptyData`	NSData	An empty data object, which can be shared to save memory.

Interfaces Implemented

Cloneable

clone

java.io.Serializable

NSCoding

classForCoder
decodeObject
encodeWithCoder

Method Types

Constructors

NSData

Accessing data

bytes
bytesNoCopy
immutableBytes
subdataWithRange

Testing data

immutableRange
length
rangeNoCopy
isEqualToData

Storing data

stream
writeToStream

Methods inherited from Object

equals
hashCode
toString

Deprecated methods

dataWithContentsOfFile
dataWithContentsOfMappedFile
writeToFile
writeToURL

Constructors

NSData

public NSData()

Creates an empty data object.

public NSData(NSData data)

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

public NSData(String string)

Deprecated in the Java Foundation Framework. Don't use this constructor. Use NSData(string.getBytes()) instead.

public NSData(byte[] bytes)

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

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

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

public NSData( byte[] bytes, NSRange range)

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

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

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

public NSData(java.io.File file) throws java.io.IOException

Deprecated in the Java Foundation Framework. Don't use this constructor. Use NSData(new FileInputStream(file),chunkSize) instead.

public NSData( java.io.InputStream inputStream, int chunkSize) throws java.io.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.

public NSData(java.net.URL url) throws java.io.IOException

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);

Static Methods

dataWithContentsOfFile

public static NSData dataWithContentsOfFile(java.io.File file) throws java.io.IOException

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


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

public static NSData dataWithContentsOfFile(String path) throws java.io.IOException

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


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

dataWithContentsOfMappedFile

public static NSData dataWithContentsOfMappedFile(java.io.File file) throws java.io.IOException

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


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

decodeObject

public static Object decodeObject(NSCoder coder)

Creates an NSData from the data in coder.

See Also: NSCoding

Instance Methods

bytes

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

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

public byte[] bytes(NSRange range)

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

public byte[] bytes()

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

bytesNoCopy

protected byte[] bytesNoCopy()

Returns the internal byte array that contains the receiver's data. Due to the internal implementation of NSData, this array 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. Used by mutable subclasses of NSData.

public byte[] bytesNoCopy(NSMutableRange dataRange)

Returns the internal byte array that contains the receiver's data and sets dataRange's offset and length to those of the receiver's internal NSRange object. The receiver's actual data is composed of the returned array's bytes that lie within dataRange. WARNING NSData assumes the internal byte array is immutable. You should not change the contents of this array.

classForCoder

public Class classForCoder()

Conformance to NSCoding. See the method description of classForCoder in the interface specification for NSCoding.

clone

public Object clone()

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

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Conformance to NSCoding. See the method description of encodeWithCoder in the interface specification for NSCoding.

equals

public boolean equals(Object anObject)

Compares the receiving data object to anObject. If anObject is an NSData and the contents of anObject 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.

hashCode

public int hashCode()

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

immutableBytes

protected byte[] immutableBytes()

Returns an immutable byte array that contains the receiver's data.

immutableRange

protected NSRange immutableRange()

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

isEqualToData

public boolean isEqualToData(NSData otherData)

Compares the receiving data object to otherData. If the contents of otherData 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.


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

writeToStream

public void writeToStream(java.io.OutputStream outputStream) throws java.io.IOException

Writes the bytes in the receiver contents to the outputStream. If the write fails for any reason, throws a java.io.IOException.

See Also: writeToStream

writeToURL

public boolean writeToURL( java.net.URL url, boolean atomically)

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


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

See Also: writeToStream