|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--hypercast.Naming
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 |
public static final byte MESSAGE_TYPE_SET_NAME
public static final byte MESSAGE_TYPE_SET_CERT
public static final byte MESSAGE_TYPE_UNSET_NAME
public static final byte MESSAGE_TYPE_UNSET_CERT
public static final byte MESSAGE_TYPE_NAME_QUERY
public static final byte MESSAGE_TYPE_LOCAL_NAME_QUERY
public static final byte MESSAGE_TYPE_LOGICAL_ADDRESS_QUERY
public static final byte MESSAGE_TYPE_INSTALL_CERT
public static final byte MESSAGE_TYPE_PUSH
public static final byte MESSAGE_TYPE_INVALIDATE
public static final byte MESSAGE_TYPE_SET_NAME_DELEGATE
public static final byte MESSAGE_TYPE_SET_CERT_DELEGATE
public static final byte MESSAGE_TYPE_LA_CHANGE
public static final int WAIT_INDEFINITELY
public static final int NO_RESPONSE_LIMIT
public static final short USE_CONFIGURED_QUERY_RADIUS
Constructor Detail |
public Naming(hypercast.OL_Socket socket)
socket
- the overlay socket that this naming object will be associated with.
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 |
public void setName(java.lang.String name)
name
- The name that will be associated with the local socket
HyperCastWarningRuntimeException
- if the parameter name
is null
public void setName(java.lang.String name, hypercast.I_LogicalAddress logicalAddress)
public void setName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey)
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
.public void setName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey, java.lang.String name, hypercast.I_LogicalAddress logicalAddress)
public void unsetName(java.lang.String name)
public void unsetName(java.security.cert.Certificate certificate, java.security.PrivateKey privateKey)
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
.public void installTrustedNamingCertificate(java.security.cert.Certificate certificate)
certificate
- The certificate of the trust anchorpublic java.lang.String[] getNames()
null
.public java.lang.String[] getNames(hypercast.I_LogicalAddress peer)
getNames(I_LogicalAddress, boolean, long, boolean, boolean, int, int, short, short)
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.
peer
- The logical address for which a name lookup is being performedrequireTrusted
- If true only trusted bindings will be acceptedtimeout
- 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 acceptedmaxAge
- 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.
getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)
public int getNamesNonBlocking(hypercast.I_LogicalAddress peer)
getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)
public int getNamesNonBlocking(hypercast.I_LogicalAddress peer, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
peer
- The logical address for which a name lookup is being performedrequireTrusted
- If true only trusted bindings will be acceptedtimeout
- 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 acceptedmaxAge
- 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.
public hypercast.I_LogicalAddress[] getLogicalAddressByName(java.lang.String name)
getLogicalAddressByName(String, boolean, long, boolean, boolean, int, int, short, short)
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)
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.
name
- The logical address for which a name lookup is being performed.requireTrusted
- If true only trusted bindings will be acceptedtimeout
- 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 acceptedmaxAge
- 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.
getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)
public int getLogicalAddressByNameNonBlocking(java.lang.String name)
getLogicalAddressByNameNonBlocking(String, boolean, long, boolean, boolean, int, int, short, short)
public int getLogicalAddressByNameNonBlocking(java.lang.String name, boolean requireTrusted, long timeout, boolean requireSerialNumberMatch, boolean requireAuthoritative, int maxAge, int maxResponses, short minHopCount, short maxHopCount)
name
- The name for which a logical address lookup is being performedrequireTrusted
- If true only trusted bindings will be acceptedtimeout
- 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 acceptedmaxAge
- 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.
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.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |