planet.commonapi
Class Id

java.lang.Object
  planet.commonapi.Id

All Implemented Interfaces:

java.lang.Comparable, java.io.Serializable

Direct Known Subclasses:

ChordId, SymphonyId

public abstract class Id

extends java.lang.Object

implements java.lang.Comparable, java.io.Serializable

This interface is an abstraction of an Id (or key) from the CommonAPI paper.

Any class that extends this Id for a specific overlay, must offer as least the no argument constructor.

The value for any built Id will be made with the related setValues() method. If any of them is nonapplicable to any Id implementation, an InitializationException must be thrown.

Author:

Carles Pairot, Ruben Mondejar, Jordi Pujol

See Also:

InitializationException, Serialized Form

Constructor Summary

Id()

Method Summary

abstract Id	add(Id offset) Returns an Id corresponding to this Id plus a given distance
abstract boolean	between(Id ccw, Id cw) Checks if this Id is between two given ids ccw (inclusive) and cw (exclusive) on the circle
boolean	betweenE(Id init, Id end) Checks if this Id is in interval (init,end]
abstract boolean	clockwise(Id nid) Checks to see if the Id nid is clockwise or counterclockwise from this, on the ring.
static Id	divide(int numberOfNodes) Divides the maximum domain of the node Id in numberOfNodes, to offers the offset between two consecutive nodes.
abstract Id	divideOn(int divisor) This method returns the arithmetical result of this division: thisId/divisor
boolean	Ebetween(Id init, Id end) Checks if this Id is in interval [init,end)
static Id	getMaximum() This method returns the maximum value for an Id that is possible to build.
abstract java.lang.Object	getValue() Returns the internal representation value of this Id.
void	setValue(Id newValue) Sets the new value with Id newValue.
abstract void	setValue(java.lang.Object newValue) Sets the new value to this Id with newValue
abstract Id	setValues(java.math.BigInteger newValue) Sets the new value for this Id, based on a BigInteger value.
abstract Id	setValues(byte[] newValue) Sets the new value for this Id, based on a byte[] value.
abstract Id	setValues(double newValue) Sets the new value for this Id, based on a double value.
abstract Id	setValues(int newValue) Sets the new value for this Id, based on an integer value.
abstract Id	setValues(int[] newValue) Sets the new value for this Id, based on an int[] value.
abstract Id	setValues(java.util.Random valueGenerator) Sets the new value for this Id, based on a randomly generated value.
abstract Id	setValues(java.lang.String newValue) Sets the new value for this Id, based on a String value.
Id	setValues(java.lang.String material, java.lang.String algorithm) Sets the new value for this Id, based on a hashed value.
abstract Id	shift(int cnt, int fill) Shift operator. shift(-1,0) multiplies value of this by two, shift(1,0) divides by 2
abstract Id	subtract(Id offset) Returns an Id corresponding to this Id minus a given distance
abstract byte[]	toByteArray() Returns a (mutable) byte array representing this Id
abstract java.lang.String	toStringFull() Returns a string representing the full length of this Id.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Comparable

compareTo

Constructor Detail

Id

public Id()

Method Detail

between

public abstract boolean between(Id ccw,
                                Id cw)

Checks if this Id is between two given ids ccw (inclusive) and cw (exclusive) on the circle

Parameters:

ccw - the counterclockwise id

cw - the clockwise id

Returns:

true if this is between ccw (inclusive) and cw (exclusive), false otherwise

Ebetween

public boolean Ebetween(Id init,
                        Id end)

Checks if this Id is in interval [init,end)

Parameters:

init - Id that open the interval

Returns:

end Id that close the interval

betweenE

public boolean betweenE(Id init,
                        Id end)

Checks if this Id is in interval (init,end]

Parameters:

init - Id that open the interval

Returns:

end Id that close the interval

clockwise

public abstract boolean clockwise(Id nid)

Checks to see if the Id nid is clockwise or counterclockwise from this, on the ring. An Id is clockwise if it is within the half circle clockwise from this on the ring. An Id is considered counter-clockwise from itself.

Parameters:

nid - The id to compare to

Returns:

true if clockwise, false otherwise.

add

public abstract Id add(Id offset)

Returns an Id corresponding to this Id plus a given distance

Parameters:

offset - the distance to add

Returns:

the new Id

subtract

public abstract Id subtract(Id offset)

Returns an Id corresponding to this Id minus a given distance

Parameters:

offset - the distance to subtract

Returns:

the new Id

shift

public abstract Id shift(int cnt,
                         int fill)

Shift operator. shift(-1,0) multiplies value of this by two, shift(1,0) divides by 2

Parameters:

cnt - the number of bits to shift, negative shifts left, positive shifts right

fill - value of bit shifted in (0 if fill == 0, 1 otherwise)

Returns:

this

toByteArray

public abstract byte[] toByteArray()

Returns a (mutable) byte array representing this Id

Returns:

A byte[] representing this Id

toStringFull

public abstract java.lang.String toStringFull()

Returns a string representing the full length of this Id.

Returns:

A string with all of this Id

setValue

public void setValue(Id newValue)

Sets the new value with Id newValue.

This invokes:
setValue(newValue.getValue());

Parameters:

newValue - Id with the new value.

See Also:

setValue(planet.commonapi.Id)

setValue

public abstract void setValue(java.lang.Object newValue)

Sets the new value to this Id with newValue

Parameters:

newValue - Internal representation with the new value to set to this Id.

getValue

public abstract java.lang.Object getValue()

Returns the internal representation value of this Id.

Returns:

The internal representatio value of this Id.

getMaximum

public static Id getMaximum()

This method returns the maximum value for an Id that is possible to build. Must to be reimplemented for any specific overlay Id. We recommend to use the singleton design pattern.

Returns:

The maximum value sets to an Id. In this case, always null.

divide

public static Id divide(int numberOfNodes)

Divides the maximum domain of the node Id in numberOfNodes, to offers the offset between two consecutive nodes.

If the domain is [MIN..MAX], the aritmethical operation will be as follows:
(MAX-MIN)/numberOfNodes

Parameters:

numberOfNodes - Number of nodes in the network.

Returns:

The offset between two consecutive nodes, to get a network with equidistance nodes. This static implementation always return null. The expected value must be the same type as on the Id.setValue(Object) method.

divideOn

public abstract Id divideOn(int divisor)

This method returns the arithmetical result of this division:
thisId/divisor

Parameters:

divisor - The number of parts to divide this Id.

Returns:

The result of division.

setValues

public abstract Id setValues(int newValue)

Sets the new value for this Id, based on an integer value. If this type of internal value is non applicable for the related implementation, we recommend throws a NoSuchMethodError error.

Parameters:

newValue - The new value.

Returns:

The Id itself

setValues

public abstract Id setValues(double newValue)

Sets the new value for this Id, based on a double value. If this type of internal value is non applicable for the related implementation, we recommend throws a NoSuchMethodError error.

Parameters:

newValue - The new value.

Returns:

The Id itself

setValues

public abstract Id setValues(byte[] newValue)

Sets the new value for this Id, based on a byte[] value. It is also used by the setValues(String, String) method. If this type of internal value is non applicable for the related implementation, we recommend throws a NoSuchMethodError error.

Parameters:

newValue - The new value.

Returns:

The Id itself

See Also:

setValues(String, String)

setValues

public abstract Id setValues(int[] newValue)

Sets the new value for this Id, based on an int[] value. If this type of internal value is non applicable for the related implementation, we recommend throws a NoSuchMethodError error.

Parameters:

newValue - The new value.

Returns:

The Id itself

setValues

public abstract Id setValues(java.lang.String newValue)

Sets the new value for this Id, based on a String value. Is a string representation of any required number. If this type of internal value is non applicable for the related implementation, we recommend throws a NoSuchMethodError error.

Parameters:

newValue - The new value.

Returns:

The Id itself

setValues

public abstract Id setValues(java.math.BigInteger newValue)

Sets the new value for this Id, based on a BigInteger value. If this type of internal value is non applicable for the related implementation, we recommend throws a NoSuchMethodError error.

Parameters:

newValue - The new value.

Returns:

The Id itself

setValues

public abstract Id setValues(java.util.Random valueGenerator)

Sets the new value for this Id, based on a randomly generated value. If this type of internal value is non applicable for the related implementation, we recommend throws a NoSuchMethodError error.

Parameters:

valueGenerator - The new value.

Returns:

The Id itself

setValues

public Id setValues(java.lang.String material,
                    java.lang.String algorithm)
             throws InitializationException

Sets the new value for this Id, based on a hashed value. Finally, it uses the setValues(byte[]) to set the correct value. If this type of internal value is non applicable for the related implementation, we recommend throws a NoSuchMethodError error.

Parameters:

material - The input for the algorithm.

algorithm - One-way hashing algorithm such as "SHA" or "MD5".

Returns:

The Id itself

Throws:

InitializationException - if the material is null or the algorithm is not found.

See Also:

setValues(byte[])