dd.api
Class DDLocateMsg

java.lang.Object
  |
  +--dd.api.DDLocateMsg
All Implemented Interfaces:
QueueElementIF, QuickSerializable
Direct Known Subclasses:
HelloWorldLocateMsg, HelloWorldLocateMsg, HelloWorldLocateMsg, RepairDHTTest.LocateLocalMsg, RepairDirectoryTest.LocateMsg, RequestDisseminationSetMsg, RMLocateMsg, TestLocateMsg, TriggerTester.LocateMsg

public abstract class DDLocateMsg
extends Object
implements QueueElementIF, QuickSerializable

Messages sent from one machine to one or more machines advertising the given objguid and satisfying the given tag query.

The intended functionality of this event (outgoing) is as follows. The message is routed toward the given guid in the network, and at each hop the query is applied to any object pointers associated with the given objguid, along with the current query_state. The query should return a result, and possibly modify the query_state as well. The result can be one of DDQueryResultMatch or DDQueryResultNoMatch. A matching result indicates which object pointers to follow, as well as whether or not to continue routing up the tree towards the root. A non-matching result causes the query to continue towards the root without following any object pointers.

If the DDLocateMsg makes it way all the way to the root without getting a positive query result, a DDLocateFailure is returned to the original DDLocateMsg requestor.

Version:
$Id: DDLocateMsg.java,v 1.4 2004/05/06 18:10:12 hweather Exp $
Author:
Sean C. Rhea
See Also:
DDLocateFailure

Field Summary
 boolean forward
          If true, DD will forward the DDLocateMsg to any ptr location where the query result is a match.
 SecureHash guid
          The queried objguid.
 int hopCount
          Number of hops taken by the message on its way to the application.
 SecureHash id
          A unique ID for this message, in order that a DDLocateFailure can be matched to the location request; set to null if you do not want failure notification.
 boolean inbound
          Whether this message is being received (true) or sent (false).
static byte INTERMEDIATE_NONE
          The underlying DHT will send the message directly to the root and will not consider intermiate nodes and ptrs.
static byte INTERMEDIATE_PTRS_CACHE_ONLY
          Similar to INTERMEDIATE_UPCALL_ONLY except that intermediate ptrs will be considered in addition to root ptrs.
static byte INTERMEDIATE_PTRS_DISK
          Similar to INTERMEDIATE_PTRS_CACHE_ONLY except that intermediate ptrs stored on disk will be used.
static String[] INTERMEDIATE_STRING
          String representation of intermediate_upcall_policy.
static byte INTERMEDIATE_UPCALL_ONLY
          The underlying DHT will generate an upcall event to the DD on each intermediate node in the path.
 byte intermediate_upcall_policy
          Either the underlying DHT will send the message directly to the root and will not consider intermiate nodes and ptrs or the underlying DHT will generate an upcall event to the DD on each intermediate node in the path potentially considering intermediate ptrs as well.
 boolean one_hop
          One hop is a (possible) optimization.
 SecureHash peer
          If inbound, the sender; undefined otherwise.
 DDQuery query
          The DDQuery.query(ostore.util.SecureHash, bamboo.vivaldi.VirtualCoordinate, ostore.util.SecureHash, dd.host.api.HostInfo, dd.api.DDTag, dd.api.DDQueryState) to execute on each object pointer.
 DDQueryState query_state
          The state to pass the DDQuery.query(ostore.util.SecureHash, bamboo.vivaldi.VirtualCoordinate, ostore.util.SecureHash, dd.host.api.HostInfo, dd.api.DDTag, dd.api.DDQueryState) executed on each object pointer.
 boolean recursive_route
          If true recursive route between src and root; otherwise, iterative route.
 int TTL
          Number of hops this message should take before delivering payload.
 bamboo.vivaldi.VirtualCoordinate vc
          The VirtualCoordinate to use when resolving ptr locations.
static byte VC_NONE
          Do not use any VirtualCoordinate when resolving ptr locations.
 byte vc_policy
          The VirtualCoordinate to use when resolving ptr locations.
static byte VC_ROOT
          Use root VirtualCoordinate when resolving ptr locations.
static byte VC_SRC
          Use src VirtualCoordinate when resolving ptr locations.
static String[] VC_STRING
          String representation of vc_policy.
static byte VC_SUPPLIED
          Use the supplied VirtualCoordinate when resolving ptr locations.
 
Constructor Summary
DDLocateMsg()
          Empty constructor.
DDLocateMsg(SecureHash guid, DDQuery query, DDQueryState query_state, SecureHash id, boolean forward, boolean recursive_route, boolean one_hop, byte intermediate_upcall_policy, byte vc_policy, bamboo.vivaldi.VirtualCoordinate vc)
          Constructor: Creates a new DDLocateMsg.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface ostore.util.QuickSerializable
serialize
 

Field Detail

INTERMEDIATE_NONE

public static final byte INTERMEDIATE_NONE
The underlying DHT will send the message directly to the root and will not consider intermiate nodes and ptrs. By not using intermediate upcalls the values for hopCount and TTL will be undefined and intermediate ptrs will not be considered.

See Also:
Constant Field Values

INTERMEDIATE_UPCALL_ONLY

public static final byte INTERMEDIATE_UPCALL_ONLY
The underlying DHT will generate an upcall event to the DD on each intermediate node in the path. Upcalls are necessary for hopCount and TTL to be accounted for correctly. But intermediate ptrs will not be considered, only root ptrs will be used.

See Also:
Constant Field Values

INTERMEDIATE_PTRS_CACHE_ONLY

public static final byte INTERMEDIATE_PTRS_CACHE_ONLY
Similar to INTERMEDIATE_UPCALL_ONLY except that intermediate ptrs will be considered in addition to root ptrs. But only intermediate ptrs that are immediately available in cache will be used; that is, the disk is not used for intermediate ptrs.

See Also:
Constant Field Values

INTERMEDIATE_PTRS_DISK

public static final byte INTERMEDIATE_PTRS_DISK
Similar to INTERMEDIATE_PTRS_CACHE_ONLY except that intermediate ptrs stored on disk will be used.

See Also:
Constant Field Values

INTERMEDIATE_STRING

public static final String[] INTERMEDIATE_STRING
String representation of intermediate_upcall_policy.


VC_NONE

public static final byte VC_NONE
Do not use any VirtualCoordinate when resolving ptr locations.

See Also:
Constant Field Values

VC_SRC

public static final byte VC_SRC
Use src VirtualCoordinate when resolving ptr locations.

See Also:
Constant Field Values

VC_ROOT

public static final byte VC_ROOT
Use root VirtualCoordinate when resolving ptr locations.

See Also:
Constant Field Values

VC_SUPPLIED

public static final byte VC_SUPPLIED
Use the supplied VirtualCoordinate when resolving ptr locations.

See Also:
Constant Field Values

VC_STRING

public static final String[] VC_STRING
String representation of vc_policy.


peer

public SecureHash peer
If inbound, the sender; undefined otherwise.


inbound

public boolean inbound
Whether this message is being received (true) or sent (false).


guid

public SecureHash guid
The queried objguid.


query

public DDQuery query
The DDQuery.query(ostore.util.SecureHash, bamboo.vivaldi.VirtualCoordinate, ostore.util.SecureHash, dd.host.api.HostInfo, dd.api.DDTag, dd.api.DDQueryState) to execute on each object pointer. See the class comments, above.


query_state

public DDQueryState query_state
The state to pass the DDQuery.query(ostore.util.SecureHash, bamboo.vivaldi.VirtualCoordinate, ostore.util.SecureHash, dd.host.api.HostInfo, dd.api.DDTag, dd.api.DDQueryState) executed on each object pointer. See the class comments, above.


forward

public boolean forward
If true, DD will forward the DDLocateMsg to any ptr location where the query result is a match. Otherwise, DDLocateMsg will be returned back to the original sender when either the query result match states to DDQueryResultMatch.stop() or the DDLocateMsg reaches the root with and DDQueryResultMatch.stop()==false. Note that when forward==true any recipient of the DDLocateMsg will not receive the state, but when forward==false the original sender will receive the state.


recursive_route

public boolean recursive_route
If true recursive route between src and root; otherwise, iterative route. Recursive route means that each node in the path forwards the message to the next node. The recursive route continues until the message reaches the root. Whereas, iterative route means each node in the path sends back to the source the next node and the source itself sends the message to the next node. The iterative route continues until the message reaches the root. In either case, when the message reaches the root, the root will forward the message to matching ptr locations.


one_hop

public boolean one_hop
One hop is a (possible) optimization. Since the DD maintains a host db, it is possible to look up the root entry in the the db. If a root exists, then forward the message directly to the root in one hop. Note one_hop=T and an entry exists, intermediate nodes will not be used.


intermediate_upcall_policy

public byte intermediate_upcall_policy
Either the underlying DHT will send the message directly to the root and will not consider intermiate nodes and ptrs or the underlying DHT will generate an upcall event to the DD on each intermediate node in the path potentially considering intermediate ptrs as well. The options are:


vc_policy

public byte vc_policy
The VirtualCoordinate to use when resolving ptr locations. Valid setting are: VC_NONE, VC_SRC, VC_ROOT, or VC_SUPPLIED. The vc parameter is ignored and set to the specified policy; unless, VC_SUPPLIED is the policy (in that case the vc parameter is used to resolve ptr locations.


vc

public bamboo.vivaldi.VirtualCoordinate vc
The VirtualCoordinate to use when resolving ptr locations. This parameter is only used when the vc_policy=VC_SUPPLIED; otherwise, vc parameter is ignored.


hopCount

public int hopCount
Number of hops taken by the message on its way to the application.


TTL

public int TTL
Number of hops this message should take before delivering payload.


id

public SecureHash id
A unique ID for this message, in order that a DDLocateFailure can be matched to the location request; set to null if you do not want failure notification.

Constructor Detail

DDLocateMsg

public DDLocateMsg(SecureHash guid,
                   DDQuery query,
                   DDQueryState query_state,
                   SecureHash id,
                   boolean forward,
                   boolean recursive_route,
                   boolean one_hop,
                   byte intermediate_upcall_policy,
                   byte vc_policy,
                   bamboo.vivaldi.VirtualCoordinate vc)
Constructor: Creates a new DDLocateMsg. Construct with the given guid, query, and state; will return a DDLocateFailure with the same id if the location fails. Set id to null if a failure response is not needed. Use for new outbound messages.

An example parameter setting for sending a message to the closest replica or service to the src:

For finding the closest replica or service to the src (without sending the replica or service a message):

Another example parameter setting for sending a message to the closest m-of-n replica or service instances where m is greater than the number that is likely to be found on intermediate nodes. That is, just route directly to the root as quickly as possible.

Again for finding the closest m-of-n replica or service instances:

Parameters:
guid - Object guid attempt to resolve.
query - DDQuery.query(ostore.util.SecureHash, bamboo.vivaldi.VirtualCoordinate, ostore.util.SecureHash, dd.host.api.HostInfo, dd.api.DDTag, dd.api.DDQueryState) to execute on each object PublishInfo.
query_state - The state to pass the DDQuery.query(ostore.util.SecureHash, bamboo.vivaldi.VirtualCoordinate, ostore.util.SecureHash, dd.host.api.HostInfo, dd.api.DDTag, dd.api.DDQueryState) executed on each object pointer.
id - A unique ID for this message, in order that a DDLocateFailure can be matched to the location request; set to null if you do not want failure notification.
forward - If true, DD will forward the DDLocateMsg to any ptr location where the query result is a match. Otherwise, DDLocateMsg will be returned back to the original sender when either the query result match states to DDQueryResultMatch.stop() or the DDLocateMsg reaches the root with and DDQueryResultMatch.stop()==false.
recursive_route - If true recursive route between src and root; otherwise, iterative route. See recursive_route for more details.
one_hop - One hop is a (possible) optimization. Since the DD maintains a host db, it is possible to look up the root entry in the the db. If a root exists, then forward the message directly to the root in one hop. Note one_hop=T and an entry exists, intermediate nodes will not be used.
intermediate_upcall_policy - Either the underlying DHT will send the message directly to the root and will not consider intermiate nodes and ptrs or the underlying DHT will generate an upcall event to the DD on each intermediate node in the path potentially considering intermediate ptrs as well. See intermediate_upcall_policy for more details.
vc_policy - The VirtualCoordinate to use when resolving ptr locations. Valid setting are: VC_NONE, VC_SRC, VC_ROOT, or VC_SUPPLIED.
vc - This parameter is only used when the vc_policy=VC_SUPPLIED; otherwise, vc parameter is ignored.

DDLocateMsg

public DDLocateMsg()
Empty constructor. For use by derived types when reconstructing themselves from a byte array.