PATH Documentation > WebObjects

Table of Contents

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.

length

public int length()

Returns the number of bytes contained by the receiver.

rangeNoCopy

protected NSRange rangeNoCopy()

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). Used by mutable subclasses of NSData.

stream

public java.io.ByteArrayInputStream stream()

Creates and returns a java.io.ByteArrayInputStream containing the receiver's data.

subdataWithRange

public NSData subdataWithRange(NSRange range)

Returns a data object containing a copy of the receiver's bytes that are fall within the range specified by range. If range isn't within the receiver's range of bytes, a RangeException is thrown.

toString

public String toString()

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 in the Java Foundation Framework. Don't use this method. Use the following code instead:

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



© 2001 Apple Computer, Inc. (Last Published April 17, 2001)


Table of Contents