org.ccnx.ccn.io.CCNFileInputStream Class Reference

A CCN input stream that expects content names to be versioned, and streams to have a Header containing file-level metadata about each stream. More...

List of all members.

Public Member Functions

 CCNFileInputStream (ContentName baseName) throws IOException
 Set up an input stream to read segmented CCN content under a given versioned name.
 CCNFileInputStream (ContentName baseName, CCNHandle handle) throws IOException
 Set up an input stream to read segmented CCN content under a given versioned name.
 CCNFileInputStream (ContentName baseName, PublisherPublicKeyDigest publisher, CCNHandle handle) throws IOException
 Set up an input stream to read segmented CCN content under a given versioned name.
 CCNFileInputStream (ContentName baseName, Long startingSegmentNumber, CCNHandle handle) throws IOException
 Set up an input stream to read segmented CCN content under a given versioned name.
 CCNFileInputStream (ContentName baseName, Long startingSegmentNumber, PublisherPublicKeyDigest publisher, CCNHandle handle) throws IOException
 Set up an input stream to read segmented CCN content under a given versioned name.
 CCNFileInputStream (ContentName baseName, Long startingSegmentNumber, PublisherPublicKeyDigest publisher, ContentKeys keys, CCNHandle handle) throws IOException
 Set up an input stream to read segmented CCN content under a given versioned name.
 CCNFileInputStream (ContentObject startingSegment, EnumSet< FlagTypes > flags, CCNHandle handle) throws IOException
 Set up an input stream to read segmented CCN content starting with a given ContentObject that has already been retrieved.
 CCNFileInputStream (ContentObject startingSegment, ContentKeys keys, EnumSet< FlagTypes > flags, CCNHandle handle) throws IOException
 Set up an input stream to read segmented CCN content starting with a given ContentObject that has already been retrieved.
boolean hasHeader ()
void waitForHeader (Long timeout) throws ContentNotReadyException
 Callers who wish to access the header should call this first; it will wait until the header has been successfully retrieved (if the retrieval has started).
void waitForHeader () throws ContentNotReadyException
Header header () throws ContentNotReadyException, ContentGoneException, ErrorStateException
 Accesses the header data if it has been requested.
ContentObject getFirstSegment () throws IOException
 Once we have retrieved the first segment of this stream using CCNVersionedInputStream.getFirstSegment(), initiate header retrieval.
long skip (long n) throws IOException
void seek (long position) throws IOException
 Seek a stream to a specific byte offset from the start.
long tell () throws IOException
long length () throws IOException
void newVersionAvailable (CCNNetworkObject<?> newVersion, boolean wasSave)
 Notification when a new version is available of a given object (the object's data and version information will already have been updated to reflect the new version).
void close () throws IOException

Protected Member Functions

boolean headerRequested ()
void requestHeader (ContentName baseName, PublisherPublicKeyDigest publisher) throws ContentDecodingException, IOException
 Request the header in the background.
int segmentCount () throws IOException

Protected Attributes

HeaderObject _header = null
 The header information for that object, once we've read it.
HeaderObject _oldHeader = null
 Temporary backwards-compatibility move.

Detailed Description

A CCN input stream that expects content names to be versioned, and streams to have a Header containing file-level metadata about each stream.

See CCNVersionedInputStream for a description of versioning behavior, and CCNFileOutputStream for a description of header information. The header is read asynchronously, and may not be available at all until the complete stream has been written (in other words, the publisher typically writes the header last). Stream data can be read normally before the header has been read, and the consumer may opt to ignore the header completely, in which case this acts exactly like a CCNVersionedInputStream. In fact, a CCNVersionedInputStream can be used to read data read by CCNFileOutputStream (except for the header). Using a CCNFileInputStream to read something not written by a CCNFileOutputStream or one of its subclasses (in other words, something without a header) will still try to retrieve the (nonexistent) header in the background, but will not cause an error unless someone tries to access the header data itself.

Headers are named according to definitions in the SegmentationProfile.


Constructor & Destructor Documentation

org.ccnx.ccn.io.CCNFileInputStream.CCNFileInputStream ( ContentName  baseName  )  throws IOException

Set up an input stream to read segmented CCN content under a given versioned name.

Content is assumed to be unencrypted, or keys will be retrieved automatically via another process. Will use the default handle given by CCNHandle.getHandle(). Note that this constructor does not currently retrieve any data; data is not retrieved until read() is called. This will change in the future, and this constructor will retrieve the first block.

Parameters:
baseName Name to read from. If it ends with a version, will retrieve that specific version. If not, will find the latest version available. If it ends with both a version and a segment number, will start to read from that segment of that version.
Exceptions:
IOException Not currently thrown, will be thrown when constructors retrieve first block.
org.ccnx.ccn.io.CCNFileInputStream.CCNFileInputStream ( ContentName  baseName,
CCNHandle  handle 
) throws IOException

Set up an input stream to read segmented CCN content under a given versioned name.

Content is assumed to be unencrypted, or keys will be retrieved automatically via another process. Will use the default handle given by CCNHandle.getHandle(). Note that this constructor does not currently retrieve any data; data is not retrieved until read() is called. This will change in the future, and this constructor will retrieve the first block.

Parameters:
baseName Name to read from. If it ends with a version, will retrieve that specific version. If not, will find the latest version available. If it ends with both a version and a segment number, will start to read from that segment of that version.
handle The CCN handle to use for data retrieval. If null, the default handle given by CCNHandle.getHandle() will be used.
Exceptions:
IOException Not currently thrown, will be thrown when constructors retrieve first block.
org.ccnx.ccn.io.CCNFileInputStream.CCNFileInputStream ( ContentName  baseName,
PublisherPublicKeyDigest  publisher,
CCNHandle  handle 
) throws IOException

Set up an input stream to read segmented CCN content under a given versioned name.

Content is assumed to be unencrypted, or keys will be retrieved automatically via another process. Will use the default handle given by CCNHandle.getHandle(). Note that this constructor does not currently retrieve any data; data is not retrieved until read() is called. This will change in the future, and this constructor will retrieve the first block.

Parameters:
baseName Name to read from. If it ends with a version, will retrieve that specific version. If not, will find the latest version available. If it ends with both a version and a segment number, will start to read from that segment of that version.
publisher The key we require to have signed this content. If null, will accept any publisher (subject to higher-level verification).
handle The CCN handle to use for data retrieval. If null, the default handle given by CCNHandle.getHandle() will be used.
Exceptions:
IOException Not currently thrown, will be thrown when constructors retrieve first block.
org.ccnx.ccn.io.CCNFileInputStream.CCNFileInputStream ( ContentName  baseName,
Long  startingSegmentNumber,
CCNHandle  handle 
) throws IOException

Set up an input stream to read segmented CCN content under a given versioned name.

Content is assumed to be unencrypted, or keys will be retrieved automatically via another process. Will use the default handle given by CCNHandle.getHandle(). Note that this constructor does not currently retrieve any data; data is not retrieved until read() is called. This will change in the future, and this constructor will retrieve the first block.

Parameters:
baseName Name to read from. If it ends with a version, will retrieve that specific version. If not, will find the latest version available. If it ends with both a version and a segment number, will start to read from that segment of that version.
startingSegmentNumber Alternative specification of starting segment number. If null, will be SegmentationProfile.baseSegment().
handle The CCN handle to use for data retrieval. If null, the default handle given by CCNHandle.getHandle() will be used.
Exceptions:
IOException Not currently thrown, will be thrown when constructors retrieve first block.
org.ccnx.ccn.io.CCNFileInputStream.CCNFileInputStream ( ContentName  baseName,
Long  startingSegmentNumber,
PublisherPublicKeyDigest  publisher,
CCNHandle  handle 
) throws IOException

Set up an input stream to read segmented CCN content under a given versioned name.

Content is assumed to be unencrypted, or keys will be retrieved automatically via another process. Will use the default handle given by CCNHandle.getHandle(). Note that this constructor does not currently retrieve any data; data is not retrieved until read() is called. This will change in the future, and this constructor will retrieve the first block.

Parameters:
baseName Name to read from. If it ends with a version, will retrieve that specific version. If not, will find the latest version available. If it ends with both a version and a segment number, will start to read from that segment of that version.
startingSegmentNumber Alternative specification of starting segment number. If null, will be SegmentationProfile.baseSegment().
publisher The key we require to have signed this content. If null, will accept any publisher (subject to higher-level verification).
handle The CCN handle to use for data retrieval. If null, the default handle given by CCNHandle.getHandle() will be used.
Exceptions:
IOException Not currently thrown, will be thrown when constructors retrieve first block.
org.ccnx.ccn.io.CCNFileInputStream.CCNFileInputStream ( ContentName  baseName,
Long  startingSegmentNumber,
PublisherPublicKeyDigest  publisher,
ContentKeys  keys,
CCNHandle  handle 
) throws IOException

Set up an input stream to read segmented CCN content under a given versioned name.

Will use the default handle given by CCNHandle.getHandle(). Note that this constructor does not currently retrieve any data; data is not retrieved until read() is called. This will change in the future, and this constructor will retrieve the first block.

Parameters:
baseName Name to read from. If it ends with a version, will retrieve that specific version. If not, will find the latest version available. If it ends with both a version and a segment number, will start to read from that segment of that version.
startingSegmentNumber Alternative specification of starting segment number. If null, will be SegmentationProfile.baseSegment().
publisher The key we require to have signed this content. If null, will accept any publisher (subject to higher-level verification).
keys The keys to use to decrypt this content. If null, assumes content unencrypted, or another process will be used to retrieve the keys.
handle The CCN handle to use for data retrieval. If null, the default handle given by CCNHandle.getHandle() will be used.
Exceptions:
IOException Not currently thrown, will be thrown when constructors retrieve first block.
org.ccnx.ccn.io.CCNFileInputStream.CCNFileInputStream ( ContentObject  startingSegment,
EnumSet< FlagTypes >  flags,
CCNHandle  handle 
) throws IOException

Set up an input stream to read segmented CCN content starting with a given ContentObject that has already been retrieved.

Content is assumed to be unencrypted, or keys will be retrieved automatically via another process.

Parameters:
startingSegment The first segment to read from. If this is not the first segment of the stream, reading will begin from this point. We assume that the signature on this segment was verified by our caller.
flags any stream flags that must be set to handle even this first block (otherwise they can be set with setFlags prior to read). Can be null.
handle The CCN handle to use for data retrieval. If null, the default handle given by CCNHandle.getHandle() will be used.
Exceptions:
IOException 
org.ccnx.ccn.io.CCNFileInputStream.CCNFileInputStream ( ContentObject  startingSegment,
ContentKeys  keys,
EnumSet< FlagTypes >  flags,
CCNHandle  handle 
) throws IOException

Set up an input stream to read segmented CCN content starting with a given ContentObject that has already been retrieved.

Parameters:
startingSegment The first segment to read from. If this is not the first segment of the stream, reading will begin from this point. We assume that the signature on this segment was verified by our caller.
keys The keys to use to decrypt this content. Null if content unencrypted, or another process will be used to retrieve the keys.
flags any stream flags that must be set to handle even this first block (otherwise they can be set with setFlags prior to read). Can be null.
handle The CCN handle to use for data retrieval. If null, the default handle given by CCNHandle.getHandle() will be used.
Exceptions:
IOException 

Member Function Documentation

boolean org.ccnx.ccn.io.CCNFileInputStream.hasHeader (  ) 
Returns:
true if we have retrieved the header.
Header org.ccnx.ccn.io.CCNFileInputStream.header (  )  throws ContentNotReadyException, ContentGoneException, ErrorStateException

Accesses the header data if it has been requested.

Returns:
the Header for this stream.
Exceptions:
ContentNotReadyException if we have not retrieved the header yet, or it hasn't been requested.
ContentGoneException if the header has been deleted.
ErrorStateException 
boolean org.ccnx.ccn.io.CCNFileInputStream.headerRequested (  )  [protected]
Returns:
true if we have started the header retrieval process. To begin the process, we must first know what version of the content we are reading.
long org.ccnx.ccn.io.CCNFileInputStream.length (  )  throws IOException
Returns:
Total length of the stream, if known, otherwise -1.
Exceptions:
IOException 

Reimplemented from org.ccnx.ccn.io.CCNAbstractInputStream.

void org.ccnx.ccn.io.CCNFileInputStream.newVersionAvailable ( CCNNetworkObject<?>  newVersion,
boolean  wasSave 
)

Notification when a new version is available of a given object (the object's data and version information will already have been updated to reflect the new version).

Parameters:
newVersion The newly updated object.
wasSave If true, someone called save() on this particular object, if false, the object received new data from the network.

Implements org.ccnx.ccn.io.content.UpdateListener.

void org.ccnx.ccn.io.CCNFileInputStream.requestHeader ( ContentName  baseName,
PublisherPublicKeyDigest  publisher 
) throws ContentDecodingException, IOException [protected]

Request the header in the background.

Parameters:
baseName name of the content, including the version, from which the header name will be derived.
publisher expected publisher
Exceptions:
IOException If the header cannot be retrieved.
ContentDecodingException If the header cannot be decoded.
void org.ccnx.ccn.io.CCNFileInputStream.seek ( long  position  )  throws IOException

Seek a stream to a specific byte offset from the start.

Tries to avoid retrieving extra segments.

Parameters:
position 
Exceptions:
IOException 

Reimplemented from org.ccnx.ccn.io.CCNAbstractInputStream.

int org.ccnx.ccn.io.CCNFileInputStream.segmentCount (  )  throws IOException [protected]
Returns:
Currently returns 0. Can be optionally overridden by subclasses.
Exceptions:
IOException 

Reimplemented from org.ccnx.ccn.io.CCNAbstractInputStream.

long org.ccnx.ccn.io.CCNFileInputStream.tell (  )  throws IOException
Returns:
Returns position in byte offset. For CCNAbstractInputStream, provide an inadequate base implementation that returns the offset into the current segment (not the stream as a whole).
Exceptions:
IOException 

Reimplemented from org.ccnx.ccn.io.CCNAbstractInputStream.

void org.ccnx.ccn.io.CCNFileInputStream.waitForHeader ( Long  timeout  )  throws ContentNotReadyException

Callers who wish to access the header should call this first; it will wait until the header has been successfully retrieved (if the retrieval has started).

Exceptions:
ContentNotReadyException if we have not requested the header yet.

Member Data Documentation

Temporary backwards-compatibility move.

..


The documentation for this class was generated from the following file:
Generated on Fri May 13 16:27:44 2011 for Content-Centric Networking in Java by  doxygen 1.6.3