org.ccnx.ccn.profiles.VersioningProfile Class Reference

Versions, when present, usually occupy the penultimate component of the CCN name, not counting the digest component. More...

Inheritance diagram for org.ccnx.ccn.profiles.VersioningProfile:

org.ccnx.ccn.profiles.CCNProfile

List of all members.

Static Public Member Functions

static ContentName addVersion (ContentName name, long version)
 Add a version field to a ContentName.
static ContentName addVersion (ContentName name, CCNTime version)
 Converts a timestamp into a fixed point representation, with 12 bits in the fractional component, and adds this to the ContentName as a version field.
static ContentName addVersion (ContentName name)
 Add a version field based on the current time, accurate to 1/4096 second.
static byte[] timeToVersionComponent (CCNTime version)
static String printAsVersionComponent (CCNTime version)
static ContentName updateVersion (ContentName name, long version)
 Adds a version to a ContentName; if there is a terminal version there already, first removes it.
static ContentName updateVersion (ContentName name, CCNTime version)
 Adds a version to a ContentName; if there is a terminal version there already, first removes it.
static ContentName updateVersion (ContentName name)
 Add updates the version field based on the current time, accurate to 1/4096 second.
static int findLastVersionComponent (ContentName name)
 Finds the last component that looks like a version in name.
static boolean containsVersion (ContentName name)
 Checks to see if this name has a validly formatted version field anywhere in it.
static boolean hasTerminalVersion (ContentName name)
 Checks to see if this name has a validly formatted version field either in final component or in next to last component with final component being a segment marker.
static boolean isVersionComponent (byte[] nameComponent)
 Check a name component to see if it is a valid version field.
static boolean isBaseVersionComponent (byte[] nameComponent)
static Tuple< ContentName, byte[]> cutTerminalVersion (ContentName name)
 Remove a terminal version marker (one that is either the last component of name, or the next to last component of name followed by a segment marker) if one exists, otherwise return name as it was passed in.
static ContentName cutLastVersion (ContentName name)
 Take a name which may have one or more version components in it, and strips the last one and all following components.
static long getLastVersionAsLong (ContentName name) throws VersionMissingException
 Function to get the version field as a long.
static byte[] getLastVersionComponent (ContentName name) throws VersionMissingException
static long getVersionComponentAsLong (final byte[] versionComponent)
static CCNTime getVersionComponentAsTimestamp (byte[] versionComponent)
static CCNTime getLastVersionAsTimestamp (ContentName name) throws VersionMissingException
 Extract the version from this name as a Timestamp.
static CCNTime getLastVersionAsTimestampIfVersioned (ContentName name)
 Returns null if no version, otherwise returns the last version in the name.
static CCNTime getTerminalVersionAsTimestampIfVersioned (ContentName name)
static CCNTime versionLongToTimestamp (long version)
static final int baseVersion ()
 Control whether versions start at 0 or 1.
static int compareVersions (CCNTime left, ContentName right)
 Compares terminal version (versions at the end of, or followed by only a segment marker) of a name to a given timestamp.
static int compareVersionComponents (byte[] left, byte[] right) throws VersionMissingException
static boolean isVersionOf (ContentName version, ContentName parent)
 See if version is a version of parent (not commutative).
static boolean isLaterVersionOf (ContentName laterVersion, ContentName earlierVersion) throws VersionMissingException
 This compares two names, with terminal versions, and determines whether one is later than the other.
static boolean startsWithLaterVersionOf (ContentName newName, ContentName previousVersion)
 Finds out if you have a versioned name, and a ContentObject that might have a versioned name which is a later version of the given name, even if that CO name might not refer to a segment of the original name.
static int compareTerminalVersions (ContentName laterVersion, ContentName earlierVersion) throws VersionMissingException
static Exclude acceptVersions (byte[] startingVersionComponent)
 Builds an Exclude filter that excludes components before or @ start, and components after the last valid version.
static Interest firstBlockLatestVersionInterest (ContentName startingVersion, PublisherPublicKeyDigest publisher)
 Active methods.
static Interest latestVersionInterest (ContentName startingVersion, Integer additionalNameComponents, PublisherPublicKeyDigest publisher)
 Generate an interest that will find a descendant of the latest version of startingVersion, after any existing version component.
static ContentObject getLatestVersion (ContentName startingVersion, PublisherPublicKeyDigest publisher, long timeout, ContentVerifier verifier, CCNHandle handle) throws IOException
 Function to (best effort) get the latest version.
static ContentObject getFirstBlockOfLatestVersion (ContentName startingVersion, Long startingSegmentNumber, PublisherPublicKeyDigest publisher, long timeout, ContentVerifier verifier, CCNHandle handle) throws IOException
 Find a particular segment of the latest version of a name
  • if no version given, gets the desired segment of the latest version
  • if a starting version given, gets the latest version available *after* that version or times out Will ensure that what it returns is a segment of a version of that object.

static ContentObject getAnyLaterVersion (ContentName startingVersion, PublisherPublicKeyDigest publisher, long timeout, ContentVerifier verifier, CCNHandle handle) throws IOException
 Single-attempt function to get the first version found; and if there are multiple versions at the network point where that version is found, it will retrieve the latest of them.
static ContentObject getFirstBlockOfAnyLaterVersion (ContentName startingVersion, Long startingSegmentNumber, PublisherPublicKeyDigest publisher, long timeout, ContentVerifier verifier, CCNHandle handle) throws IOException
 Find a particular segment of the closest version available of this object later than the version given.
static boolean isVersionedFirstSegment (ContentName desiredName, ContentObject potentialFirstSegment, Long startingSegmentNumber)
 Version of isFirstSegment that expects names to be versioned, and allows that desiredName won't know what version it wants but will want some version.
static byte[] versionComponentFromStripped (byte[] bs)
static byte[] stripVersionMarker (byte[] version) throws VersionMissingException

Static Public Attributes

static final byte VERSION_MARKER = (byte)0xFD
static final byte FF = (byte) 0xFF
static final byte O1 = (byte) 0x01
static final byte OO = (byte) 0x00
static final byte[] FIRST_VERSION_MARKER = new byte []{VERSION_MARKER}
static final byte[] LAST_VERSION_MARKER = new byte [] {VERSION_MARKER+1, OO, OO, OO, OO, OO, OO }
static final byte[] MIN_VERSION_MARKER = new byte [] {VERSION_MARKER, O1, OO, OO, OO, OO, OO}
static final byte[] MAX_VERSION_MARKER = new byte [] {VERSION_MARKER, FF, FF, FF, FF, FF, FF }
static final byte[] BOTTOM_EXCLUDE_VERSION_MARKER = MIN_VERSION_MARKER
static final byte[] TOP_EXCLUDE_VERSION_MARKER = LAST_VERSION_MARKER

Static Protected Member Functions

static ContentObject getLocalLatestVersion (ContentName startingVersion, PublisherPublicKeyDigest publisher, long timeout, ContentVerifier verifier, CCNHandle handle, Long startingSegmentNumber, boolean findASegment) throws IOException


Detailed Description

Versions, when present, usually occupy the penultimate component of the CCN name, not counting the digest component.

A name may actually incorporate multiple versions, where the rightmost version is the version of "this" object, if it has one, and previous (parent) versions are the versions of the objects of which this object is a part. The most common location of a version, if present, is in the next to last component of the name, where the last component is a segment number (which is generally always present; versions themselves are optional). More complicated segmentation profiles occur, where a versioned object has components that are structured and named in ways other than segments -- and may themselves have individual versions (e.g. if the components of such a composite object are written as CCNNetworkObjects and automatically pick up an (unnecessary) version in their own right). Versioning operations therefore take context from their caller about where to expect to find a version, and attempt to ignore other versions in the name.

Versions may be chosen based on time. The first byte of the version component is 0xFD. The remaining bytes are a big-endian binary number. If based on time they are expressed in units of 2**(-12) seconds since the start of Unix time, using the minimum number of bytes. The time portion will thus take 48 bits until quite a few centuries from now (Sun, 20 Aug 4147 07:32:16 GMT). With 12 bits of precision, it allows for sub-millisecond resolution. The client generating the version stamp should try to avoid using a stamp earlier than (or the same as) any version of the file, to the extent that it knows about it. It should also avoid generating stamps that are unreasonably far in the future.

Get latest version is going to exclude [B, 0xFD00FFFFFFFFFF, 0xFE000000000000,B], so you need to be sure to use version numbers in those bounds.


Member Function Documentation

static ContentName org.ccnx.ccn.profiles.VersioningProfile.addVersion ( ContentName  name,
long  version 
) [static]

Add a version field to a ContentName.

Version:
should be a CCNTime toBinaryTimeAsLong() not getTime()
Returns:
ContentName with a version appended. Does not affect previous versions.

static ContentName org.ccnx.ccn.profiles.VersioningProfile.addVersion ( ContentName  name,
CCNTime  version 
) [static]

Converts a timestamp into a fixed point representation, with 12 bits in the fractional component, and adds this to the ContentName as a version field.

The timestamp is rounded to the nearest value in the fixed point representation.

This allows versions to be recorded as a timestamp with a 1/4096 second accuracy.

Get latest version is going to exclude [B, 0xFD00FFFFFFFFFF, 0xFE000000000000,B], so you need to be sure to use version numbers in those bounds.

See also:
addVersion(ContentName, long)

static ContentName org.ccnx.ccn.profiles.VersioningProfile.addVersion ( ContentName  name  )  [static]

Add a version field based on the current time, accurate to 1/4096 second.

Get latest version is going to exclude [B, 0xFD00FFFFFFFFFF, 0xFE000000000000,B], so you need to be sure to use version numbers in those bounds.

See also:
addVersion(ContentName, CCNTime)

static ContentName org.ccnx.ccn.profiles.VersioningProfile.updateVersion ( ContentName  name  )  [static]

Add updates the version field based on the current time, accurate to 1/4096 second.

See also:
updateVersion(ContentName, Timestamp)

static int org.ccnx.ccn.profiles.VersioningProfile.findLastVersionComponent ( ContentName  name  )  [static]

Finds the last component that looks like a version in name.

Parameters:
name 
Returns:
the index of the last version component in the name, or -1 if there is no version component in the name

static Tuple<ContentName, byte[]> org.ccnx.ccn.profiles.VersioningProfile.cutTerminalVersion ( ContentName  name  )  [static]

Remove a terminal version marker (one that is either the last component of name, or the next to last component of name followed by a segment marker) if one exists, otherwise return name as it was passed in.

Parameters:
name 
Returns:

static ContentName org.ccnx.ccn.profiles.VersioningProfile.cutLastVersion ( ContentName  name  )  [static]

Take a name which may have one or more version components in it, and strips the last one and all following components.

If no version components present, returns the name as handed in.

static long org.ccnx.ccn.profiles.VersioningProfile.getLastVersionAsLong ( ContentName  name  )  throws VersionMissingException [static]

Function to get the version field as a long.

Starts from the end and checks each name component for the version marker.

Parameters:
name 
Returns:
long
Exceptions:
VersionMissingException 

static CCNTime org.ccnx.ccn.profiles.VersioningProfile.getLastVersionAsTimestamp ( ContentName  name  )  throws VersionMissingException [static]

Extract the version from this name as a Timestamp.

Exceptions:
VersionMissingException 

static CCNTime org.ccnx.ccn.profiles.VersioningProfile.getLastVersionAsTimestampIfVersioned ( ContentName  name  )  [static]

Returns null if no version, otherwise returns the last version in the name.

Parameters:
name 
Returns:

static final int org.ccnx.ccn.profiles.VersioningProfile.baseVersion (  )  [static]

Control whether versions start at 0 or 1.

Returns:

static int org.ccnx.ccn.profiles.VersioningProfile.compareVersions ( CCNTime  left,
ContentName  right 
) [static]

Compares terminal version (versions at the end of, or followed by only a segment marker) of a name to a given timestamp.

Parameters:
left 
right 
Returns:

static boolean org.ccnx.ccn.profiles.VersioningProfile.isVersionOf ( ContentName  version,
ContentName  parent 
) [static]

See if version is a version of parent (not commutative).

Returns:

static boolean org.ccnx.ccn.profiles.VersioningProfile.isLaterVersionOf ( ContentName  laterVersion,
ContentName  earlierVersion 
) throws VersionMissingException [static]

This compares two names, with terminal versions, and determines whether one is later than the other.

Parameters:
laterVersion 
earlierVersion 
Returns:
Exceptions:
VersionMissingException 

static boolean org.ccnx.ccn.profiles.VersioningProfile.startsWithLaterVersionOf ( ContentName  newName,
ContentName  previousVersion 
) [static]

Finds out if you have a versioned name, and a ContentObject that might have a versioned name which is a later version of the given name, even if that CO name might not refer to a segment of the original name.

For example, given a name /parc/foo.txt/<version1> or /parc/foo.txt/<version1>/<segment> and /parc/foo.txt/<version2>/<stuff>, return true, whether <stuff> is a segment marker, a whole bunch of repo write information, or whatever.

Parameters:
newName Will check to see if this name begins with something which is a later version of previousVersion.
previousVersion The name to compare to, must have a terminal version or be unversioned.
Returns:

static Exclude org.ccnx.ccn.profiles.VersioningProfile.acceptVersions ( byte[]  startingVersionComponent  )  [static]

Builds an Exclude filter that excludes components before or @ start, and components after the last valid version.

Parameters:
startingVersionComponent The latest version component we know about. Can be null or VersioningProfile.isBaseVersionComponent() == true to indicate that we want to start from 0 (we don't have a known version we're trying to update). This exclude filter will find versions *after* the version represented in startingVersionComponent.
Returns:
An exclude filter.

static Interest org.ccnx.ccn.profiles.VersioningProfile.firstBlockLatestVersionInterest ( ContentName  startingVersion,
PublisherPublicKeyDigest  publisher 
) [static]

Active methods.

Want to provide profile-specific methods that:

  • find the latest version without regard to what is below it
    • if no version given, gets the latest version
    • if a starting version given, gets the latest version available *after* that version; will time out if no such newer version exists Returns a content object, which may or may not be a segment of the latest version, but the latest version information is available from its name.

  • find the first segment of the latest version of a name
    • if no version given, gets the first segment of the latest version
    • if a starting version given, gets the latest version available *after* that version or times out Will ensure that what it returns is a segment of a version of that object.

  • generate an interest designed to find the first segment of the latest version of a name, in the above form; caller is responsible for checking and re-issuing Generate an interest that will find the leftmost child of the latest version. It will ensure that the next to last segment is a version, and the last segment (excluding digest) is the leftmost child available. But it can't guarantee that the latter is a segment. Because most data is segmented, length constraints will make it very likely, however.
    Parameters:
    startingVersion 
    Returns:

static Interest org.ccnx.ccn.profiles.VersioningProfile.latestVersionInterest ( ContentName  startingVersion,
Integer  additionalNameComponents,
PublisherPublicKeyDigest  publisher 
) [static]

Generate an interest that will find a descendant of the latest version of startingVersion, after any existing version component.

If additionalNameComponents is non-null, it will find a descendant with exactly that many name components after the version (including the digest). The latest version is the rightmost child of the desired prefix, however, this interest will find leftmost descendants of that rightmost child. With appropriate length limitations, can be used to find segments of the latest version (though that will work more effectively with appropriate segment numbering).

static ContentObject org.ccnx.ccn.profiles.VersioningProfile.getLatestVersion ( ContentName  startingVersion,
PublisherPublicKeyDigest  publisher,
long  timeout,
ContentVerifier  verifier,
CCNHandle  handle 
) throws IOException [static]

Function to (best effort) get the latest version.

There may be newer versions available if you ask again passing in the version found (i.e. each response will be the latest version a given responder knows about. Further queries will move past that responder to other responders, who may have newer information.)

Parameters:
name If the name ends in a version then this method explicitly looks for a newer version than that, and will time out if no such later version exists. If the name does not end in a version then this call just looks for the latest version.
publisher Currently unused, will limit query to a specific publisher.
timeout This is the time to wait until you get any response. If nothing is returned, this method will return null.
verifier Used to verify the returned content objects
handle CCNHandle used to get the latest version
Returns:
A ContentObject with the latest version, or null if the query timed out.

Returns a matching ContentObject, verified.

Exceptions:
IOException 

static ContentObject org.ccnx.ccn.profiles.VersioningProfile.getFirstBlockOfLatestVersion ( ContentName  startingVersion,
Long  startingSegmentNumber,
PublisherPublicKeyDigest  publisher,
long  timeout,
ContentVerifier  verifier,
CCNHandle  handle 
) throws IOException [static]

Find a particular segment of the latest version of a name

  • if no version given, gets the desired segment of the latest version
  • if a starting version given, gets the latest version available *after* that version or times out Will ensure that what it returns is a segment of a version of that object.

Also makes sure to return the latest version with a SegmentationProfile.baseSegment() marker. *

Parameters:
desiredName The name of the object we are looking for the first segment of. If (VersioningProfile.hasTerminalVersion(desiredName) == false), will get latest version it can find of desiredName. If desiredName has a terminal version, will try to find the first block of content whose version is *after* desiredName (i.e. getLatestVersion starting from desiredName).
startingSegmentNumber The desired block number, or SegmentationProfile.baseSegment() if null.
publisher,if one is specified.
timeout 
Returns:
The first block of a stream with a version later than desiredName, or null if timeout is reached. This block is verified.
Exceptions:
IOException 

static ContentObject org.ccnx.ccn.profiles.VersioningProfile.getAnyLaterVersion ( ContentName  startingVersion,
PublisherPublicKeyDigest  publisher,
long  timeout,
ContentVerifier  verifier,
CCNHandle  handle 
) throws IOException [static]

Single-attempt function to get the first version found; and if there are multiple versions at the network point where that version is found, it will retrieve the latest of them.

So if your ccnd cache has multiple versions, it will return the latest of those, but won't move past them to get a later one in the repository or one hop away. This should be used if you believe there is only a single version of a piece of content available, or if you care more about fast answers than ensuring you have the latest version available. if you ask again passing in the version found, you will find a version later than that if one is available (i.e. each response will be the latest version a given responder knows about. Further queries will move past that responder to other responders, who may have newer information.)

Parameters:
name If the name ends in a version then this method explicitly looks for a newer version than that, and will time out if no such later version exists. If the name does not end in a version then this call just looks for the latest version.
publisher Currently unused, will limit query to a specific publisher.
timeout This is the time to wait until you get any response. If nothing is returned, this method will return null.
verifier Used to verify the returned content objects
handle CCNHandle used to get the latest version
Returns:
A ContentObject with the latest version, or null if the query timed out.

Returns a matching ContentObject, verified.

Exceptions:
IOException 

static ContentObject org.ccnx.ccn.profiles.VersioningProfile.getFirstBlockOfAnyLaterVersion ( ContentName  startingVersion,
Long  startingSegmentNumber,
PublisherPublicKeyDigest  publisher,
long  timeout,
ContentVerifier  verifier,
CCNHandle  handle 
) throws IOException [static]

Find a particular segment of the closest version available of this object later than the version given.

If there are multiple versions available at that point, will get the latest among them. See getAnyLaterVersion.

  • if no version given, gets the desired segment of the latest version
  • if a starting version given, gets the latest version available *after* that version or times out Will ensure that what it returns is a segment of a version of that object. Also makes sure to return the latest version with a SegmentationProfile.baseSegment() marker. *
    Parameters:
    desiredName The name of the object we are looking for the first segment of. If (VersioningProfile.hasTerminalVersion(desiredName) == false), will get latest version it can find of desiredName. If desiredName has a terminal version, will try to find the first block of content whose version is *after* desiredName (i.e. getLatestVersion starting from desiredName).
    startingSegmentNumber The desired block number, or SegmentationProfile.baseSegment() if null.
    publisher,if one is specified.
    timeout 
    Returns:
    The first block of a stream with a version later than desiredName, or null if timeout is reached. This block is verified.
    Exceptions:
    IOException 


The documentation for this class was generated from the following file:

Generated on Thu Feb 16 00:45:03 2012 for Content-Centric Networking in Java by  doxygen 1.5.6