hypercast
Class NamingBinding

java.lang.Object
  |
  +--hypercast.NamingBinding
All Implemented Interfaces:
hypercast.I_LRUObject, I_NamingBinding

public class NamingBinding
extends java.lang.Object
implements I_NamingBinding, hypercast.I_LRUObject

A NamingBinding object binds a single name to a single logical address. It has a timestamp which records the creation time of the binding (NB: not necessarily the creation time of the NamingBinding object). It also has a metric that reflects the number of times that the socket that created the binding has changed its logical address. Finally it has an optional digitial signature that ensures the integrity and the authenticity of the binding information. All of the naming binding fields mentioned thusfar are immutable - fixed at the time of the creation of the binding. Binding information received from peers can never be modified so a NamingBinding object that represents such data has fixed fields. A NamingBinding object that represents a local binding has its fields (except name) updated on demand to reflect current values. This on-demand update is the responsibility of some container that holds binding objects. This container calls the various "setter" methods when it wants an updated binding. In the current (Spring 2005) implementation of the Naming Service this container is the PeerBindingCache of the Naming Service Message Store FSM. Bindings also have the notion of being authoritative or not authoritative. This refers to whether or not a binding was received from the peer that created the binding. This field of the binding is not covered by the digital signature because if it was, it could never change. As an example, consider three peers: A, B, and C. A creates a binding and sends it to B where it is cached. Next, B sends the cached binding to C. B received an authoritative binding because it received the binding from A and A created the binding. C did not received an authoritative binding; C received a cached copy. Note that the authoritiative binding and the cached binding both have a digital signature created by A. In particular B does not resign the binding, therefore it cannot alter any fields of the binding. If the authoritative field was included in the digital signature computation B could not change the authoritative field to mean "not authoritative" when transmitting the binding to C. A binding can be created locally or it can be received from a peer. An argument can be made that this class [sc]ould be factored into two subclasses: LocalBinding and PeerBinding, instead an instance variable, local, is used to control the behavior of particular objects. There is no synchronization provided by this class. It is assumed that the caller ensures synchronization. For example, computing a digital signature using the data from an object of this class while simultaneously altering that data in another thread is almost certainly a Bad Thing.


Field Summary
 java.lang.String signerName
          Subject common name of certificate needed to verify the digital signature of the binding (digital signature optional)
 
Constructor Summary
NamingBinding(java.lang.String name, java.lang.String logicalAddressString, java.lang.String signerName)
          Base class constructor called when bindings are created locally.
 
Method Summary
static byte[] bindingsToByteArray(hypercast.NamingBinding[] bindings, java.security.Signature signer, hypercast.CertificateCache certificateCache)
          Concatenates byte representations of all bindings into single byte array.
 void clearTrusted()
          Used in situation where trusted state should not be set permanently - like in experiments
 long getAge(long now)
          Returns the age of the binding in milleseconds relative to the time parameter given.
 int getLogicalAddressChangeCounter()
          Returns the number of times that the logical address of the socket that made this binding changed at the time the binding was created.
 java.lang.String getLogicalAddressString()
          Returns the logical address of the binding.
 java.lang.String getName()
          Returns the name of the binding.
 java.lang.String getSignerName()
           
 hypercast.LRUTimeoutQueue.Entry getTimeoutQueueEntry()
          Returns a pointer to an entry in a timeout queue for this binding.
 long getTimestamp()
          Returns the time the binding was created.
 boolean isAuthoritative()
          Returns whether or not this binding was received from an authoritative source (local implies authoritative).
 boolean isLocal()
          Returns whether or not this binding was created by the local socket.
 boolean isTrusted()
          This method is part of the binding interface that is not used here.
 boolean isTrusted(java.security.Signature signer, hypercast.CertificateCache.Entry certificateCacheEntry)
          Decides if this binding is trusted using certificates.
static hypercast.NamingBinding[] restoreInvalidateNamingBindings(byte[] data, int offset)
          Creates invalidation naming binding object given an array of one or more serialized bindingss.
static hypercast.NamingBinding[] restoreNamingBindings(byte[] data, int offset)
          Creates naming binding object given an array of one or more serialized bindingss.
static hypercast.NamingBinding[] restoreNamingBindings(byte[] data, int index, boolean makeInvalidate)
          Given an array of serialized binding objects, parses array and instanciates objects.
 void setLogicalAddressChangeCounter(int logicalAddressChangeCounter)
          Sets the value of the logical address change counter for a local binding.
 void setLogicalAddressString(java.lang.String logicalAddressString)
          Sets the logical address of the local binding.
 void setTimeoutQueueEntry(hypercast.LRUTimeoutQueue.Entry toqEntry)
          Sets the timeout queue entry for a binding.
 void setTimestamp(long timestamp)
          Sets the values of the timestamp for a local binding.
 byte[] toByteArray(java.security.Signature signer, java.security.PrivateKey privateKey)
          Serializes and signs a binding.
 java.lang.String toString()
          Creates a string with information about the binding object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

signerName

public java.lang.String signerName
Subject common name of certificate needed to verify the digital signature of the binding (digital signature optional)

Constructor Detail

NamingBinding

public NamingBinding(java.lang.String name,
                     java.lang.String logicalAddressString,
                     java.lang.String signerName)
Base class constructor called when bindings are created locally.

Parameters:
name - Bound name
logicalAddressString - Bound logical address
signerName - Subject common name of certificate needed to verify the digital signature of the binding (digital signature optional)
Method Detail

getName

public java.lang.String getName()
Returns the name of the binding. The name field of objects of this class can only be set by a constructor.

Specified by:
getName in interface I_NamingBinding

getSignerName

public java.lang.String getSignerName()

getLogicalAddressString

public java.lang.String getLogicalAddressString()
Returns the logical address of the binding.

Specified by:
getLogicalAddressString in interface I_NamingBinding

setLogicalAddressString

public void setLogicalAddressString(java.lang.String logicalAddressString)
Sets the logical address of the local binding.


getLogicalAddressChangeCounter

public int getLogicalAddressChangeCounter()
Returns the number of times that the logical address of the socket that made this binding changed at the time the binding was created.

Specified by:
getLogicalAddressChangeCounter in interface I_NamingBinding

setLogicalAddressChangeCounter

public void setLogicalAddressChangeCounter(int logicalAddressChangeCounter)
Sets the value of the logical address change counter for a local binding.


getTimestamp

public long getTimestamp()
Returns the time the binding was created.

Specified by:
getTimestamp in interface I_NamingBinding

setTimestamp

public void setTimestamp(long timestamp)
Sets the values of the timestamp for a local binding.


getAge

public long getAge(long now)
Returns the age of the binding in milleseconds relative to the time parameter given.


isLocal

public boolean isLocal()
Returns whether or not this binding was created by the local socket.

Specified by:
isLocal in interface I_NamingBinding

isAuthoritative

public boolean isAuthoritative()
Returns whether or not this binding was received from an authoritative source (local implies authoritative). The authoritive aspect of an object of this class is determined at construction time and stays fixed, i.e. there is no "setAuthoritative" method, even for local bindings. When a binding is serialized for sending to a peer the authoritative field in the serialized representation is set appropriately, i.e. authoritiative if the binding was created locally, non-authoritative if the binding was received from a peer.

Specified by:
isAuthoritative in interface I_NamingBinding
See Also:
toByteArray(Signature,PrivateKey)

isTrusted

public boolean isTrusted()
This method is part of the binding interface that is not used here. To establish trust in this implemenation a digital signature verifier and certificate cache entry must be provided.

Specified by:
isTrusted in interface I_NamingBinding

isTrusted

public boolean isTrusted(java.security.Signature signer,
                         hypercast.CertificateCache.Entry certificateCacheEntry)
Decides if this binding is trusted using certificates. Local bindings are considered to be trusted by definition.

Parameters:
signer - Security object used to sign the binding information.
certificateCacheEntry - Entry of certificate cache that points the certificate needed for the crypto operations of this method.

clearTrusted

public void clearTrusted()
Used in situation where trusted state should not be set permanently - like in experiments


getTimeoutQueueEntry

public hypercast.LRUTimeoutQueue.Entry getTimeoutQueueEntry()
Returns a pointer to an entry in a timeout queue for this binding.

Specified by:
getTimeoutQueueEntry in interface hypercast.I_LRUObject

setTimeoutQueueEntry

public void setTimeoutQueueEntry(hypercast.LRUTimeoutQueue.Entry toqEntry)
Sets the timeout queue entry for a binding.

Specified by:
setTimeoutQueueEntry in interface hypercast.I_LRUObject

toString

public java.lang.String toString()
Creates a string with information about the binding object.

Overrides:
toString in class java.lang.Object

toByteArray

public byte[] toByteArray(java.security.Signature signer,
                          java.security.PrivateKey privateKey)
Serializes and signs a binding.

Parameters:
signer - Security object used to create the signature of the binding
privateKey - The private key needed to verify the signature of this binding.

restoreInvalidateNamingBindings

public static hypercast.NamingBinding[] restoreInvalidateNamingBindings(byte[] data,
                                                                        int offset)
Creates invalidation naming binding object given an array of one or more serialized bindingss.


restoreNamingBindings

public static hypercast.NamingBinding[] restoreNamingBindings(byte[] data,
                                                              int offset)
Creates naming binding object given an array of one or more serialized bindingss.


restoreNamingBindings

public static hypercast.NamingBinding[] restoreNamingBindings(byte[] data,
                                                              int index,
                                                              boolean makeInvalidate)
Given an array of serialized binding objects, parses array and instanciates objects.


bindingsToByteArray

public static byte[] bindingsToByteArray(hypercast.NamingBinding[] bindings,
                                         java.security.Signature signer,
                                         hypercast.CertificateCache certificateCache)
Concatenates byte representations of all bindings into single byte array. For each binding, there may or may not be a certificate. For each binding with a corresponding certificate there may or may not be a private key.

See Also:
Note: this method could be very inefficient regarding the handling of byte arrays. Instead of making a small byte array for each binding and then allocating a large array that holds all of the smaller array (with a copy for each of the smaller arrays), perhaps a large array could be created at the beginning of the method (the size of this array would be a guess). Each particular binding would be packed into the large array as long as there is room to do so. The large array would be expanded as needed. The "toByteArray" method of NamingBinding would take two extra params: the large array and an offset into the large array. The final valid byte of the large array would have to be communicated back to the caller.