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

A NetworkObject provides support for storing an object in a network based backing store. More...

List of all members.

Public Member Functions

 NetworkObject (Class< E > type, boolean contentIsMutable)
 Subclasses need to specify the type as an argument as well as a template parameter in order to make factory methods work properly.
 NetworkObject (Class< E > type, boolean contentIsMutable, E data)
 Specify type as well as initial data.
void update (InputStream input) throws ContentDecodingException, IOException
 Read this object's data from the network.
synchronized boolean available ()
synchronized boolean hasError ()
synchronized IOException getError ()
synchronized void clearError ()
synchronized void setData (E data)
 Set a new data value for this object.
synchronized void forceSave (OutputStream output) throws ContentEncodingException, IOException
 Save the object regardless of whether it has been modified (isDirty()) or not.
synchronized void save (OutputStream output) throws ContentEncodingException, IOException
 Save the object if it is dirty (has been changed).
synchronized boolean isSaved () throws IOException
byte[] getContentDigest () throws IOException
 Extract the content digest (made with the default digest algorithm).
int hashCode ()
boolean equals (Object obj)
boolean contentEquals (Object obj)
 Equality comparison on just the internal data.
String toString ()

Static Public Attributes

static final String DEFAULT_CHECKSUM_ALGORITHM = "MD5"
 Care about speed, not collision-resistance.

Protected Member Functions

 NetworkObject (Class< E > type, NetworkObject<?extends E > other)
factory () throws IOException
 Create an instance of the parameterized type, used for decoding.
synchronized void setError (IOException t)
synchronized void setAvailable (boolean available)
synchronized E data () throws ContentNotReadyException, ContentGoneException, ErrorStateException
 Retrieve this object's data.
byte[] digestContent () throws ContentEncodingException, 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 boolean isDirty () throws ContentEncodingException, IOException
 Encode the object and see whether its digest has changed since last time it was saved.
synchronized void setDirty (boolean dirty)
synchronized void internalWriteObject (OutputStream output) throws ContentEncodingException, IOException
 Save the object and update the internal tracking digest of its last-saved content.
abstract void writeObjectImpl (OutputStream output) throws ContentEncodingException, IOException
 Subclasses override.
abstract E readObjectImpl (InputStream input) throws ContentDecodingException, IOException
 Subclasses override.

Protected Attributes

Class< E > _type
_data
boolean _isDirty = false
boolean _isPotentiallyDirty = false
boolean _contentIsMutable = false
 Is it possible to modify the type of data we contain directly from a pointer to the object, or do we have to replace the whole thing to change its value? For example, a Java String or BigInteger is immutable (modulo reflection-based abstraction violations).
byte[] _lastSaved
boolean _available = false
IOException _errorState = null
 Track error state in a subclass-compatible way by storing the last exception we threw.

Detailed Description

A NetworkObject provides support for storing an object in a network based backing store.

It provides support for loading the object from the network, tracking if the object's data has been changed, to determine whether it needs to be saved or not and saving the object.

It can have 3 states:

It can be:

Subclasses can vary as to whether they think null is valid data for an object -- i.e. whether assigning the object's value to null makes it available or not. The default behavior is to not treat a null assignment as a value -- i.e. not available.


Constructor & Destructor Documentation

org.ccnx.ccn.io.content.NetworkObject< E >.NetworkObject ( Class< E >  type,
boolean  contentIsMutable 
)

Subclasses need to specify the type as an argument as well as a template parameter in order to make factory methods work properly.

Parameters:
type Should be same as class template parameter.
contentIsMutable Is the class we are encapsulating mutable (its content can be modified without replacing the object reference) or immutable (the only way to change it is to replace it, or here set it with setData). Unfortunately there is no way to determine this via reflection. You could also set this to false if you do not expose the data directly, but merely expose methods to modify its values, and manage _isPotentiallyDirty directly.
org.ccnx.ccn.io.content.NetworkObject< E >.NetworkObject ( Class< E >  type,
boolean  contentIsMutable,
data 
)

Specify type as well as initial data.

Parameters:
type Should be same as class template parameter.
contentIsMutable Is the class we are encapsulating mutable (its content can be modified without replacing the object reference) or immutable (the only way to change it is to replace it, or here set it with setData). Unfortunately there is no way to determine this via reflection. You could also set this to false if you do not expose the data directly, but merely expose methods to modify its values, and manage _isPotentiallyDirty directly.
data Initial data value.

Member Function Documentation

synchronized boolean org.ccnx.ccn.io.content.NetworkObject< E >.available (  ) 
Returns:
true if the object has been updated from the network, or has had its data value set to a non-null value (whether it has been saved to the network or not).
boolean org.ccnx.ccn.io.content.NetworkObject< E >.contentEquals ( Object  obj  ) 

Equality comparison on just the internal data.

Parameters:
obj 
Returns:
true if other is a NetworkObject and the two have matching data().
synchronized E org.ccnx.ccn.io.content.NetworkObject< 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 in org.ccnx.ccn.io.content.CCNNetworkObject< E >.

byte [] org.ccnx.ccn.io.content.NetworkObject< E >.digestContent (  )  throws ContentEncodingException, 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 in org.ccnx.ccn.io.content.CCNNetworkObject< E >.

E org.ccnx.ccn.io.content.NetworkObject< E >.factory (  )  throws IOException [protected]

Create an instance of the parameterized type, used for decoding.

Returns:
the new instance
Exceptions:
IOException wrapping other types of exception generated by constructor.
synchronized void org.ccnx.ccn.io.content.NetworkObject< E >.forceSave ( OutputStream  output  )  throws ContentEncodingException, IOException

Save the object regardless of whether it has been modified (isDirty()) or not.

Parameters:
output stream to save to
Exceptions:
ContentEncodingException if there is an error encoding the object
IOException if there is an error writing the object to the network
byte [] org.ccnx.ccn.io.content.NetworkObject< E >.getContentDigest (  )  throws IOException

Extract the content digest (made with the default digest algorithm).

Exceptions:
IOException 
synchronized void org.ccnx.ccn.io.content.NetworkObject< E >.internalWriteObject ( OutputStream  output  )  throws ContentEncodingException, IOException [protected]

Save the object and update the internal tracking digest of its last-saved content.

Parameters:
output stream to write to.
Exceptions:
ContentEncodingException if there is an error encoding the object
IOException if there is an error writing the object to the network
synchronized boolean org.ccnx.ccn.io.content.NetworkObject< E >.isDirty (  )  throws ContentEncodingException, IOException [protected]

Encode the object and see whether its digest has changed since last time it was saved.

Conservative, only runs the full check if _isPotentiallyDirty is true.

Returns:
true if the object has been modified.
Exceptions:
IOException if there is a problem encoding the object.
synchronized boolean org.ccnx.ccn.io.content.NetworkObject< E >.isSaved (  )  throws IOException
Returns:
True if the content was either read from the network or was saved locally.
abstract E org.ccnx.ccn.io.content.NetworkObject< E >.readObjectImpl ( InputStream  input  )  throws ContentDecodingException, IOException [protected, pure virtual]

Subclasses override.

This implements the actual object read from stream, returning the new object.

Exceptions:
ContentDecodingException if there is an error decoding the object
IOException if there is an error actually reading the data

Implemented in org.ccnx.ccn.io.content.CCNEncodableObject< E extends XMLEncodable >, org.ccnx.ccn.io.content.CCNSerializableObject< E extends Serializable >, org.ccnx.ccn.io.content.EncodableObject< E extends XMLEncodable >, and org.ccnx.ccn.io.content.SerializableObject< E extends Serializable >.

synchronized void org.ccnx.ccn.io.content.NetworkObject< E >.save ( OutputStream  output  )  throws ContentEncodingException, IOException

Save the object if it is dirty (has been changed).

Parameters:
output stream to write to.
Exceptions:
ContentEncodingException if there is an error encoding the object
IOException if there is an error writing the object to the network.
synchronized void org.ccnx.ccn.io.content.NetworkObject< E >.setAvailable ( boolean  available  )  [protected]
Parameters:
available the new value
synchronized void org.ccnx.ccn.io.content.NetworkObject< E >.setData ( data  ) 

Set a new data value for this object.

Mark it as dirty (needing to be saved).

Parameters:
data new value

Reimplemented in org.ccnx.ccn.io.content.CCNNetworkObject< E >.

synchronized void org.ccnx.ccn.io.content.NetworkObject< E >.setDirty ( boolean  dirty  )  [protected]
Parameters:
dirty new value for the dirty setting.
void org.ccnx.ccn.io.content.NetworkObject< E >.update ( InputStream  input  )  throws ContentDecodingException, IOException

Read this object's data from the network.

Parameters:
input InputStream holding the object's data.
Exceptions:
ContentDecodingException if there is an error decoding the object
IOException if there is an error reading the object from the network
abstract void org.ccnx.ccn.io.content.NetworkObject< E >.writeObjectImpl ( OutputStream  output  )  throws ContentEncodingException, IOException [protected, pure virtual]

Subclasses override.

This implements the actual object write. No flush or close necessary.

Parameters:
output the stream to write to
Exceptions:
ContentEncodingException if there is an error encoding the object
IOException if there is an error writing it to the network

Implemented in org.ccnx.ccn.io.content.CCNEncodableObject< E extends XMLEncodable >, org.ccnx.ccn.io.content.CCNSerializableObject< E extends Serializable >, org.ccnx.ccn.io.content.EncodableObject< E extends XMLEncodable >, and org.ccnx.ccn.io.content.SerializableObject< E extends Serializable >.


Member Data Documentation

boolean org.ccnx.ccn.io.content.NetworkObject< E >._contentIsMutable = false [protected]

Is it possible to modify the type of data we contain directly from a pointer to the object, or do we have to replace the whole thing to change its value? For example, a Java String or BigInteger is immutable (modulo reflection-based abstraction violations).

A complex structure whose fields can be set would be mutable. We want to track whether the content of the object has been changed either using setData or outside of the object interface; this is an optimization to allow us to avoid the outside-the-object checks for immutable objects.


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