hypercast
Class Naming

java.lang.Object
  |
  +--hypercast.Naming

public class Naming
extends java.lang.Object

This class implements the APIs of the naming service. Logically, this code is part of the OL_Socket. This class implements a proxy, used by instances of OL_Socket, for the naming APIs. This is done to reduce the complexity (i.e. bloat) of the OL_Socket code.

This class implements the API side of the naming service. The other side of the naming service is the Naming FSM in the Message Store.

As per the HyperCast system design, there are no "conventional" API calls that can be made to the Message Store. Rather, the interface that is exported by the Message Store consists of passing a message to the message store (input) and receiving a message from the message store (output). The system is designed in this way because the Message Store is designed to interact with other Message Stores, not the application/programmer.

The Message Store handles two types of messages application and control. Application messages contain data that is being transmitted to and from applications. Control, or non-application payload, messages are internal to the Message Store, generated and consumed by communicating Message Stores. The Naming Service needs to be able to send and receive non-application payload information to and from the message store. All Naming Service messages are control messages.

To communicate beteen the Naming Service API and the Message Store a "dummy" message mechanism is used. In this scheme messages are sent from a socket to its own Message Store. These messages are not designed to travel "on-the-wire" (implemented by setting the hop limit field to zero). These dummy message are formatted as application payload messages at the socket/API level. Application payload messages are used because control messages cannot be created at the API level. When the dummy message with application payload formatting are received by the Message Store Naming Service FSM, they are reformatted as control messages.

The idiom that is used to send dummy messages to the message store is:

 // Inject the dummy message into the message store. Ignore
 // the return value because this isn't the forwarding engine.

 (void) messageStore.receiveMessage (message);
 
The (void) syntax preceeding the method invocation is not valid Java code; it is an idiom borrowed from the C programming language that means "ignore the return value." Results from the Message Store are received via the asynchonous notificate system of HyperCast rather than by the method call return mechanism. Naming Service API calls pass information to the Message Store via the dummy message mechanism causing the Naming Service FSM to do work on behalf of the API (create a binding, perform a query, etc.). When the Naming Service FSM is finished with the work it notifies the application via an asynchonous message.


Field Summary
static byte MESSAGE_TYPE_INSTALL_CERT
           
static byte MESSAGE_TYPE_INVALIDATE
           
static byte MESSAGE_TYPE_LA_CHANGE
           
static byte MESSAGE_TYPE_LOCAL_NAME_QUERY
           
static byte MESSAGE_TYPE_LOGICAL_ADDRESS_QUERY
           
static byte MESSAGE_TYPE_NAME_QUERY
           
static byte MESSAGE_TYPE_PUSH
           
static byte MESSAGE_TYPE_SET_CERT
           
static byte MESSAGE_TYPE_SET_CERT_DELEGATE
           
static byte MESSAGE_TYPE_SET_NAME
           
static byte MESSAGE_TYPE_SET_NAME_DELEGATE
           
static byte MESSAGE_TYPE_UNSET_CERT
           
static byte MESSAGE_TYPE_UNSET_NAME
           
static int NO_RESPONSE_LIMIT
          Constant used with query APIs to denote that an unlimited number of responses will be allowed.
static short USE_CONFIGURED_QUERY_RADIUS
          Used in a dummy message to signal that the configured query radius should not be overridden.
static int WAIT_INDEFINITELY
          Constant used with query APIs to denote that an unlimited amount of time will be spent waiting for a query response.
 
Constructor Summary
Naming(hypercast.OL_Socket socket)
          Constructs a naming object and associates it with the specified socket.
 
Method Summary
 hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name)
           
 hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Calls getLogicalAddressByNameNonBlocking() to inject a dummy message into the message store to query the logical address of the name; blocks waiting for a response to the query.
 int getLogicalAddressByNameNonBlocking(java.lang.String name)
           
 int getLogicalAddressByNameNonBlocking(java.lang.String name, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Performs a query on the given name to get the logical addresses of the sockets having that name.
 java.lang.String[] getNames()
          Returns the names that are associated with this socket.
 java.lang.String[] getNames(hypercast.I_LogicalAddress peer)
           
 java.lang.String[] getNames(hypercast.I_LogicalAddress peer, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Calls getNamesNonBlocking() to inject a dummy message into the message store to query the names of the given logical address; blocks waiting for responses to the query.
 int getNamesNonBlocking(hypercast.I_LogicalAddress peer)
           
 int getNamesNonBlocking(hypercast.I_LogicalAddress peer, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
          Performs a query on the given logical address to get the names of the socket having that logical address.
 void installTrustedNamingCertificate(java.security.cert.Certificate certificate)
          Installs a certificate as a trust anchor.
 void LAChange()
          Called by OL_Socket.namingLogicalAddressChange().
 void setName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey)
          Associates the common name of the subject of the certificate with the local socket.
 void setName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey, java.lang.String name, hypercast.I_LogicalAddress logicalAddress)
           
 void setName(java.lang.String name)
          Associates a name with the local socket.
 void setName(java.lang.String name, hypercast.I_LogicalAddress logicalAddress)
           
 void unsetName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey)
          Disassociates the common name of the subject of the certificate from the local socket.
 void unsetName(java.lang.String name)
          Disassociates a name with this socket.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MESSAGE_TYPE_SET_NAME

public static final byte MESSAGE_TYPE_SET_NAME
See Also:
Constant Field Values

MESSAGE_TYPE_SET_CERT

public static final byte MESSAGE_TYPE_SET_CERT
See Also:
Constant Field Values

MESSAGE_TYPE_UNSET_NAME

public static final byte MESSAGE_TYPE_UNSET_NAME
See Also:
Constant Field Values

MESSAGE_TYPE_UNSET_CERT

public static final byte MESSAGE_TYPE_UNSET_CERT
See Also:
Constant Field Values

MESSAGE_TYPE_NAME_QUERY

public static final byte MESSAGE_TYPE_NAME_QUERY
See Also:
Constant Field Values

MESSAGE_TYPE_LOCAL_NAME_QUERY

public static final byte MESSAGE_TYPE_LOCAL_NAME_QUERY
See Also:
Constant Field Values

MESSAGE_TYPE_LOGICAL_ADDRESS_QUERY

public static final byte MESSAGE_TYPE_LOGICAL_ADDRESS_QUERY
See Also:
Constant Field Values

MESSAGE_TYPE_INSTALL_CERT

public static final byte MESSAGE_TYPE_INSTALL_CERT
See Also:
Constant Field Values

MESSAGE_TYPE_PUSH

public static final byte MESSAGE_TYPE_PUSH
See Also:
Constant Field Values

MESSAGE_TYPE_INVALIDATE

public static final byte MESSAGE_TYPE_INVALIDATE
See Also:
Constant Field Values

MESSAGE_TYPE_SET_NAME_DELEGATE

public static final byte MESSAGE_TYPE_SET_NAME_DELEGATE
See Also:
Constant Field Values

MESSAGE_TYPE_SET_CERT_DELEGATE

public static final byte MESSAGE_TYPE_SET_CERT_DELEGATE
See Also:
Constant Field Values

MESSAGE_TYPE_LA_CHANGE

public static final byte MESSAGE_TYPE_LA_CHANGE
See Also:
Constant Field Values

WAIT_INDEFINITELY

public static final int WAIT_INDEFINITELY
Constant used with query APIs to denote that an unlimited amount of time will be spent waiting for a query response.

See Also:
Constant Field Values

NO_RESPONSE_LIMIT

public static final int NO_RESPONSE_LIMIT
Constant used with query APIs to denote that an unlimited number of responses will be allowed.

See Also:
Constant Field Values

USE_CONFIGURED_QUERY_RADIUS

public static final short USE_CONFIGURED_QUERY_RADIUS
Used in a dummy message to signal that the configured query radius should not be overridden.

See Also:
Constant Field Values
Constructor Detail

Naming

public Naming(hypercast.OL_Socket socket)
Constructs a naming object and associates it with the specified socket. Each socket may be associated with a single naming object; each naming object must be associated with a socket.

Parameters:
socket - the overlay socket that this naming object will be associated with.
Throws:
HyperCastFatalRuntimeException - if the socket argument is null or it does not have a message store.
HyperCastConfigException - if the socket does not have a message store.
Method Detail

setName

public void setName(java.lang.String name)
Associates a name with the local socket.

Parameters:
name - The name that will be associated with the local socket
Throws:
HyperCastWarningRuntimeException - if the parameter name is null

setName

public void setName(java.lang.String name,
                    hypercast.I_LogicalAddress logicalAddress)

setName

public void setName(java.security.cert.Certificate certificate,
                    java.security.PrivateKey privateKey)
Associates the common name of the subject of the certificate with the local socket. The private key allows the Naming Service FSM in the Message Store to add digitial signatures to the Naming Bindings that it generates for this name.

Parameters:
certificate - The common name of the subject of this certificate will be associated to this socket.
privateKey - This private key, that matches the public key in certificate will be used to digitally sign bindings corresponding to the common name of the subject contained in certificate.

setName

public void setName(java.security.cert.Certificate certificate,
                    java.security.PrivateKey privateKey,
                    java.lang.String name,
                    hypercast.I_LogicalAddress logicalAddress)

unsetName

public void unsetName(java.lang.String name)
Disassociates a name with this socket. If the name was associated using a certificate and a private key, this operation will not succeed.


unsetName

public void unsetName(java.security.cert.Certificate certificate,
                      java.security.PrivateKey privateKey)
Disassociates the common name of the subject of the certificate from the local socket. The private key matches the public key of the certificate.

Parameters:
certificate - The common name of the subject of this certificate will be disassociated from this socket.
privateKey - This private key, that matches the public key in certificate.

installTrustedNamingCertificate

public void installTrustedNamingCertificate(java.security.cert.Certificate certificate)
Installs a certificate as a trust anchor. When a certificate chain is being built it need only reach a trust anchor to be trusted.

Parameters:
certificate - The certificate of the trust anchor

getNames

public java.lang.String[] getNames()
Returns the names that are associated with this socket.

Returns:
The names associated with this overlay socket. This method never returns null.

getNames

public java.lang.String[] getNames(hypercast.I_LogicalAddress peer)
See Also:
getNames(I_LogicalAddress, boolean, long, boolean, boolean, int, int, short, short)

getNames

public java.lang.String[] getNames(hypercast.I_LogicalAddress peer,
                                   boolean requireTrusted,
                                   long timeout,
                                   boolean requireSerialNumberMatch,
                                   boolean requireAuthoritative,
                                   int maxAge,
                                   int maxResponses,
                                   short minHopCount,
                                   short maxHopCount)

Calls getNamesNonBlocking() to inject a dummy message into the message store to query the names of the given logical address; blocks waiting for responses to the query.

Parameters:
peer - The logical address for which a name lookup is being performed
requireTrusted - If true only trusted bindings will be accepted
timeout - Time in milliseconds before this query will be ended. Can be Naming.WAIT_INDEFINITELY.
requireSerialNumberMatch - Each query has a unique serial number assigned to it. If this parameter is true then the serial number of a valid response must match the serial number of a query.
requireAuthoritative - If true only bindings received from the authoritative peer will be accepted
maxAge - The maximum age in milliseconds of an acceptable query. Calculated from the time of the query for already cached bindings; calculated from time of receipt for bindings received after the query is made.
maxResponses - The query will end when this number of responses are received. Can be Naming.NO_RESPONSE_LIMIT.
minHopCount - The minimum number of hops that a query must make before it is not propagated further.
Returns:
An array of the names associated with the given logical address.
See Also:
getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)

getNamesNonBlocking

public int getNamesNonBlocking(hypercast.I_LogicalAddress peer)
See Also:
getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)

getNamesNonBlocking

public int getNamesNonBlocking(hypercast.I_LogicalAddress peer,
                               boolean requireTrusted,
                               long timeout,
                               boolean requireSerialNumberMatch,
                               boolean requireAuthoritative,
                               int maxAge,
                               int maxResponses,
                               short minHopCount,
                               short maxHopCount)
Performs a query on the given logical address to get the names of the socket having that logical address.

Parameters:
peer - The logical address for which a name lookup is being performed
requireTrusted - If true only trusted bindings will be accepted
timeout - Time in milliseconds before this query will be ended. Can be Naming.WAIT_INDEFINITELY.
requireSerialNumberMatch - Each query has a unique serial number assigned to it. If this parameter is true then the serial number of a valid response must match the serial number of a query.
requireAuthoritative - If true only bindings received from the authoritative peer will be accepted
maxAge - The maximum age in milliseconds of an acceptable query. Calculated from the time of the query for already cached bindings; calculated from time of receipt for bindings received after the query is made.
maxResponses - The query will end when this number of responses are received. Can be Naming.NO_RESPONSE_LIMIT.
minHopCount - The minimum number of hops that a query must make before it is not propagated further.
Returns:
serial number of query

getLogicalAddressByName

public hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name)
See Also:
getLogicalAddressByName(String, boolean, long, boolean, boolean, int, int, short, short)

getLogicalAddressByName

public hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name,
                                                            boolean requireTrusted,
                                                            long timeout,
                                                            boolean requireSerialNumberMatch,
                                                            boolean requireAuthoritative,
                                                            int maxAge,
                                                            int maxResponses,
                                                            short minHopCount,
                                                            short maxHopCount)
Calls getLogicalAddressByNameNonBlocking() to inject a dummy message into the message store to query the logical address of the name; blocks waiting for a response to the query.

Parameters:
name - The logical address for which a name lookup is being performed.
requireTrusted - If true only trusted bindings will be accepted
timeout - Time in milliseconds before this query will be ended. Can be Naming.WAIT_INDEFINITELY.
requireSerialNumberMatch - Each query has a unique serial number assigned to it. If this parameter is true then the serial number of a valid response must match the serial number of a query.
requireAuthoritative - If true only bindings received from the authoritative peer will be accepted
maxAge - The maximum age in milliseconds of an acceptable query. Calculated from the time of the query for already cached bindings; calculated from time of receipt for bindings received after the query is made.
maxResponses - The query will end when this number of responses are received. Can be Naming.NO_RESPONSE_LIMIT.
minHopCount - The minimum number of hops that a query must make before it is not propagated further.
maxHopCount - The maximum number of hops that a query can make before it is not propagated further.
Returns:
A array of the logical addresses associated with the given name.
See Also:
getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)

getLogicalAddressByNameNonBlocking

public int getLogicalAddressByNameNonBlocking(java.lang.String name)
See Also:
getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)

getLogicalAddressByNameNonBlocking

public int getLogicalAddressByNameNonBlocking(java.lang.String name,
                                              boolean requireTrusted,
                                              long timeout,
                                              boolean requireSerialNumberMatch,
                                              boolean requireAuthoritative,
                                              int maxAge,
                                              int maxResponses,
                                              short minHopCount,
                                              short maxHopCount)
Performs a query on the given name to get the logical addresses of the sockets having that name.

Parameters:
name - The name for which a logical address lookup is being performed
requireTrusted - If true only trusted bindings will be accepted
timeout - Time in milliseconds before this query will be ended. Can be Naming.WAIT_INDEFINITELY.
requireSerialNumberMatch - Each query has a unique serial number assigned to it. If this parameter is true then the serial number of a valid response must match the serial number of a query.
requireAuthoritative - If true only bindings received from the authoritative peer will be accepted
maxAge - The maximum age in milliseconds of an acceptable query. Calculated from the time of the query for already cached bindings; calculated from time of receipt for bindings received after the query is made.
maxResponses - The query will end when this number of responses are received. Can be Naming.NO_RESPONSE_LIMIT.
minHopCount - The minimum number of hops that a query must make before it is not propagated further.
maxHopCount - The maximum number of hops that a query can make before it is not propagated further.
Returns:
serial number of query

LAChange

public void LAChange()

Called by OL_Socket.namingLogicalAddressChange(). The user must implement the necessary code to interact with the notification handler to check if the logical address changes, then call namingLogicalAddressChange() when the logical address changes. This method helps pass the LA change signal to the FSM.