org.ccnx.ccn.profiles.SegmentationProfile Class Reference

We speak in terms of segments, not fragments, as this profile also encompasses packet-oriented data with sequenced segments rather than block data divided into fragments. More...

List of all members.

Public Types

enum  SegmentNumberType { SEGMENT_FIXED_INCREMENT, SEGMENT_BYTE_COUNT }
 

What does its fragment number mean?


Static Public Member Functions

static final long baseSegment ()
 Control whether fragments start at 0 or 1.
static boolean isUnsegmented (ContentName name)
static boolean isNotSegmentMarker (byte[] potentialSegmentID)
static boolean isSegmentMarker (byte[] potentialSegmentID)
static boolean isSegment (ContentName name)
static ContentName segmentRoot (ContentName name)
static ContentName segmentName (ContentName name, long index)
static byte[] getSegmentNumberNameComponent (long segmentNumber)
static long getSegmentNumber (byte[] segmentNumberNameComponent)
static long getSegmentNumber (ContentName name)
 Extract the segment information from this name.
static boolean isFirstSegment (ContentName name)
 Just confirms that last name component is a segment, and that its segment number is baseSegment() (0).
static ContentObject getSegment (ContentName desiredContent, Long desiredSegmentNumber, PublisherPublicKeyDigest publisher, long timeout, ContentVerifier verifier, CCNHandle handle) throws IOException
 Retrieves a specific segment, following the above naming conventions.
static Interest segmentInterest (ContentName name, Long segmentNumber, PublisherPublicKeyDigest publisher)
 Creates an Interest for a specified segment number.
static Interest anySegmentInterest (ContentName prefix, PublisherPublicKeyDigest publisher)
 Creates an Interest that allows for only a segment number and an ephemeral digest below the given prefix.
static Interest firstSegmentInterest (ContentName name, PublisherPublicKeyDigest publisher)
 Creates an Interest for the first segment.
static Interest nextSegmentInterest (ContentName name, PublisherPublicKeyDigest publisher)
static Interest lastSegmentInterest (ContentName name, Long segmentNumber, PublisherPublicKeyDigest publisher)
 Creates an Interest to find the right-most child from the given segment number or the base segment if one is not supplied.
static Interest lastSegmentInterest (ContentName name, PublisherPublicKeyDigest publisher)
 Creates an Interest to find the right-most child from the given segment number or the base segment if one is not supplied.
static ContentObject getLastSegment (ContentName name, PublisherPublicKeyDigest publisher, long timeout, ContentVerifier verifier, CCNHandle handle) throws IOException
 This method returns the last segment for the name provided.
static boolean isLastSegment (ContentObject co)
static Exclude acceptSegments (byte[] startingSegmentComponent)
 Builds an Exclude filter that excludes components that are not segments in the next component.
static ContentObject getNextSegment (ContentName name, PublisherPublicKeyDigest publisher, long timeout, ContentVerifier verifier, CCNHandle handle) throws IOException
 Function to get the next segment after segment in the supplied name (or the first segment if no segment is given).

Static Public Attributes

static final long BASE_SEGMENT = 0
 Is it fragmented, and what is its fragment number?
static final byte SEGMENT_MARKER = (byte)0x00
static final byte NO_SEGMENT_POSTFIX = 0x00
static final byte[] FIRST_SEGMENT_MARKER = new byte[]{SEGMENT_MARKER}
static final byte[] NO_SEGMENT_MARKER = new byte[]{SEGMENT_MARKER, NO_SEGMENT_POSTFIX}
static final int DEFAULT_BLOCKSIZE = 4096
 Default blocksize.
static final int DEFAULT_INCREMENT = 1
static final int DEFAULT_SCALE = 1
static final int MAX_LAST_SEGMENT_LOOP_ATTEMPTS = 10
 The library will attempt to get the last segment, without knowing exactly what segment number this will be.

Detailed Description

We speak in terms of segments, not fragments, as this profile also encompasses packet-oriented data with sequenced segments rather than block data divided into fragments.

Sequence/segment numbers occupy the final component of the CCN name (again, not counting the digest component). For consecutive numbering, the first byte of the sequence component is 0x00. The remaining bytes hold the sequence number in big-endian unsigned binary, using the minimum number of bytes. Thus sequence number 0 is encoded in just one byte, 00, and sequence number 1 is 0001. Note that this encoding is not quite dense - 0000 is unused, as are other components that start with these two bytes. For non-consecutive numbering (e.g, using byte offsets) the value 0xFB may be used as a marker.


Member Function Documentation

static Exclude org.ccnx.ccn.profiles.SegmentationProfile.acceptSegments ( byte[]  startingSegmentComponent  )  [static]

Builds an Exclude filter that excludes components that are not segments in the next component.

Parameters:
startingSegmentComponent The latest segment component we know about. Can be null or the SegmentationProfile.baseSegment() component to indicate that we want to start from 0 (we don't have a known segment to start from). This exclude filter will find segments *after* the segment represented in startingSegmentComponent.
Returns:
An exclude filter.

TODO needs to be fully implemented

static Interest org.ccnx.ccn.profiles.SegmentationProfile.anySegmentInterest ( ContentName  prefix,
PublisherPublicKeyDigest  publisher 
) [static]

Creates an Interest that allows for only a segment number and an ephemeral digest below the given prefix.

Parameters:
prefix 
publisher 
Returns:
static final long org.ccnx.ccn.profiles.SegmentationProfile.baseSegment (  )  [static]

Control whether fragments start at 0 or 1.

Returns:
static Interest org.ccnx.ccn.profiles.SegmentationProfile.firstSegmentInterest ( ContentName  name,
PublisherPublicKeyDigest  publisher 
) [static]

Creates an Interest for the first segment.

Parameters:
name ContentName for the desired ContentObject
publisher can be null
Returns:
interest
static ContentObject org.ccnx.ccn.profiles.SegmentationProfile.getLastSegment ( ContentName  name,
PublisherPublicKeyDigest  publisher,
long  timeout,
ContentVerifier  verifier,
CCNHandle  handle 
) throws IOException [static]

This method returns the last segment for the name provided.

If there are no segments for the supplied name, the method will return null. It is possible for producers to continuously make new segments. In this case, the function returns last content object it finds (and verifies) after some number of attempts (the default value is 10 for now). The function can be called with a starting segment, the method will attempt to find the last segment after the provided segment number. This method assumes either the last component of the supplied name is a segment or the next component of the name will be a segment. It does not attempt to resolve the remainder of the prefix (for example, it will not attempt to distinguish which version to use).

If the method is called with a segment in the name and as an additional parameter, the method will use the higher number to locate the last segment. Again, if no segment is found, the method will return null.

Calling functions should explicitly check if the returned segment is the best-effort at the last segment, or the marked last segment (if it matters to the caller).

Parameters:
name 
publisher 
timeout 
verifier 
handle 
Returns:
Exceptions:
IOException 
static ContentObject org.ccnx.ccn.profiles.SegmentationProfile.getSegment ( ContentName  desiredContent,
Long  desiredSegmentNumber,
PublisherPublicKeyDigest  publisher,
long  timeout,
ContentVerifier  verifier,
CCNHandle  handle 
) throws IOException [static]

Retrieves a specific segment, following the above naming conventions.

If necessary (not currently), will issue repeated requests until it gets a segment that matches requirements and verifies, or it times out. If it can't find anything, should return null. TODO Eventually cope if verification fails (exclude, warn and retry).

Parameters:
desiredContent 
segmentNumber If null, gets baseSegment().
timeout 
verifier Cannot be null.
handle 
Returns:
the segment it got, or null if nothing matching could be found in the allotted time
Exceptions:
IOException only on error
static long org.ccnx.ccn.profiles.SegmentationProfile.getSegmentNumber ( ContentName  name  )  [static]

Extract the segment information from this name.

Try to return any valid number encoded in the last name component, be it either a raw big-endian encoding of a number, or more likely, a properly-formatted segment number with segment marker.

Exceptions:
NumberFormatException if neither number type found in last name component
static boolean org.ccnx.ccn.profiles.SegmentationProfile.isFirstSegment ( ContentName  name  )  [static]

Just confirms that last name component is a segment, and that its segment number is baseSegment() (0).

Parameters:
name 
Returns:
static Interest org.ccnx.ccn.profiles.SegmentationProfile.lastSegmentInterest ( ContentName  name,
PublisherPublicKeyDigest  publisher 
) [static]

Creates an Interest to find the right-most child from the given segment number or the base segment if one is not supplied.

This Interest will attempt to find the last segment for the given content name. Due to caching, this does not guarantee the interest will find the last segment, higher layer code must verify that the ContentObject returned for this interest is the last one.

Parameters:
name ContentName for the prefix of the Interest
publisher can be null
Returns:
interest
static Interest org.ccnx.ccn.profiles.SegmentationProfile.lastSegmentInterest ( ContentName  name,
Long  segmentNumber,
PublisherPublicKeyDigest  publisher 
) [static]

Creates an Interest to find the right-most child from the given segment number or the base segment if one is not supplied.

This attempts to find the last segment for the given content name. Due to caching, this does not guarantee the interest will find the last segment, higher layer code must verify that the ContentObject returned for this interest is the last one.

TODO: depends on acceptSegments being fully implemented. right now mainly depends on the number of component restriction.

Parameters:
name ContentName for the prefix of the Interest
segmentNumber create an interest for the last segment number after this number
publisher can be null
Returns:
interest
static Interest org.ccnx.ccn.profiles.SegmentationProfile.segmentInterest ( ContentName  name,
Long  segmentNumber,
PublisherPublicKeyDigest  publisher 
) [static]

Creates an Interest for a specified segment number.

If the supplied name already ends with a segment number, the interest will have the supplied segment in the name instead.

Parameters:
name ContentName for the desired ContentObject
segmentNumber segment number to append to the name, if null, uses the baseSegment number
publisher can be null
Returns:
interest

Member Data Documentation

Default blocksize.

This must be a multiple of the block size of standard encryption algorithms (generally, 128 bits = 16 bytes; conservatively 256 bits = 32 bytes, really conservatively, support 192 bits = 24 bytes; so 32 bytes with unused bytes in the 192-bit case (otherwise we'd have to use the LCM, 96 bytes, which is really inefficient).

The library will attempt to get the last segment, without knowing exactly what segment number this will be.

Additionally, it is possible for a streaming producer to continuously push a new segment and never have an end. The MAX_LAST_SEGMENT_LOOP_ATTEMPT variable avoids blocking forever in this case. The getLastSegment function will attempt x times (default is 10), before handing back the current content object, which is a best effort attempt at the last segment.


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