com.adobe.acrobat.file
Class ByteArraySource

java.lang.Object
  |
  +--com.adobe.acrobat.file.ByteArraySource

public abstract class ByteArraySource
extends java.lang.Object

Abstract superclass of objects that function as "handles" to potentially changeable arrays of bytes. A ByteArraySource can, at any time, "create" a ByteArray whose immutable contents represent the potentially very large sequence of octets "pointed to" by this ByteArraySource. Implementers of subclasses of ByteArraySource are required to implement the getByteArray method, which creates a ByteArray which represents the contents associated with the ByteArraySource at the time of the call.

ByteArraySources also provide relative simple file specification resoluation: they are capable of returning a new ByteArraySource object representing the entity located relative to this ByteArraySource by a file-spec String as described in the PDF spec.

Subclasses of ByteArraySource are usually associated with unique subclasses of ByteArray. When the contents associated with a ByteArraySource change, the associated ByteArray should turn "invalid" (see ByteArray.setInvalid), and the user of the ByteArray should take this as a signal that getByteArray needs to be called, and all structures dependent upon the contents of the old ByteArray ought to be updated.

For example, URLByteArraySource, which is a ByteArraySource associated with a single URL, creates a URLByteArray which is created based on the entity-body received from a HTTP GET request on said URL. If, in the case of byte-served connections with multiple requests, it is discovered that the creation date or last mod date of the entity has changed, the old URLByteArray should turn invalid and the client should ask the URLByteArraySource for a new ByteArray. The FaultLine viewer handles this eventuality transparently, but the onus is on the ByteArray implementer to detect invalidation in such a way as to conform to the immutability requirements enumerated in the documentation on ByteArray.

Version:
1.0 12 November 1997 Copyright (c) 1997, Adobe Systems Inc., All Rights Reserved.

Constructor Summary
ByteArraySource()
           

 

Method Summary
 void close()
          For ByteArraySources that can have their input streams or files closed
 void decRefCount()
           
abstract  ByteArray getByteArray()
          Get the ByteArray associated with this ByteArraySource.
abstract  ByteArraySource getByteArraySourceRelative(java.lang.String fileSpecString)
          Get the ByteArraySource relative to this ByteArraySource by the given simple file specification.
 java.lang.String getFullName()
          Get a Full Path Name for a ByteArraySource, or return null if that's not a meaningful notion.
 com.adobe.acrobat.file.ByteArraySourceSpace getSourceSpace()
          For registered file systems, this is the ByteArraySourceSpace associated with this ByteArraySource.
 java.lang.String getTitle()
          Get the "title" of this ByteArraySource, if any.
 java.net.URL getURL()
          Get a URL that is equivalent to this ByteArraySource, or return null if that's not a meaningful notion.
 void incRefCount()
          maintain reference count for this byte array source

 

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

 

Constructor Detail

ByteArraySource

public ByteArraySource()
Method Detail

getByteArraySourceRelative

public abstract ByteArraySource getByteArraySourceRelative(java.lang.String fileSpecString)
                                                    throws java.lang.Exception
Get the ByteArraySource relative to this ByteArraySource by the given simple file specification. The simple file specification is not necessarily relative.
Parameters:
fileSpecString - a String describing a location of another ByteArraySource, potentially positioned relative to this ByteArraySource
Returns:
a ByteArraySource located relative to this ByteArraySource by the given simple file specification string.
Throws:
java.lang.Exception - arbitrary exceptions may be thrown

getByteArray

public abstract ByteArray getByteArray()
                                throws java.lang.Exception
Get the ByteArray associated with this ByteArraySource. Implementers must override this method to provide what is logically a snapshot of the associated entity. When the "contents" associated with this ByteArraySource change, it would be wise to mark past ByteArrays returned by this method as invalid.
Returns:
a ByteArray representing this ByteArraySource's contents at a particular point in time
Throws:
java.lang.Exception - arbitrary exceptions may be thrown

getURL

public java.net.URL getURL()
Get a URL that is equivalent to this ByteArraySource, or return null if that's not a meaningful notion. Implementers may override this at their discretion.
Returns:
a URL whose contents map to this ByteArraySource's contents, or null if no such URL exists

getFullName

public java.lang.String getFullName()
Get a Full Path Name for a ByteArraySource, or return null if that's not a meaningful notion.

getTitle

public java.lang.String getTitle()
Get the "title" of this ByteArraySource, if any. This should be a user-sensible representation--for example, for files, this is the name of the file (not the full path). Implementers are strongly encouraged, but not required, to override this method. A ByteArraySource's title should never change, so the title should not be derived from the changeable contents of the ByteArray.
Returns:
the title of this ByteArraySource for the purposes of display in the user interface.

getSourceSpace

public com.adobe.acrobat.file.ByteArraySourceSpace getSourceSpace()
For registered file systems, this is the ByteArraySourceSpace associated with this ByteArraySource. Implementers should only override this method if this ByteArraySource is associated with a registered ByteArraySourceSpace.
Returns:
the ByteArraySourceSpace which created this ByteArraySource, or null if there is no such ByteArraySourceSpace

incRefCount

public void incRefCount()
maintain reference count for this byte array source

decRefCount

public void decRefCount()
                 throws java.lang.Exception

close

public void close()
           throws java.lang.Exception
For ByteArraySources that can have their input streams or files closed
Throws:
java.lang.Exception - in case a subclass wants to throw an exception