org.ccnx.ccn.io.CCNAbstractInputStream Class Reference

This abstract class is the superclass of all classes representing an input stream of bytes segmented and stored in CCN. More...

List of all members.

Classes

class  IncomingSegment

Public Types

enum  FlagTypes { DONT_DEREFERENCE }

Public Member Functions

 CCNAbstractInputStream (ContentName baseName, Long startingSegmentNumber, PublisherPublicKeyDigest publisher, ContentKeys keys, EnumSet< FlagTypes > flags, CCNHandle handle) throws IOException
 Set up an input stream to read segmented CCN content under a given name.
 CCNAbstractInputStream (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 readerReadyCheck (long nextSegment)
Interest handleContent (ContentObject result, Interest interest)
 Callback called when we get new results for our query.
void setTimeout (int timeout)
 Set the timeout that will be used for all content retrievals on this stream.
void addFlags (EnumSet< FlagTypes > additionalFlags)
 Add flags to this stream.
void addFlag (FlagTypes additionalFlag)
 Add a flag to this stream.
void setFlags (EnumSet< FlagTypes > flags)
 Set flags on this stream.
void clearFlags ()
 Clear the flags on this stream.
void removeFlag (FlagTypes flag)
 Remove a flag from this stream.
boolean hasFlag (FlagTypes flag)
 Check whether this stream has a particular flag set.
ContentName getBaseName ()
CCNTime getVersion ()
byte[] getFirstDigest () throws NoMatchingContentFoundException, IOException
 Returns the digest of the first segment of this stream.
int read () throws IOException
int read (byte[] b) throws IOException
int read (byte[] buf, int offset, int len) throws IOException
ContentObject getFirstSegment () throws IOException
 Retrieves the first segment of the stream, based on specified startingSegmentNumber (see CCNAbstractInputStream(ContentName, Long, PublisherPublicKeyDigest, ContentKeys, CCNHandle)).
synchronized LinkObject getDereferencedLink ()
 If we traversed a link to get this object, make it available.
long firstSegmentNumber ()
 Returns the first segment number for this stream.
long nextSegmentNumber ()
 Returns the segment number for the next segment.
long segmentNumber ()
boolean isGone () throws NoMatchingContentFoundException, IOException
 Checks to see whether this content has been marked as GONE (deleted).
ContentObject deletionInformation ()
 Return the single segment of a stream marked as GONE.
PublisherPublicKeyDigest publisher ()
 Callers may need to access information about this stream's publisher.
KeyLocator publisherKeyLocator () throws IOException
String currentSegmentName ()
int available () throws IOException
boolean eof ()
void close () throws IOException
synchronized void mark (int readlimit)
boolean markSupported ()
synchronized void reset () throws IOException
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

Protected Member Functions

abstract int readInternal (byte[] buf, int offset, int len) throws IOException
 Actual mechanism used to trigger segment retrieval and perform content reads.
void setFirstSegment (ContentObject newSegment) throws IOException
 Called to set the first segment when opening a stream.
void setCurrentSegment (ContentObject newSegment) throws IOException
 Set up current segment for reading, including preparation for decryption if necessary.
void rewindSegment () throws IOException
 Rewinds read buffers for current segment to beginning of the segment.
ContentObject getSegment (long number) throws IOException
 Retrieves a specific segment of this stream, indicated by segment number.
boolean hasNextSegment () throws IOException
 Checks whether we might have a next segment.
ContentObject getNextSegment () throws IOException
 Retrieve the next segment of the stream.
boolean isFirstSegment (ContentName desiredName, ContentObject segment)
 Method to determine whether a retrieved block is the first segment of this stream (as specified by startingSegmentNumber, (see CCNAbstractInputStream(ContentName, Long, PublisherPublicKeyDigest, ContentKeys, CCNHandle)).
synchronized void setDereferencedLink (LinkObject dereferencedLink)
 Use only if you know what you are doing.
synchronized void pushDereferencedLink (LinkObject dereferencedLink)
 Add a LinkObject to the stack we had to dereference to get here.
long currentSegmentNumber ()
int segmentCount () throws IOException

Protected Attributes

CCNHandle _handle
 Flags: DONT_DEREFERENCE to prevent dereferencing in case we are attempting to read a link.
LinkObject _dereferencedLink = null
 The Link we dereferenced to get here, if any.
EnumSet< FlagTypes > _flags = EnumSet.noneOf(FlagTypes.class)
ContentObject _currentSegment = null
 The segment we are currently reading from.
InputStream _segmentReadStream = null
 Internal stream used for buffering reads.
ContentName _baseName = null
 The name prefix of the segmented stream we are reading, up to (but not including) a segment number.
PublisherPublicKeyDigest _publisher = null
 The publisher we are looking for, either specified by querier on initial read, or read from previous blocks (for now, we assume that all segments in a stream are created by the same publisher).
Long _startingSegmentNumber = null
 The segment number to start with.
int _timeout = SystemConfiguration.getDefaultTimeout()
 The timeout to use for segment retrieval.
Cipher _cipher
 Encryption/decryption handler.
ContentKeys _keys
byte[] _verifiedRootSignature = null
 If this content uses Merkle Hash Trees or other bulk signatures to amortize signature cost, we can amortize verification cost as well by caching verification data as follows: store the currently-verified root signature, so we don't have to re-verify it; and the verified root hash.
byte[] _verifiedProxy = null
boolean _atEOF = false
int _readlimit = 0
 Used for mark(int) and reset().
int _markOffset = 0
long _markBlock = 0
ArrayList< ContentObjectinOrderSegments = new ArrayList<ContentObject>()
ArrayList< ContentObjectoutOfOrderSegments = new ArrayList<ContentObject>()
long _nextPipelineSegment = -1
long _lastRequestedPipelineSegment = -1
long _lastInOrderSegment = -1
ContentName _basePipelineName = null
long _lastSegmentNumber = -1
ArrayList< Interest_sentInterests = new ArrayList<Interest>()

Detailed Description

This abstract class is the superclass of all classes representing an input stream of bytes segmented and stored in CCN.

See also:
SegmentationProfile for description of CCN segmentation

Constructor & Destructor Documentation

org.ccnx.ccn.io.CCNAbstractInputStream.CCNAbstractInputStream ( ContentName  baseName,
Long  startingSegmentNumber,
PublisherPublicKeyDigest  publisher,
ContentKeys  keys,
EnumSet< FlagTypes >  flags,
CCNHandle  handle 
) throws IOException

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

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 contains a segment number, will start to read from that segment.
startingSegmentNumber Alternative specification of starting segment number. If unspecified, 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. Null if 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.CCNAbstractInputStream.CCNAbstractInputStream ( 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.
any flags necessary for processing this stream; have to hand in in constructor in case first segment provided, so can apply to that segment
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

void org.ccnx.ccn.io.CCNAbstractInputStream.addFlag ( FlagTypes  additionalFlag  ) 

Add a flag to this stream.

Adds to existing flags.

void org.ccnx.ccn.io.CCNAbstractInputStream.addFlags ( EnumSet< FlagTypes >  additionalFlags  ) 

Add flags to this stream.

Adds to existing flags.

String org.ccnx.ccn.io.CCNAbstractInputStream.currentSegmentName (  ) 
Returns:
the name of the current segment held by this string, or "null". Used for debugging.
long org.ccnx.ccn.io.CCNAbstractInputStream.currentSegmentNumber (  )  [protected]
Returns:
Returns the segment number of the current segment if we have one, otherwise -1.
ContentObject org.ccnx.ccn.io.CCNAbstractInputStream.deletionInformation (  ) 

Return the single segment of a stream marked as GONE.

This method should be called only after checking isGone() == true otherwise it may return the wrong result.

Returns:
the GONE segment or null if state unknown or stream is not marked GONE
boolean org.ccnx.ccn.io.CCNAbstractInputStream.eof (  ) 
Returns:
Whether this stream believes it is at eof (has read past the end of the last segment of the stream).
long org.ccnx.ccn.io.CCNAbstractInputStream.firstSegmentNumber (  ) 

Returns the first segment number for this stream.

Returns:
The index of the first segment of stream data.
ContentName org.ccnx.ccn.io.CCNAbstractInputStream.getBaseName (  ) 
Returns:
The name used to retrieve segments of this stream (not including the segment number).
byte [] org.ccnx.ccn.io.CCNAbstractInputStream.getFirstDigest (  )  throws NoMatchingContentFoundException, IOException

Returns the digest of the first segment of this stream.

Together with firstSegmentNumber() and getBaseName() this method may be used to identify the stream content unambiguously.

Returns:
The digest of the first segment of this stream
Exceptions:
NoMatchingContentException if no content available
IOException on communication error
ContentObject org.ccnx.ccn.io.CCNAbstractInputStream.getFirstSegment (  )  throws IOException

Retrieves the first segment of the stream, based on specified startingSegmentNumber (see CCNAbstractInputStream(ContentName, Long, PublisherPublicKeyDigest, ContentKeys, CCNHandle)).

Returns:
the first segment, if found.
Exceptions:
IOException If can't get a valid starting segment number

Reimplemented in org.ccnx.ccn.io.CCNFileInputStream, and org.ccnx.ccn.io.CCNVersionedInputStream.

ContentObject org.ccnx.ccn.io.CCNAbstractInputStream.getNextSegment (  )  throws IOException [protected]

Retrieve the next segment of the stream.

Convenience method, uses getSegment(long).

Returns:
the next segment, if found.
Exceptions:
IOException 
ContentObject org.ccnx.ccn.io.CCNAbstractInputStream.getSegment ( long  number  )  throws IOException [protected]

Retrieves a specific segment of this stream, indicated by segment number.

Three navigation options: get first (leftmost) segment, get next segment, or get a specific segment. Have to assume that everyone is using our segment number encoding. Probably easier to ask raw streams to use that encoding (e.g. for packet numbers) than to flag streams as to whether they are using integers or segments.

Parameters:
number Segment number to retrieve. See SegmentationProfile for numbering. If we already have this segment as currentSegmentNumber(), will just return the current segment, and will not re-retrieve it from the network.
Exceptions:
IOException If no matching content found (actually throws NoMatchingContentFoundException) or if there is an error at lower layers.
CCNTime org.ccnx.ccn.io.CCNAbstractInputStream.getVersion (  ) 
Returns:
The version of the stream being read, if its name is versioned.
Interest org.ccnx.ccn.io.CCNAbstractInputStream.handleContent ( ContentObject  data,
Interest  interest 
)

Callback called when we get new results for our query.

Parameters:
data the ContentObject that matched our Interest
interest Interest that was satisfied
Returns:
new Interest to be expressed

Implements org.ccnx.ccn.CCNInterestListener.

boolean org.ccnx.ccn.io.CCNAbstractInputStream.hasNextSegment (  )  throws IOException [protected]

Checks whether we might have a next segment.

Returns:
Returns false if this content is marked as GONE (see ContentType), or if we have retrieved the segment marked as the last one, or, in a very rare case, if we're reading content that does not have segment markers.
boolean org.ccnx.ccn.io.CCNAbstractInputStream.isFirstSegment ( ContentName  desiredName,
ContentObject  segment 
) [protected]

Method to determine whether a retrieved block is the first segment of this stream (as specified by startingSegmentNumber, (see CCNAbstractInputStream(ContentName, Long, PublisherPublicKeyDigest, ContentKeys, CCNHandle)).

Overridden by subclasses to implement narrower constraints on names. Once first segment is retrieved, further segments can be identified just by segment-naming conventions (see SegmentationProfile).

Parameters:
desiredName The expected name prefix for the stream. For CCNAbstractInputStream, assume that desiredName contains the name up to but not including segmentation information.
segment The potential first segment.
Returns:
True if it is the first segment, false otherwise.

Reimplemented in org.ccnx.ccn.io.CCNVersionedInputStream.

boolean org.ccnx.ccn.io.CCNAbstractInputStream.isGone (  )  throws NoMatchingContentFoundException, IOException

Checks to see whether this content has been marked as GONE (deleted).

Will retrieve the first segment if we do not already have it in order to make this determination.

Returns:
true if stream is GONE.
Exceptions:
NoMatchingContentFound exception if no first segment found
IOException if there is other difficulty retrieving the first segment.
long org.ccnx.ccn.io.CCNAbstractInputStream.length (  )  throws IOException
Returns:
Total length of the stream, if known, otherwise -1.
Exceptions:
IOException 

Reimplemented in org.ccnx.ccn.io.CCNFileInputStream.

long org.ccnx.ccn.io.CCNAbstractInputStream.nextSegmentNumber (  ) 

Returns the segment number for the next segment.

Default segmentation generates sequentially-numbered stream segments but this method may be overridden in subclasses to perform re-assembly on streams that have been segmented differently.

Returns:
The index of the next segment of stream data.
PublisherPublicKeyDigest org.ccnx.ccn.io.CCNAbstractInputStream.publisher (  ) 

Callers may need to access information about this stream's publisher.

We eventually should (TODO) ensure that all the segments we're reading match in publisher information, and cache the verified publisher info. (In particular once we're doing trust calculations, to ensure we do them only once per stream.) But we do verify each segment, so start by pulling what's in the current segment.

Returns:
the publisher of the data in the stream (either as requested, or once we have data, as observed).
KeyLocator org.ccnx.ccn.io.CCNAbstractInputStream.publisherKeyLocator (  )  throws IOException
Returns:
the key locator for this stream's publisher.
Exceptions:
IOException if unable to obtain content (NoMatchingContentFoundException)
abstract int org.ccnx.ccn.io.CCNAbstractInputStream.readInternal ( byte[]  buf,
int  offset,
int  len 
) throws IOException [protected, pure virtual]

Actual mechanism used to trigger segment retrieval and perform content reads.

Subclasses define different schemes for retrieving content across segments.

Parameters:
buf As in read(byte[], int, int).
offset As in read(byte[], int, int).
len As in read(byte[], int, int).
Returns:
As in read(byte[], int, int).
Exceptions:
IOException if a segment cannot be retrieved, or there is an error in lower-level segment retrieval mechanisms. Uses subclasses of IOException to help provide more information. In particular, throws NoMatchingContentFoundException when no content found within the timeout given.

Implemented in org.ccnx.ccn.io.CCNBlockInputStream, and org.ccnx.ccn.io.CCNInputStream.

void org.ccnx.ccn.io.CCNAbstractInputStream.rewindSegment (  )  throws IOException [protected]

Rewinds read buffers for current segment to beginning of the segment.

Exceptions:
IOException 
void org.ccnx.ccn.io.CCNAbstractInputStream.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 in org.ccnx.ccn.io.CCNFileInputStream.

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

Reimplemented in org.ccnx.ccn.io.CCNFileInputStream.

long org.ccnx.ccn.io.CCNAbstractInputStream.segmentNumber (  ) 
Returns:
Returns the segment number of the current segment if we have one, otherwise the expected startingSegmentNumber.
void org.ccnx.ccn.io.CCNAbstractInputStream.setCurrentSegment ( ContentObject  newSegment  )  throws IOException [protected]

Set up current segment for reading, including preparation for decryption if necessary.

Called after getSegment/getFirstSegment/getNextSegment, which take care of verifying the segment for us. Assumes newSegment has been verified.

Exceptions:
IOException If decryption keys set up incorrectly
void org.ccnx.ccn.io.CCNAbstractInputStream.setFirstSegment ( ContentObject  newSegment  )  throws IOException [protected]

Called to set the first segment when opening a stream.

This does initialization and setup particular to the first segment of a stream. Subclasses should not override unless they really know what they are doing. Calls setCurrentSegment(ContentObject) for the first segment. If the content is encrypted, and keys are not provided for this stream, they are looked up according to the namespace. Note that this assumes that all segments of a given piece of content are either encrypted or not.

Parameters:
newSegment Must not be null
Exceptions:
IOException If newSegment is null or decryption keys set up incorrectly
void org.ccnx.ccn.io.CCNAbstractInputStream.setFlags ( EnumSet< FlagTypes >  flags  ) 

Set flags on this stream.

Replaces existing flags.

void org.ccnx.ccn.io.CCNAbstractInputStream.setTimeout ( int  timeout  ) 

Set the timeout that will be used for all content retrievals on this stream.

Default is 5 seconds.

Parameters:
timeout Milliseconds
long org.ccnx.ccn.io.CCNAbstractInputStream.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 in org.ccnx.ccn.io.CCNFileInputStream.


Member Data Documentation

The Link we dereferenced to get here, if any.

This may contain a link dereferenced to get to it, and so on.

Internal stream used for buffering reads.

May include filters.

The segment number to start with.

If not specified, is SegmentationProfile.baseSegment().

If this content uses Merkle Hash Trees or other bulk signatures to amortize signature cost, we can amortize verification cost as well by caching verification data as follows: store the currently-verified root signature, so we don't have to re-verify it; and the verified root hash.

For each piece of incoming content, see if it aggregates to the same root, if so don't reverify signature. If not, assume it's part of a new tree and change the root.


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