planet.commonapi.factory
Interface IdFactory

All Superinterfaces:
java.io.Serializable
All Known Implementing Classes:
IdFactoryImpl

public interface IdFactory
extends java.io.Serializable

This interface provides methods with a way of generating Ids.

Author:
Jordi Pujol

Method Summary
 java.util.Iterator buildDistributedIds(long desiredNetworkSize)
          The Iterator instance returned permits to build as maximum desiredNetworkSize.
 Id buildId()
          Builds an Id with the actual configuration of network topology and size.
 Id buildId(java.math.BigInteger material)
          Generate an Id from a BigInteger, that includes its internal value.
 Id buildId(byte[] material)
          Builds a protocol-specific Id given the source data.
 Id buildId(double material)
          Builds a protocol-specific Id given the source data.
 Id buildId(int material)
          Builds a protocol-specific Id given the source data.
 Id buildId(int[] material)
          Builds a protocol-specific Id given the source data as int[].
 Id buildId(java.lang.String material)
          Generate an Id from the String as its internal value.
 Id buildId(java.lang.String material, java.lang.String algorithm)
          Builds a new Id from an arbitray string applying a one-way hashing algorithm, such as SHA-1 or MD5.
 Id buildKey(java.lang.String materialToHash)
          Builds a protocol-specific Id by using the given string as source data for a hash function (like SHA-1).
 Id buildRandomId()
          Builds an uniformly distributed random Id.
 

Method Detail

buildId

public Id buildId()
           throws InitializationException
Builds an Id with the actual configuration of network topology and size.

Returns:
A new Id generated with the actual configuration.
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.

buildId

public Id buildId(int material)
           throws InitializationException
Builds a protocol-specific Id given the source data.

Parameters:
material - The material to use as double value.
Returns:
A new Id with the double value as internal one.
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.

buildId

public Id buildId(double material)
           throws InitializationException
Builds a protocol-specific Id given the source data.

Parameters:
material - The material to use as double value.
Returns:
A new Id with the double value as internal one.
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.

buildId

public Id buildId(byte[] material)
           throws InitializationException
Builds a protocol-specific Id given the source data.

Parameters:
material - The material to use to build the new Id.
Returns:
A new Id with the byte[] value.
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.

buildId

public Id buildId(int[] material)
           throws InitializationException
Builds a protocol-specific Id given the source data as int[].

Parameters:
material - The internal representation value of the new Id as int[].
Returns:
A new Id with the int[] value.
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.

buildKey

public Id buildKey(java.lang.String materialToHash)
            throws InitializationException
Builds a protocol-specific Id by using the given string as source data for a hash function (like SHA-1). The returned hash value will be the internal value for the new Id.

Parameters:
materialToHash - The string to use as source data for a hash function.
Returns:
The built Id as result to apply a hash function to the given String.
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.

buildId

public Id buildId(java.lang.String material)
           throws InitializationException
Generate an Id from the String as its internal value.

Parameters:
material - With the String representation of the internal value.
Returns:
A new Id with the value included in the String.
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.

buildId

public Id buildId(java.math.BigInteger material)
           throws InitializationException
Generate an Id from a BigInteger, that includes its internal value.

Parameters:
material - BigInteger with the internal value for the new Id.
Returns:
A new Id with the value included in the BigInteger.
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.

buildId

public Id buildId(java.lang.String material,
                  java.lang.String algorithm)
           throws InitializationException
Builds a new Id from an arbitray string applying a one-way hashing algorithm, such as SHA-1 or MD5.

Parameters:
material - An arbitray string.
algorithm - One-way hashing algorithm such as "SHA" or "MD5".
Throws:
InitializationException - when an error occurs during the initialization of the Id or when this factory method is nonapplicable.
See Also:
Java Cryptography Architecture API Specification & Reference

buildRandomId

public Id buildRandomId()
                 throws InitializationException
Builds an uniformly distributed random Id.

Returns:
A new Id built randomly
Throws:
InitializationException - if an error occurs during the initialization of the Id.

buildDistributedIds

public java.util.Iterator buildDistributedIds(long desiredNetworkSize)
                                       throws InitializationException
The Iterator instance returned permits to build as maximum desiredNetworkSize. This method goal is to obtain desiredNetworkSize equidistant Ids for a network.

Parameters:
desiredNetworkSize - Number of nodes Id to obtain.
Returns:
An Iterator instance for getting all desiredNetworkSize. null if desiredNetworkSize is zero.
Throws:
InitializationException - if any error has ocurred during the initialization.