org.ccnx.ccn.io.content.Link Class Reference

Represents a secure, authenticatable link from one part of the CCN namespace to another. More...

Inheritance diagram for org.ccnx.ccn.io.content.Link:

org.ccnx.ccn.impl.encoding.GenericXMLEncodable org.ccnx.ccn.impl.encoding.XMLEncodable org.ccnx.ccn.impl.encoding.XMLEncodable org.ccnx.ccn.profiles.security.access.group.ACL.ACLOperation

List of all members.

Public Member Functions

 Link (ContentName targetName, String targetLabel, LinkAuthenticator targetAuthenticator)
 Link (ContentName targetName, LinkAuthenticator targetAuthenticator)
 Link (ContentName targetName)
 Link ()
 Decoding constructor.
 Link (Link other)
ContentName targetName ()
String targetLabel ()
LinkAuthenticator targetAuthenticator ()
void setTargetLabel (String label)
void setTargetName (ContentName name)
void setTargetAuthenticator (LinkAuthenticator authenticator)
ContentObject dereference (long timeout, CCNHandle handle) throws IOException
 A stab at a dereference() method.
void decode (XMLDecoder decoder) throws ContentDecodingException
 Decode this object as the top-level item in a new XML document, reading it from a network buffer.
void encode (XMLEncoder encoder) throws ContentEncodingException
 Encode this object during an ongoing encoding pass; this is what subclasses generally need to know how to implement.
long getElementLabel ()
 Allow the encoder/decoder to retrieve the top-level element name programmatically.
boolean validate ()
 Make sure all of the necessary fields are filled in prior to attempting to encode.
int hashCode ()
boolean approximates (Link linkToMatch)
 Return true if this link matches target on all fields where target is non-null.
boolean equals (Object obj)
Object clone () throws CloneNotSupportedException
String toString ()
 Default toString() implementation simply prints the text encoding of the object.

Protected Attributes

ContentName _targetName
String _targetLabel
LinkAuthenticator _targetAuthenticator = null

Classes

class  LinkObject
 A CCNNetworkObject wrapper around Link, used for easily saving and retrieving versioned Links to CCN. More...


Detailed Description

Represents a secure, authenticatable link from one part of the CCN namespace to another.

CCN links are very flexible and can be used to represent a wide variety of application-level structures. A link can point to a specific content object (an individual block of content), the collection of "segments" making up a specific version of a stream or document, an aggregated "document" object consisting of multiple versions and their associated metadata, or to an arbitrary point in the name tree -- essentially saying "treat the children of this node as if they were my children".

CCN links have authentication information associated with them, and can be made highly secure -- by specifying who should have published (signed) the target of a given link, one can say effectively "what I mean by name N is whatever Tom means by name N'". The authentication information associated with a Link is called a LinkAuthenticator; its form and capabilities are still evolving, but it will at least have the ability to offer indirection -- "trust anyone whose key is signed by key K to have signed a valid target for this link".

Links also play an important role in making up Collections, the CCN notion of a container full of objects or names.


Member Function Documentation

ContentObject org.ccnx.ccn.io.content.Link.dereference ( long  timeout,
CCNHandle  handle 
) throws IOException

A stab at a dereference() method.

Dereferencing is not well-defined in this general setting -- we don't know what we'll find down below this name. A link may link to anything in the tree, including an intermediate node, or a name qualified down to the digest, and we need a way of distinguishing these things (TODO). Usually you'll read the target of the link using a method that knows something about what kind of data to find there. This is a brute-force method that hands you back a block underneath the link target name that meets the authentication criteria; at minimum it should pull an exact match if the link fully specifies digests and so on (TODO -- TBD), and otherwise it'll probably assume that what is below here is either a version and segments (get latest version) or that this is versioned and it wants segments.

Parameters:
timeout How long to try for, in milliseconds.
handle Handle to use. Should not be null.
Returns:
Returns a child object. Verifies that it meets the requirement of the link, and that it is signed by who it claims. Could allow caller to pass in verifier to verify higher-level trust and go look for another block on failure.
Exceptions:
IOException 

void org.ccnx.ccn.io.content.Link.decode ( XMLDecoder  decoder  )  throws ContentDecodingException [virtual]

Decode this object as the top-level item in a new XML document, reading it from a network buffer.

Reads document start and end. Assumes default encoding.

Parameters:
buf input stream to read from
Exceptions:
ContentDecodingException if there is an error decoding the content Decode this object as the top-level item in a new XML document, reading it from a network buffer. Reads document start and end.
Parameters:
buf input stream to read from
codec the codec to use; must be recognized by XMLCodecFactory
Exceptions:
ContentDecodingException if there is an error decoding the content
See also:
XMLCodecFactory Decode this object during an ongoing decoding pass; this is what subclasses generally need to know how to implement. Reads just the object itself, higher-level processes have handled start and end document if need be. Allows object to be read using the same code whether it is a top-level element written alone, or nested inside another element.
Parameters:
decoder the decoder being used; encapsulates state including the codec being used as well as the input source and current offset

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

void org.ccnx.ccn.io.content.Link.encode ( XMLEncoder  encoder  )  throws ContentEncodingException [virtual]

Encode this object during an ongoing encoding pass; this is what subclasses generally need to know how to implement.

Writes just the object itself, higher-level processes have handled start and end document if need be. Allows object to be written using the same code whether it is a top-level element written alone, or nested inside another element.

Parameters:
encoder the encoder being used; encapsulates state including the codec being used as well as the output destination and current offset

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

long org.ccnx.ccn.io.content.Link.getElementLabel (  )  [virtual]

Allow the encoder/decoder to retrieve the top-level element name programmatically.

This allows subclasses to rename elements without changing their encoder/decoders.

Returns:
the element label to use, as a key in a loaded encoding dictionary

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

Reimplemented in org.ccnx.ccn.profiles.security.access.group.ACL.ACLOperation.

boolean org.ccnx.ccn.io.content.Link.validate (  )  [virtual]

Make sure all of the necessary fields are filled in prior to attempting to encode.

All implementations of encode(XMLEncoder) should call this for their classes prior to encoding.

Returns:
true if object is valid and can be encoded, false if there is a problem; for example mandatory fields are uninitialized

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

boolean org.ccnx.ccn.io.content.Link.approximates ( Link  linkToMatch  ) 

Return true if this link matches target on all fields where target is non-null.

Parameters:
linkToMatch The specification of the values we want.
Returns:

String org.ccnx.ccn.io.content.Link.toString (  ) 

Default toString() implementation simply prints the text encoding of the object.

This demonstrates how to force use of the text encoding.

Reimplemented from org.ccnx.ccn.impl.encoding.GenericXMLEncodable.


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

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