A NetworkObject provides support for storing an object in a network based backing store. More...
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) | |
E | 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 |
E | _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. |
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.
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.
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, | |||
E | data | |||
) |
Specify type as well as initial data.
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. |
synchronized boolean org.ccnx.ccn.io.content.NetworkObject< E >.available | ( | ) |
boolean org.ccnx.ccn.io.content.NetworkObject< E >.contentEquals | ( | Object | obj | ) |
Equality comparison on just the internal data.
obj |
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.)
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).
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.
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.
output | stream to save to |
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).
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.
output | stream to write to. |
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.
IOException | if there is a problem encoding the object. |
synchronized boolean org.ccnx.ccn.io.content.NetworkObject< E >.isSaved | ( | ) | throws IOException |
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.
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).
output | stream to write to. |
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] |
available | the new value |
synchronized void org.ccnx.ccn.io.content.NetworkObject< E >.setData | ( | E | data | ) |
Set a new data value for this object.
Mark it as dirty (needing to be saved).
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] |
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.
input | InputStream holding the object's data. |
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.
output | the stream to write to |
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 >.
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.