org.ccnx.ccn.io.content.CCNNetworkObject< E > Class Reference

Extends a NetworkObject to add specifics for using a CCN-based backing store. More...

List of all members.

Public Member Functions

 CCNNetworkObject (Class< E > type, boolean contentIsMutable, ContentName name, E data, SaveType saveType, CCNHandle handle) throws IOException
 Basic write constructor.
 CCNNetworkObject (Class< E > type, boolean contentIsMutable, ContentName name, E data, SaveType saveType, PublisherPublicKeyDigest publisher, KeyLocator locator, CCNHandle handle) throws IOException
 Basic write constructor.
 CCNNetworkObject (Class< E > type, boolean contentIsMutable, ContentName name, CCNHandle handle) throws ContentDecodingException, IOException
 Read constructor.
 CCNNetworkObject (Class< E > type, boolean contentIsMutable, ContentName name, PublisherPublicKeyDigest publisher, CCNHandle handle) throws ContentDecodingException, IOException
 Read constructor.
 CCNNetworkObject (Class< E > type, boolean contentIsMutable, ContentObject firstSegment, CCNHandle handle) throws ContentDecodingException, IOException
 Read constructor if you already have a segment of the object.
CCNFlowControl getFlowControl ()
 Get the flow controller associated with this object.
long getTimeout ()
 Get timeout associated with this object.
synchronized void setupSave (SaveType saveType) throws IOException
 Start listening to interests on our base name, if we aren't already.
synchronized void setupSave () throws IOException
synchronized void close ()
 Close flow controller, remove listeners.
SaveType saveType ()
void setFreshnessSeconds (Integer freshnessSeconds)
 If you want to set the lifetime of objects saved with this instance.
void setVerifier (ContentVerifier verifier)
 Allow verifier to be specified.
boolean update (long timeout) throws ContentDecodingException, IOException
 Attempts to find a version after the latest one we have, or times out.
boolean updateAny (long timeout) throws ContentDecodingException, IOException
 The regular update does a call to do multi-hop get latest version -- i.e.
boolean updateAny () throws ContentDecodingException, IOException
boolean update () throws ContentDecodingException, IOException
 Calls update(long) with the default timeout SystemConfiguration.getDefaultTimeout().
boolean update (ContentName name, PublisherPublicKeyDigest publisher) throws ContentDecodingException, IOException
 Load data into object.
boolean update (ContentObject object) throws ContentDecodingException, IOException
 Load a stream starting with a specific object.
synchronized boolean update (CCNInputStream inputStream) throws ContentDecodingException, IOException
 Updates the object from a CCNInputStream or one of its subclasses.
void updateInBackground () throws IOException
 Update this object in the background -- asynchronously.
void updateInBackground (boolean continuousUpdates) throws IOException
 Update this object in the background -- asynchronously.
void updateInBackground (ContentName latestVersionKnown, boolean continuousUpdates) throws IOException
void updateInBackground (boolean continuousUpdates, UpdateListener listener) throws IOException
synchronized void updateInBackground (ContentName latestVersionKnown, boolean continuousUpdates, UpdateListener listener) throws IOException
 Update this object in the background -- asynchronously.
synchronized void cancelInterest ()
 Cancel an outstanding updateInBackground().
synchronized void addListener (UpdateListener listener)
synchronized boolean hasListener (UpdateListener listener)
 Does this object already have this listener.
void removeListener (UpdateListener listener)
void clearListeners ()
boolean save () throws ContentEncodingException, IOException
 Save to existing name, if content is dirty.
boolean save (Interest outstandingInterest) throws ContentEncodingException, IOException
 Method for CCNFilterListeners to save an object in response to an Interest callback.
boolean save (CCNTime version) throws ContentEncodingException, IOException
 Save to existing name, if content is dirty.
boolean save (CCNTime version, Interest outstandingInterest) throws ContentEncodingException, IOException
 Save to existing name, if content is dirty.
boolean save (E data) throws ContentEncodingException, IOException
 Convenience method to the data and save it in a single operation.
synchronized boolean save (CCNTime version, E data) throws ContentEncodingException, IOException
 Convenience method to the data and save it as a particular version in a single operation.
synchronized boolean saveToRepository (CCNTime version) throws ContentEncodingException, IOException
 Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.
boolean saveToRepository () throws ContentEncodingException, IOException
 Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.
boolean saveToRepository (E data) throws ContentEncodingException, IOException
 Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.
synchronized boolean saveToRepository (CCNTime version, E data) throws ContentEncodingException, IOException
 Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.
synchronized boolean saveAsGone () throws ContentEncodingException, IOException
 Save this object as GONE.
synchronized boolean saveAsGone (Interest outstandingInterest) throws ContentEncodingException, IOException
 For use by CCNFilterListeners, saves a GONE object and emits an inital block in response to an already-received Interest.
synchronized boolean saveToRepositoryAsGone () throws ContentEncodingException, IOException
 Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.
synchronized void disableFlowControl ()
 Turn off flow control for this object.
void waitForData ()
 Will return immediately if this object already has data, otherwise will wait indefinitely for the initial data to appear.
void waitForData (long timeout)
 Will wait for data to arrive.
boolean isGone ()
synchronized void setData (E newData)
 Set a new data value for this object.
synchronized CCNTime getVersion () throws IOException
synchronized VersionNumber getVersionNumber () throws IOException
synchronized ContentName getBaseName ()
CCNHandle getHandle ()
synchronized byte[] getVersionComponent () throws IOException
Long firstSegmentNumber ()
 Returns the first segment number for this object.
byte[] getFirstDigest ()
 Returns the digest of the first segment of this object which may be used to help identify object instance unambiguously.
ContentObject getFirstSegment ()
 Returns the first segment of this object.
synchronized LinkObject getDereferencedLink ()
 If we traversed a link to get this object, make it available.
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.
synchronized ContentName getVersionedName ()
 If the object has been saved or read from the network, returns the (cached) versioned name.
synchronized
PublisherPublicKeyDigest 
getContentPublisher () throws IOException
synchronized KeyLocator getPublisherKeyLocator () throws IOException
synchronized void setOurPublisherInformation (PublisherPublicKeyDigest publisherIdentity, KeyLocator keyLocator)
 Change the publisher information we use when we sign commits to this object.
synchronized Interest handleContent (ContentObject co, Interest interest)
 Callback called when we get new results for our query.
ContentType contentType ()
 Subclasses that need to write an object of a particular type can override.
int hashCode ()
boolean equals (Object obj)
String toString ()

Protected Member Functions

 CCNNetworkObject (Class< E > type, boolean contentIsMutable, ContentName name, E data, PublisherPublicKeyDigest publisher, KeyLocator locator, CCNFlowControl flowControl) throws IOException
 Specialized constructor, allowing subclasses to override default flow controller (and hence backing store) behavior.
 CCNNetworkObject (Class< E > type, boolean contentIsMutable, ContentName name, PublisherPublicKeyDigest publisher, CCNFlowControl flowControl) throws ContentDecodingException, IOException
 Read constructor.
 CCNNetworkObject (Class< E > type, boolean contentIsMutable, ContentObject firstSegment, CCNFlowControl flowControl) throws ContentDecodingException, IOException
 Read constructor if you already have a segment of the object.
 CCNNetworkObject (Class< E > type, CCNNetworkObject<?extends E > other)
 Copy constructor.
synchronized void createFlowController () throws IOException
 Maximize laziness of flow controller creation, to make it easiest for client code to decide how to store this object.
void finalize () throws Throwable
 Finalizer.
void setSaveType (SaveType saveType) throws IOException
 Used by subclasses to specify a mandatory save type in read constructors.
void setInputStreamProperties (CCNInputStream inputStream)
 Override point where subclasses can modify each input stream before it is read.
EnumSet< FlagTypes > getInputStreamFlags ()
 Override point where subclasses can specify set of flags on input stream at point it is read or where necessary created.
synchronized boolean saveInternal (CCNTime version, boolean gone, Interest outstandingInterest) throws ContentEncodingException, IOException
 Save content to specific version.
void newVersionAvailable (boolean wasSave)
 Used to signal waiters and listeners that a new version is available.
byte[] digestContent () throws IOException
 Encode and digest the object's content in order to detect changes made outside of the object's own interface (for example, if the data is accessed using data() and then modified).
synchronized E data () throws ContentNotReadyException, ContentGoneException, ErrorStateException
 Retrieve this object's data.

Protected Attributes

ContentName _baseName
 Unversioned "base" name.
byte[] _currentVersionComponent
 The most recent version we have read/written.
ContentName _currentVersionName
 Cached versioned name.
boolean _isGone = false
 Flag to indicate whether content has been explicitly marked as GONE in the latest version we know about.
ContentObject _firstSegment = null
 The first segment for the stored data.
LinkObject _dereferencedLink
 If the name we started with was actually a link, detect that, store the link, and dereference it to get the content.
PublisherPublicKeyDigest _currentPublisher
KeyLocator _currentPublisherKeyLocator
CCNHandle _handle
CCNFlowControl _flowControl
boolean _disableFlowControlRequest = false
PublisherPublicKeyDigest _publisher
KeyLocator _keyLocator
SaveType _saveType = null
Integer _freshnessSeconds = null
ContentKeys _keys
ContentVerifier _verifier

Static Protected Attributes

static final byte[] GONE_OUTPUT = "GONE".getBytes()

Package Attributes

Interest _currentInterest = null
 Controls ongoing update.
boolean _continuousUpdates = false
HashSet< UpdateListener_updateListeners = null

Detailed Description

Extends a NetworkObject to add specifics for using a CCN-based backing store.

Each time the object is saved creates a new CCN version. Readers can open a specific version or not specify a version, in which case the latest available version is read. Defaults allow for saving data to a repository or directly to the network.

Need to support four use models: dimension 1: synchronous - ask for and block, the latest version or a specific version dimension 2: asynchronous - ask for and get in the background, the latest version or a specific version When possible, keep track of the latest version known so that the latest version queries can attempt to do better than that. Start by using only in the background load case, as until something comes back we can keep using the old one and the propensity for blocking is high.

Support for subclasses or users specifying different flow controllers with different behavior. Build in support for either the simplest standard flow controller, or a standard repository-backed flow controller.

These objects attempt to maintain a CCN copy of the current state of their data. In descriptions below, an object that is "dirty" is one whose data has been modified locally, but not yet saved to the network.

While CCNNetworkObject could be used directly, it almost never is; it is usually more effective to define a subclass specialized to save/retrieve a specific object type.

Updates, 12/09: Move to creating a flow controller in the write constructor if one isn't passed in. Read constructors still lazily create flow controllers on first write (tradeoff); preemptive construction (and registering for interests) can be achieved by calling the setupSave() method which creates a flow controller if one hasn't been created already. Move to a strong default of saving to a repository, unless overridden by the subclass itself. Change of repository/raw nature can be made with the setRawSave() and setRepositorySave() methods.

TODO: Note that the CCNNetworkObject class hierarchy currently has a plethora of constructors. It is also missing some important functionality -- encryption, the ability to specify freshness, and so on. Expect new constructors to deal with the latter deficiencies, and a cleanup of the constructor architecture overall in the near term.


Constructor & Destructor Documentation

org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
boolean  contentIsMutable,
ContentName  name,
data,
SaveType  saveType,
CCNHandle  handle 
) throws IOException

Basic write constructor.

This will set the object's internal data but it will not save it until save() is called. Unless overridden by the subclass, will default to save to a repository. Can be changed to save directly to the network using setRawSave(). If a subclass sets the default behavior to raw saves, this can be overridden on a specific instance using setRepositorySave().

Parameters:
type Wrapped class type.
contentIsMutable is the wrapped class type mutable or not
name Name under which to save object.
data Data to save.
handle CCNHandle to use for network operations. If null, a new one is created using CCNHandle.open().
Exceptions:
IOException If there is an error setting up network backing store.
org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
boolean  contentIsMutable,
ContentName  name,
data,
SaveType  saveType,
PublisherPublicKeyDigest  publisher,
KeyLocator  locator,
CCNHandle  handle 
) throws IOException

Basic write constructor.

This will set the object's internal data but it will not save it until save() is called. Unless overridden by the subclass, will default to save to a repository. Can be changed to save directly to the network using setRawSave(). If a subclass sets the default behavior to raw saves, this can be overridden on a specific instance using setRepositorySave().

Parameters:
type Wrapped class type.
contentIsMutable is the wrapped class type mutable or not
name Name under which to save object.
data Data to save.
raw If true, saves to network by default, if false, saves to repository by default.
publisher The key to use to sign this data, or our default if null.
locator The key locator to use to let others know where to get our key.
handle CCNHandle to use for network operations. If null, a new one is created using CCNHandle.open().
Exceptions:
IOException If there is an error setting up network backing store.
org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
boolean  contentIsMutable,
ContentName  name,
data,
PublisherPublicKeyDigest  publisher,
KeyLocator  locator,
CCNFlowControl  flowControl 
) throws IOException [protected]

Specialized constructor, allowing subclasses to override default flow controller (and hence backing store) behavior.

Parameters:
type Wrapped class type.
contentIsMutable is the wrapped class type mutable or not
name Name under which to save object.
data Data to save.
publisher The key to use to sign this data, or our default if null.
locator The key locator to use to let others know where to get our key.
flowControl Flow controller to use. A single flow controller object is used for all this instance's writes, we use underlying streams to call CCNFlowControl.startWrite(ContentName, Shape) on each save. Calls to setRawSave() and setRepositorySave() will replace this flow controller with a raw or repository flow controller, and should not be used with this type of object (which obviously cares about what flow controller to use).
Exceptions:
IOException If there is an error setting up network backing store.
org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
boolean  contentIsMutable,
ContentName  name,
CCNHandle  handle 
) throws ContentDecodingException, IOException

Read constructor.

Will try to pull latest version of this object, or a specific named version if specified in the name. If read times out, will leave object in its uninitialized state.

Parameters:
type Wrapped class type.
contentIsMutable is the wrapped class type mutable or not
name Name from which to read the object. If versioned, will read that specific version. If unversioned, will attempt to read the latest version available.
handle CCNHandle to use for network operations. If null, a new one is created using CCNHandle.open().
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
boolean  contentIsMutable,
ContentName  name,
PublisherPublicKeyDigest  publisher,
CCNFlowControl  flowControl 
) throws ContentDecodingException, IOException [protected]

Read constructor.

Will try to pull latest version of this object, or a specific named version if specified in the name. If read times out, will leave object in its uninitialized state.

Parameters:
type Wrapped class type.
contentIsMutable is the wrapped class type mutable or not
name Name from which to read the object. If versioned, will read that specific version. If unversioned, will attempt to read the latest version available.
publisher Particular publisher we require to have signed the content, or null for any publisher.
flowControl Flow controller to use. A single flow controller object is used for all this instance's writes, we use underlying streams to call CCNFlowControl.startWrite(ContentName, Shape) on each save.
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
boolean  contentIsMutable,
ContentName  name,
PublisherPublicKeyDigest  publisher,
CCNHandle  handle 
) throws ContentDecodingException, IOException

Read constructor.

Will try to pull latest version of this object, or a specific named version if specified in the name. If read times out, will leave object in its uninitialized state.

Parameters:
type Wrapped class type.
contentIsMutable is the wrapped class type mutable or not
name Name from which to read the object. If versioned, will read that specific version. If unversioned, will attempt to read the latest version available.
publisher Particular publisher we require to have signed the content, or null for any publisher.
handle CCNHandle to use for network operations. If null, a new one is created using CCNHandle.open().
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
boolean  contentIsMutable,
ContentObject  firstSegment,
CCNHandle  handle 
) throws ContentDecodingException, IOException

Read constructor if you already have a segment of the object.

Used by streams.

Parameters:
type Wrapped class type.
contentIsMutable is the wrapped class type mutable or not
firstSegment First segment of the object, retrieved by other means.
raw If true, defaults to raw network writes, if false, repository writes.
handle CCNHandle to use for network operations. If null, a new one is created using CCNHandle.open().
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
boolean  contentIsMutable,
ContentObject  firstSegment,
CCNFlowControl  flowControl 
) throws ContentDecodingException, IOException [protected]

Read constructor if you already have a segment of the object.

Used by streams.

Parameters:
type Wrapped class type.
contentIsMutable is the wrapped class type mutable or not
firstSegment First segment of the object, retrieved by other means.
flowControl Flow controller to use. A single flow controller object is used for all this instance's writes, we use underlying streams to call CCNFlowControl.startWrite(ContentName, Shape) on each save.
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
org.ccnx.ccn.io.content.CCNNetworkObject< E >.CCNNetworkObject ( Class< E >  type,
CCNNetworkObject<?extends E >  other 
) [protected]

Copy constructor.

Handle it piece by piece, though it means updating this whenever the structure changes (rare).


Member Function Documentation

synchronized void org.ccnx.ccn.io.content.CCNNetworkObject< E >.close (  ) 

Close flow controller, remove listeners.

Have to call setupSave to save with this object again, re-add listeners.

Returns:
ContentType org.ccnx.ccn.io.content.CCNNetworkObject< E >.contentType (  ) 

Subclasses that need to write an object of a particular type can override.

DKS TODO -- verify type on read, modulo that ENCR overrides everything.

Returns:
synchronized void org.ccnx.ccn.io.content.CCNNetworkObject< E >.createFlowController (  )  throws IOException [protected]

Maximize laziness of flow controller creation, to make it easiest for client code to decide how to store this object.

When we create the flow controller, we add the base name namespace, so it will respond to requests for latest version. Create them immediately in write constructors, when we have a strong expectation that we will save data, if we have a namespace to start listening on. Otherwise wait till we are going to write.

Returns:
Exceptions:
IOException 
synchronized E org.ccnx.ccn.io.content.CCNNetworkObject< E >.data (  )  throws ContentNotReadyException, ContentGoneException, ErrorStateException [protected]

Retrieve this object's data.

Subclasses should expose methods to access/modify _data, but may choose not to expose _data itself. Ideally any dangerous operation (like giving access to some variable that could be changed) will mark the object as _isPotentiallyDirty. Changes to the data will then be detected automatically. (The use of _isPotentiallyDirty to control detection of content change is an optimization, otherwise isDirty() is invoked every time the object might need to be saved.)

Returns:
Returns the data. Whether null data is allowed or not is determined by the subclass, which can override available() (by default, data cannot be null).
Exceptions:
ContentNotReadyException if the object has not finished retrieving data/having data set
ErrorStateException 

Reimplemented from org.ccnx.ccn.io.content.NetworkObject< E >.

byte [] org.ccnx.ccn.io.content.CCNNetworkObject< E >.digestContent (  )  throws IOException [protected]

Encode and digest the object's content in order to detect changes made outside of the object's own interface (for example, if the data is accessed using data() and then modified).

Returns:
Exceptions:
ContentEncodingException if there is a problem encoding the content
IOException if there is a problem writing the object to the stream.

Reimplemented from org.ccnx.ccn.io.content.NetworkObject< E >.

synchronized void org.ccnx.ccn.io.content.CCNNetworkObject< E >.disableFlowControl (  ) 

Turn off flow control for this object.

Warning - calling this risks packet drops. It should only be used for tests or other special circumstances in which you "know what you are doing".

void org.ccnx.ccn.io.content.CCNNetworkObject< E >.finalize (  )  throws Throwable [protected]

Finalizer.

Somewhat dangerous, but currently best way to close lingering open registrations. Can't close the handle, till we ref count.

Long org.ccnx.ccn.io.content.CCNNetworkObject< E >.firstSegmentNumber (  ) 

Returns the first segment number for this object.

Returns:
The index of the first segment of stream data or null if no segments generated yet.
byte [] org.ccnx.ccn.io.content.CCNNetworkObject< E >.getFirstDigest (  ) 

Returns the digest of the first segment of this object which may be used to help identify object instance unambiguously.

Returns:
The digest of the first segment of this object if available, null otherwise
CCNFlowControl org.ccnx.ccn.io.content.CCNNetworkObject< E >.getFlowControl (  ) 

Get the flow controller associated with this object.

Returns:
the flow controller or null if not assigned
EnumSet<FlagTypes> org.ccnx.ccn.io.content.CCNNetworkObject< E >.getInputStreamFlags (  )  [protected]

Override point where subclasses can specify set of flags on input stream at point it is read or where necessary created.

Returns:
long org.ccnx.ccn.io.content.CCNNetworkObject< E >.getTimeout (  ) 

Get timeout associated with this object.

Returns:
synchronized ContentName org.ccnx.ccn.io.content.CCNNetworkObject< E >.getVersionedName (  ) 

If the object has been saved or read from the network, returns the (cached) versioned name.

Otherwise returns the base name.

Returns:
synchronized Interest org.ccnx.ccn.io.content.CCNNetworkObject< E >.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.

synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.hasListener ( UpdateListener  listener  ) 

Does this object already have this listener.

Uses Object.equals for comparison; so will only say yes if it has this *exact* listener instance already registered.

Parameters:
listener 
Returns:
void org.ccnx.ccn.io.content.CCNNetworkObject< E >.newVersionAvailable ( boolean  wasSave  )  [protected]

Used to signal waiters and listeners that a new version is available.

Parameters:
wasSave is a new version available because we were saved, or because we found a new version on the network?
synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.save ( CCNTime  version,
data 
) throws ContentEncodingException, IOException

Convenience method to the data and save it as a particular version in a single operation.

Parameters:
version the desired version
data new data for object, set with setData
Returns:
Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.save ( data  )  throws ContentEncodingException, IOException

Convenience method to the data and save it in a single operation.

Parameters:
data new data for object, set with setData
Returns:
Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.save ( CCNTime  version,
Interest  outstandingInterest 
) throws ContentEncodingException, IOException

Save to existing name, if content is dirty.

Saves to specified version. Method for CCNFilterListeners to save an object in response to an Interest callback. An Interest has already been received, so the object can output one ContentObject as soon as one is ready. Ideally this Interest will have been received on the CCNHandle the object is using for output. If the object is not dirty, it will not be saved, and the Interest will not be consumed. If the Interest does not match this object, the Interest will not be consumed; it is up to the caller to ensure that the Interest would be matched by writing this object. (If the Interest doesn't match, no initial block will be output even if the object is saved; the object will wait for matching Interests prior to writing its blocks.)

boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.save ( CCNTime  version  )  throws ContentEncodingException, IOException

Save to existing name, if content is dirty.

Saves to specified version. This is the default form of save -- if the object has been told to use a repository backing store, by either giving it a repository flow controller, calling saveToRepository() on it for its first save, or specifying false to a constructor that allows a raw argument, it will save to a repository. Otherwise will perform a raw save.

Parameters:
version Version to save to.
Returns:
true if object was saved, false if it was not (if it was not dirty).
Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.save ( Interest  outstandingInterest  )  throws ContentEncodingException, IOException

Method for CCNFilterListeners to save an object in response to an Interest callback.

An Interest has already been received, so the object can output one ContentObject as soon as one is ready. Ideally this Interest will have been received on the CCNHandle the object is using for output. If the object is not dirty, it will not be saved, and the Interest will not be consumed. If the Interest does not match this object, the Interest will not be consumed; it is up to the caller to ensure that the Interest would be matched by writing this object. (If the Interest doesn't match, no initial block will be output even if the object is saved; the object will wait for matching Interests prior to writing its blocks.)

boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.save (  )  throws ContentEncodingException, IOException

Save to existing name, if content is dirty.

Update version. This is the default form of save -- if the object has been told to use a repository backing store, by either giving it a repository flow controller, calling saveToRepository() on it for its first save, or specifying false to a constructor that allows a raw argument, it will save to a repository. Otherwise will perform a raw save.

Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.saveAsGone ( Interest  outstandingInterest  )  throws ContentEncodingException, IOException

For use by CCNFilterListeners, saves a GONE object and emits an inital block in response to an already-received Interest.

Save this object as GONE. Intended to mark the latest version, rather than a specific version as GONE. So for now, require that name handed in is *not* already versioned; throw an IOException if it is.

Exceptions:
IOException 
synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.saveAsGone (  )  throws ContentEncodingException, IOException

Save this object as GONE.

Intended to mark the latest version, rather than a specific version as GONE. So for now, require that name handed in is *not* already versioned; throw an IOException if it is.

Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.saveInternal ( CCNTime  version,
boolean  gone,
Interest  outstandingInterest 
) throws ContentEncodingException, IOException [protected]

Save content to specific version.

Internal form that performs actual save.

Parameters:
version If version is non-null, assume that is the desired version. If not, set version based on current time.
gone Are we saving this content as gone or not.
Returns:
return Returns true if it saved data, false if it thought data was not dirty and didn't save. TODO allow freshness specification
Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.saveToRepository ( CCNTime  version,
data 
) throws ContentEncodingException, IOException

Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.

Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.saveToRepository ( data  )  throws ContentEncodingException, IOException

Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.

Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.saveToRepository (  )  throws ContentEncodingException, IOException

Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.

Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.saveToRepository ( CCNTime  version  )  throws ContentEncodingException, IOException

Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.

If raw=true or DEFAULT_RAW=true specified, this must be the first call to save made for this object to force repository storage (overriding default).

Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.saveToRepositoryAsGone (  )  throws ContentEncodingException, IOException

Deprecated; use either object defaults or setRepositorySave() to indicate writes should go to a repository, then call save() to write.

If raw=true or DEFAULT_RAW=true specified, this must be the first call to save made for this object.

Exceptions:
ContentEncodingException if there is an error encoding the content
IOException if there is an error reading the content from the network
synchronized void org.ccnx.ccn.io.content.CCNNetworkObject< E >.setData ( data  ) 

Set a new data value for this object.

Mark it as dirty (needing to be saved).

Parameters:
data new value

Reimplemented from org.ccnx.ccn.io.content.NetworkObject< E >.

void org.ccnx.ccn.io.content.CCNNetworkObject< E >.setFreshnessSeconds ( Integer  freshnessSeconds  ) 

If you want to set the lifetime of objects saved with this instance.

Parameters:
freshnessSeconds If null, will unset any freshness seconds (will write objects that stay in cache till forced out); if a value will constrain how long objects will stay in cache.
void org.ccnx.ccn.io.content.CCNNetworkObject< E >.setInputStreamProperties ( CCNInputStream  inputStream  )  [protected]

Override point where subclasses can modify each input stream before it is read.

Subclasses should at least set the flags using getInputStreamFlags, or call super.setInputStreamProperties.

synchronized void org.ccnx.ccn.io.content.CCNNetworkObject< E >.setOurPublisherInformation ( PublisherPublicKeyDigest  publisherIdentity,
KeyLocator  keyLocator 
)

Change the publisher information we use when we sign commits to this object.

Takes effect on the next save(). Useful for objects created with a read constructor, but who want to override default publisher information.

Parameters:
signingKey indicates the identity we want to use to sign future writes to this object. If null, will default to key manager's (user's) default key.
locator the key locator (key lookup location) information to attach to future writes to this object. If null, will be the default value associated with the chosen signing key.
void org.ccnx.ccn.io.content.CCNNetworkObject< E >.setSaveType ( SaveType  saveType  )  throws IOException [protected]

Used by subclasses to specify a mandatory save type in read constructors.

Only works on objects whose flow controller has not yet been set, to not override manually-set FC's.

synchronized void org.ccnx.ccn.io.content.CCNNetworkObject< E >.setupSave ( SaveType  saveType  )  throws IOException

Start listening to interests on our base name, if we aren't already.

Exceptions:
IOException 
void org.ccnx.ccn.io.content.CCNNetworkObject< E >.setVerifier ( ContentVerifier  verifier  ) 

Allow verifier to be specified.

Could put this in the constructors; though they are already complicated enough. If not set, the default verifier for the key manager used by the object's handle is used.

Parameters:
verifier the verifier to use. Cannot be null.
synchronized boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.update ( CCNInputStream  inputStream  )  throws ContentDecodingException, IOException

Updates the object from a CCNInputStream or one of its subclasses.

Used predominantly by internal methods, most clients should use update() or update(long). Exposed for special-purpose use and experimentation.

Parameters:
inputStream Stream to read object from.
Returns:
true if an update found, false if not.
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.update ( ContentObject  object  )  throws ContentDecodingException, IOException

Load a stream starting with a specific object.

Parameters:
object 
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.update ( ContentName  name,
PublisherPublicKeyDigest  publisher 
) throws ContentDecodingException, IOException

Load data into object.

If name is versioned, load that version. If name is not versioned, look for latest version.

Parameters:
name Name of object to read.
publisher Desired publisher, or null for any.
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.update (  )  throws ContentDecodingException, IOException

Calls update(long) with the default timeout SystemConfiguration.getDefaultTimeout().

Returns:
see update(long).
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.update ( long  timeout  )  throws ContentDecodingException, IOException

Attempts to find a version after the latest one we have, or times out.

If it times out, it simply leaves the object unchanged.

Returns:
returns true if it found an update, false if not
Exceptions:
ContentDecodingException if there is a problem decoding the object.
IOException if there is an error setting up network backing store.
boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >.updateAny ( long  timeout  )  throws ContentDecodingException, IOException

The regular update does a call to do multi-hop get latest version -- i.e.

it will try multiple times to find the latest version of a piece of content, even if interposed caches have something older. While that's great when you really need the latest, sometimes you are happy with the latest available version available in your local ccnd cache; or you really know there is only one version available and you don't want to try multiple times (and incur a timeout) in an attempt to get a later version that does not exist. This call, updateAny, claims to get "any" version available. In reality, it will do a single-hop latest version; i.e. if there are two versions say in your local ccnd cache (or repo with nothing in the ccnd cache), it will pull the later one. But it won't move beyond those to find a newer version available at a writer, or to find a later version in the repo than one in the ccnd cache. Use this if you know there is only one version of something, or you want a fast path to the latest version where it really doesn't have to be the "absolute" latest.

Like all update methods, it will start from the version you've got -- so it is guaranteed to find something after the current version this object knows about (if it has already found something), and to time out and return false if there isn't anything later.

synchronized void org.ccnx.ccn.io.content.CCNNetworkObject< E >.updateInBackground ( ContentName  latestVersionKnown,
boolean  continuousUpdates,
UpdateListener  listener 
) throws IOException

Update this object in the background -- asynchronously.

To use, create an object using a write constructor, setting the data field to null. Then call updateInBackground() to retrieve the object's data asynchronously. To wait for an update to arrive, call wait() on this object itself.

Parameters:
latestVersionKnown the name of the latest version we know of, or an unversioned name if no version known
continuousUpdates If true, updates the object continuously to the latest version available, a single time if it is false.
Exceptions:
IOException 
void org.ccnx.ccn.io.content.CCNNetworkObject< E >.updateInBackground ( boolean  continuousUpdates  )  throws IOException

Update this object in the background -- asynchronously.

To use, create an object using a write constructor, setting the data field to null. Then call updateInBackground() to retrieve the object's data asynchronously. To wait for an update to arrive, call wait() on this object itself.

Parameters:
continuousUpdates If true, updates the object continuously to the latest version available, a single time if it is false.
Exceptions:
IOException 
void org.ccnx.ccn.io.content.CCNNetworkObject< E >.updateInBackground (  )  throws IOException

Update this object in the background -- asynchronously.

This call updates the object a single time, after the first update (the requested version or the latest version), the object will not self-update again unless requested. To use, create an object using a write constructor, setting the data field to null. Then call updateInBackground() to retrieve the object's data asynchronously. To wait on data arrival, call either waitForData() or wait() on the object itself.

Exceptions:
IOException 
void org.ccnx.ccn.io.content.CCNNetworkObject< E >.waitForData ( long  timeout  ) 

Will wait for data to arrive.

Callers should use available() to determine whether data has arrived or not. If data already available, will return immediately (in other words, this is only useful to wait for the first update to an object, or to ensure that it has data). To wait for later updates, call wait() on the object itself.

Parameters:
timeout In milliseconds. If 0, will wait forever (if data does not arrive).

Member Data Documentation

LinkObject org.ccnx.ccn.io.content.CCNNetworkObject< E >._dereferencedLink [protected]

If the name we started with was actually a link, detect that, store the link, and dereference it to get the content.

Call updateLink() to update the link itself, and if updated, to update the dereferenced value.

If the initial link is a link, recursion should push that into the link of this LinkObject, and read its data. If that is a link, it should push again -- this should chain through links till we reach an object of the desired type, or blow up. (It won't handle encrypted links, though; we may need to distinguish between ENCR and ENCRL. Having encrypted links would be handy, to send people off in random directions. But it matters a lot to be able to tell if the decryption is a LINK or not.)

Writing linked objects is better done by separately writing the object and the link, as it gives you more control over what is happening. If you attempt to save this object, it may break the link (as the link may link to the particular version retrieved). You can use this inner link object to manually update the link to the target; but there are no good defaults about how to update the data. So you need to specify the new link value yourself. For now we don't prevent users from getting their data and their links de-syncrhonized.

boolean org.ccnx.ccn.io.content.CCNNetworkObject< E >._isGone = false [protected]

Flag to indicate whether content has been explicitly marked as GONE in the latest version we know about.

Use an explicit flag to separate from the option for valid null content, or content that has not yet been updated.


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