com.adobe.acrobat.bytearray
Class ByteArray

java.lang.Object
  |
  +--com.adobe.acrobat.bytearray.ByteArray

public abstract class ByteArray
extends java.lang.Object

An abstract class that encapsulates an ordered, arbitrarily sized array of bytes.

A ByteArray's contents are accessed via InputStreams, which are created in the createStream method, which takes a ContiguousByteRange describing a set of bytes and returns an InputStream returning the bytes at the positions defined by the ContiguousByteRange object in order.

Implementers of subclasses of ByteArray must be able to guarantee that the contents of the ByteArray are invariant--i.e., if the nth byte of a given ByteArray is x today, it had better be x tomorrow. If during normal execution a ByteArray "discovers" that it is unable to satisfy this invariant (say, a file's contents on disk change spontaneously), it must turn "invalid."

A more precise, but less readable, way of expressing the invariant described above follows:

Given the following definition:

The following invariant must be preserved by all implementers of ByteArray subclasses:

For any two invokations of fetchBytes(br1) and fetchBytes(br2), where i1 is the InputStream returned by the first invokation and i2 is the InputStream returned by the second invokation, for any integer value n where n is contained in br1 and br2, b(i1, o(br1, n)) == b(i2, o(br2, n)).

A ByteArray is "invalid" if it is unable to reliably satisfy this constraint.

Version:
1.1 8 April 1997 Copyright (c) 1997, Adobe Systems Inc., All Rights Reserved.

Constructor Summary
protected ByteArray(ByteArraySource source)
          Create a new ByteArray From Source.

 

Method Summary
protected  int computeLength()
          Called by getLength, and only once in the lifetime of the ByteArray.
protected  void confirmValid()
          Implementors of ByteArray subclasses might want to override this to provide on-the-fly checking for validity even if no byte-range requests are taking place.
protected abstract  java.io.InputStream createStream(ContiguousByteRange br)
          Create an InputStream based on the bytes delimited by the given ContiguousByteRange.
 int findBytes(byte[] bytes, int start, int numToScan, boolean forward, int pageSize)
          Locate the given sequence of bytes in this ByteArray with the given search criteria.
 int findString(java.lang.String s, int start, int numToScan, boolean forward, int pageSize)
          Search for the given String in the ByteArray subject to the given search criteria.
 ByteArraySource getByteArraySource()
          Get the associated ByteArraySource.
 void getBytes(ContiguousByteRange br, byte[] b)
          Fill the array of bytes with the bytes from the given ContiguousByteRange.
 void getBytes(ContiguousByteRange br, byte[] b, int offset)
          Fill the array of bytes starting at the element at the given offset with the bytes delimited by the given ContiguousByteRange.
 void getBytes(int pos, byte[] b)
          Fill the array of bytes b with bytes from this ByteArray starting at the given position to the end of b.
 void getBytes(int pos, int len, byte[] b, int offset)
          Fill the array of bytes b, starting at offset, with the len bytes in this ByteArray starting at pos.
 java.io.InputStream getByteStream(ContiguousByteRange br)
          Get an InputStream that returns the bytes delimited by the given ContiguousByteRange in order by index.
 java.io.InputStream getByteStream(int offset)
          Get an InputStream that returns the bytes beginning at the given offset to the end of the ByteArray.
 java.io.InputStream getByteStream(int offset, int len)
          Get an InputStream that returns the bytes beginning at the given offset to the end of the ByteArray or after len bytes, whichever comes first.
 int getLength()
           
protected  boolean isValid()
          Returns true if the ByteArray is valid.
protected  void setInvalid(java.io.IOException exception)
          Marks the ByteArray as invalid.
protected  void throwIfInvalid()
          If the ByteArray is invalid, throw the exception that caused it to be invalid.

 

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Constructor Detail

ByteArray

protected ByteArray(ByteArraySource source)
Create a new ByteArray From Source.

Method Detail

getByteArraySource

public ByteArraySource getByteArraySource()
Get the associated ByteArraySource.

getByteStream

public java.io.InputStream getByteStream(ContiguousByteRange br)
                                  throws java.io.IOException
Get an InputStream that returns the bytes delimited by the given ContiguousByteRange in order by index.
Parameters:
br - the ContiguousByteRange describing which subset of the ByteArray's bytes were requested
Returns:
an InputStream which streams, in increasing order by byte-offset, the bytes at all the positions described by the given ContiguousByteRange
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown

getByteStream

public java.io.InputStream getByteStream(int offset)
                                  throws java.io.IOException
Get an InputStream that returns the bytes beginning at the given offset to the end of the ByteArray.
Parameters:
offset - the offset at which to start reading bytes
Returns:
an InputStream that streams all the bytes from offset to the end of the ByteArray
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown
See Also:
getByteStream(ContiguousByteRange)

getByteStream

public java.io.InputStream getByteStream(int offset,
                                         int len)
                                  throws java.io.IOException
Get an InputStream that returns the bytes beginning at the given offset to the end of the ByteArray or after len bytes, whichever comes first.
Parameters:
offset - the offset at which to start reading bytes
len - the maximum number of bytes to read before the stream terminates
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown
See Also:
getByteStream(ContiguousByteRange)

getBytes

public void getBytes(ContiguousByteRange br,
                     byte[] b,
                     int offset)
              throws java.io.IOException
Fill the array of bytes starting at the element at the given offset with the bytes delimited by the given ContiguousByteRange. This is equivalent to getting InputStream represented by the given ContiguousByteRange and streaming its contents into the provided buffer starting offset bytes into the buffer. Bytes in b before offset or after (and including) offset + the length of br will not be altered.

Implmenters of subclasses of ByteArray may wish to override this method for performance reasons. They must respect the above invariants.

Parameters:
br - the subrange of this ByteArray which is to be read into b
b - the array of bytes into which this ByteArray's contents are to be read
offset - the start offset in b at which bytes are to be written
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown

getBytes

public void getBytes(ContiguousByteRange br,
                     byte[] b)
              throws java.io.IOException
Fill the array of bytes with the bytes from the given ContiguousByteRange. The first byte is stored in b[0] and ends at b[br.length() - 1].
Parameters:
br - the subrange of bytes requested
b - the buffer into which to write the bytes.
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown
See Also:
getBytes(ContiguousByteRange, byte[], int)

getBytes

public void getBytes(int pos,
                     int len,
                     byte[] b,
                     int offset)
              throws java.io.IOException
Fill the array of bytes b, starting at offset, with the len bytes in this ByteArray starting at pos.
Parameters:
pos - the starting position in this ByteArray from which to copy bytes
len - the number of bytes to copy
b - the buffer into which to copy the bytes
offset - the offset into b at which to start copying
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown
See Also:
getBytes(ContiguousByteRange, byte[], int)

getBytes

public void getBytes(int pos,
                     byte[] b)
              throws java.io.IOException
Fill the array of bytes b with bytes from this ByteArray starting at the given position to the end of b. If this ByteArray ends before the end of b is reached, subsequent vaules in b go unchanged.
Parameters:
pos - the position in this ByteArray from which to start copying bytes
b - the array of bytes into which bytes should be copied
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown
See Also:
getBytes(ContiguousByteRange, byte[], int)

getLength

public int getLength()
              throws java.io.IOException

findBytes

public int findBytes(byte[] bytes,
                     int start,
                     int numToScan,
                     boolean forward,
                     int pageSize)
              throws java.io.IOException
Locate the given sequence of bytes in this ByteArray with the given search criteria.
Parameters:
bytes - Array of bytes to search for.
start - Offset where to start looking. If search is backwards, search will not return an index >= start.
numToScan - Number of bytes to scan before giving up, -1 indicates search to the end. The sequence must be located completely within numToScan bytes for a successful result.
forward - true if search should move forward from start; false if backward
pageSize - number of bytes to request at a time from the ByteArray (-1 for default). This search will never request a chunk of bytes larger than this.
Returns:
Offset of the beginning of the matching subsequence; -1 if not found
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown

findString

public int findString(java.lang.String s,
                      int start,
                      int numToScan,
                      boolean forward,
                      int pageSize)
               throws java.io.IOException
Search for the given String in the ByteArray subject to the given search criteria. The characters in the String are converted to bytes using Util.rawBytesFromString, and then passed on to findBytes.
Parameters:
s - the String to search for.
start - Offset where to start looking. If search is backwards, search will not return an index >= start.
numToScan - Number of bytes to scan before giving up, -1 indicates search to the end. The sequence must be located completely within numToScan bytes for a successful result.
forward - true if search should move forward from start; false if backward
pageSize - number of bytes to request at a time from the ByteArray (-1 for default). This search will never request a chunk of bytes larger than this.
Returns:
Offset of the beginning of the matching subsequence; -1 if not found
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown

createStream

protected abstract java.io.InputStream createStream(ContiguousByteRange br)
                                             throws java.io.IOException
Create an InputStream based on the bytes delimited by the given ContiguousByteRange. Implementers of ByteArray subclasses must override this, and provide a stream that respects the ByteArray invariants enumerated above.
Parameters:
br - the ContiguousByteRange delimiting the requested bytes
Returns:
an InputStream that streams, in order, the bytes from this ByteArray described by br
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown
See Also:
ByteRangeInputStream

setInvalid

protected void setInvalid(java.io.IOException exception)
Marks the ByteArray as invalid. The given exception will be thrown every time any of the ByteArray's methods are called thereafter.
Parameters:
exception - The exception to throw on this and future uses of the ByteArray.

computeLength

protected int computeLength()
                     throws java.io.IOException
Called by getLength, and only once in the lifetime of the ByteArray. The default implementation simply creates an unbounded InputStream and consumes it in its entirety, counting every byte; since this is likely a very expensive operation, this method ought to be overridden in subclasses where it is possible to perform the computation more efficiently.
Returns:
the number of bytes in the ByteArray
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown

throwIfInvalid

protected void throwIfInvalid()
                       throws java.io.IOException
If the ByteArray is invalid, throw the exception that caused it to be invalid.
Throws:
java.io.IOException - the IOException describes why this ByteArray is invalid.

isValid

protected boolean isValid()
Returns true if the ByteArray is valid.
Returns:
whether or not this ByteArray is valid

confirmValid

protected void confirmValid()
                     throws java.io.IOException
Implementors of ByteArray subclasses might want to override this to provide on-the-fly checking for validity even if no byte-range requests are taking place. If an exception is thrown, the ByteArray is marked as invalid with said Exception.
Throws:
java.io.IOException - arbitrary IOExceptions may be thrown