WebObjects 5.4.2

com.webobjects.foundation
Class NSData

java.lang.Object
  extended by com.webobjects.foundation.NSData
All Implemented Interfaces:
NSCoding, Serializable, Cloneable
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:
NSData.bytesNoCopy(), NSData.immutableBytes(), NSData.immutableRange(), NSData.rangeNoCopy(), NSData.isEqualToData(NSData otherData), NSData.subdataWithRange(NSRange range), NSData.writeToStream(java.io.OutputStream outputStream), Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface 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)
          Creates a new NSData from the contents of url.
 
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

@Deprecated
public NSData(File file)
       throws IOException
Deprecated. 

Throws:
IOException
IllegalArgumentException
See Also:
NSData.NSData(InputStream inputStream, int chunkSize)

NSData

public NSData(URL url)
       throws IOException
Creates a new NSData from the contents of url.

Parameters:
url - input url
Throws:
IOException

NSData

@Deprecated
public NSData(String value)
Deprecated. 

This method is deprecated in the Java Foundation Framework.

Parameters:
value - input value as String
See Also:
NSData.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

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:
NSData.rangeNoCopy()

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:
NSData.bytesNoCopy(), NSData.bytesNoCopy(NSMutableRange dataRange)

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.

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

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

dataWithContentsOfMappedFile

@Deprecated
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.
 <blockquote>
  myData = new NSData(new FileInputStream(file), chunkSize);
  </blockquote>
 

Parameters:
file - input java.io.File object
Returns:
an NSData object initialized with the contents of file
Throws:
IOException

dataWithContentsOfFile

@Deprecated
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

@Deprecated
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:

 <blockquote>
  myData = new NSData(new FileInputStream(path), chunkSize);
  </blockquote>
 

Parameters:
path - input path of the file
Returns:
an NSData object initialized with the contents of file at path
Throws:
IOException

length

public int length()
Returns the number of bytes contained by the receiver.

Returns:
the number of bytes contained by the receiver

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

writeToURL

@Deprecated
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:

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

Parameters:
url - input url
atomically - this parameter is ignored
Returns:
returns true if write to URL succeeds
See Also:
NSData.writeToStream(java.io.OutputStream outputStream)

writeToFile

@Deprecated
public boolean writeToFile(String path)
Deprecated. 

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

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

Parameters:
path - input path of the file
Returns:
returns true if write to file succeeds

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

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

stream

public ByteArrayInputStream stream()
Returns a stream containing the receiver's data

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

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.
IOException
See Also:
throws java.io.IOException

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

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 -
See Also:
NSCoder

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

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

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.

Last updated June 2008

Copyright © 2000-2008 Apple Inc.