mil.navy.nps.dis
Class EntityID

java.lang.Object
  mil.navy.nps.dis.PduElement
      mil.navy.nps.dis.EntityID

All Implemented Interfaces:

java.lang.Cloneable, SerializationInterface

public class EntityID

extends PduElement

Record uniquely identifying an entity.

Version:

1.0

Author:

Don McGregor (http://www.npsnet.org/~mcgredo)

Location:

Web: http://www.web3d.org/WorkingGroups/vrtp/mil/navy/nps/dis/EntityID.java

or locally: ~/mil/navy/nps/dis/EntityID.java

Hierarchy Diagram:

Summary:

Each Entity in a given exercise executing on a DIS application shall be assigned an Entity Identifier Record Unique to the exercise.

Explanation:

EntityID is a composite of several values that are commonly found together, and that,when combined, uniquely identify an entity in a simulation. It's used in a variety of PDUs, typically to identify a receving and a sending entity. Since it uniquely identifies an entity in a virtual world, it's a good candidate to act as a hash table key.

Note:

Note that I've "flattened" the Simulation Address Record, so that you instead of the simulation address record , you will find the Site ID and the Application ID. This is a questionnable move.

History:

15Nov96 /Don McGregor /New

10Mar97 /Don McGregor /cleaned up for javadoc

16Apr97 /Don McGregor /PrintStream passed to printValues

12Aug97 /DonB /elaborated printValues

8Dec97 /Ronan Fauglas /changes for documentation templates + complements in documentation

11Dec97 /Ronan Fauglas /changes access methods names from "variable()" to "getVariable()"

References:

DIS Data Dictionary :Entity Identifier Record

DIS specification : IEEE 1278.1, 5.3.14

See Also:

ProtocolDataUnit, PduElement, SerializationInterface

Field Summary

protected UnsignedShort	applicationID Application at that site this came from.
protected UnsignedShort	entityID Entity within the current application.
static int	SHORT_HIGH_BYTE_MASK
static int	SHORT_LOW_BYTE_MASK
protected UnsignedShort	siteID Site the entity came from.

Constructor Summary

EntityID()
Default constructor--fills with zeros for all values.

EntityID(int pSiteID, int pApplicationID, int pEntityID)
Constructs a new Entity Identifier, with variables values passed in parameters.

EntityID(short pSiteID, short pApplicationID, short pEntityID)
Constructs a new Entity Identifier, with variables values passed in parameters.

Method Summary

java.lang.Object	clone() Makes deep copies of all the instance variables, so we don't have two objects pointing to the same data.
void	deSerialize(java.io.DataInputStream inputStream) Deserialize our data from the input stream.
boolean	equals(java.lang.Object obj) Makes a "numeric equality" test.
UnsignedShort	getApplicationID()
UnsignedShort	getEntityID()
UnsignedShort	getSiteID()
int	hashCode() This provides a hash code for the object.
int	length() Returns the length of the object when serialized in a stream.
void	printValues(int indentLevel, java.io.PrintStream printStream) Prints the generated serialized object for debugging.
void	serialize(java.io.DataOutputStream outputStream) Serialize our data out to the stream.
void	setApplicationID(int pApplicationID)
void	setApplicationID(UnsignedShort pApplicationID)
void	setEntityID(int pEntityID)
void	setEntityID(UnsignedShort pEntityID)
void	setSiteID(int pSiteID)
void	setSiteID(UnsignedShort pSiteID)
java.lang.String	toString()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

SHORT_HIGH_BYTE_MASK

public static final int SHORT_HIGH_BYTE_MASK

See Also:

Constant Field Values

SHORT_LOW_BYTE_MASK

public static final int SHORT_LOW_BYTE_MASK

See Also:

Constant Field Values

siteID

protected UnsignedShort siteID

Site the entity came from. Each DIS Site has a unique Identifier. 0, 2^16-1 and 2^16-2 are reserved.

Value:

No site shall be assigned an ID containin all zero's, (2e16-1) or (2e16-2). The mechanism by which Site IDs are assigned is outside the scope of this standard. The simulation manager shall use the reserved site IDs to identify receivers of Simulation Management PDUs. A site ID equal to zero shall mean no site; this may be used to annotate a PDU log. A site ID equal to all ones (2e16-1) shall mean all sites; this may be used to start all sites. An application ID equal to (2e16-2) shall have no meaning but is reserved for consistency.

References:

DIS Data Dictionary: Site Identifier Field

DIS specification : IEEE 1278.1, 5.3.14.1.1

applicationID

protected UnsignedShort applicationID

Application at that site this came from. Each DIS application has a unique Identifier on a given site. 0, 2^16-1 and 2^16-2 are reserved.

Value:

No simulation application shall be assigned an id containin all zeros, (2e16-1), or (2e16-2). One or more simulation applications may reside in a single host computer. The mechanism by which application IDs are assigned is outside the scope of this standard. The simulation manager shall use the reserved application IDs to identify receivers of Simulation Management PDUs. An application ID equal to zero shall mean no application (NO_APPLIC). An application ID equal to all ones (2e16-1) shall mean all applications (ALL_APPLIC); this may be used to start all applications within a site. An application ID equal to (2e16-2) shall have no meaning but is reserved for consistency.

References:

DIS Data Dictionary: Application Identifier Field

DIS specification : IEEE 1278.1, 5.3.14.1.2

entityID

protected UnsignedShort entityID

Entity within the current application. Each Entity has a unique Identifier on a given site. 0, 2^16-1 and 2^16-2 are reserved.

Value:

This identifier is valid for the duration of the exercise; however, entity IDs shall be reused when all possible entity IDs have been exhausted. No entity shall have an ID of zero, (2e16 -1) or (2e16-2) (which is NO_ENTITY, ALL_ENTITIES or RQSRT_ASSIGN_ID). This number need not be registered or retained for future exercises.

References:

DIS Data Dictionary: Entity Identity Field

DIS specification : IEEE 1278.1, 5.3.14.2

Constructor Detail

EntityID

public EntityID()

Default constructor--fills with zeros for all values.

EntityID

public EntityID(short pSiteID,
                short pApplicationID,
                short pEntityID)

Constructs a new Entity Identifier, with variables values passed in parameters.

Parameters:

pSiteID - the Site Identifier

pApplicationID - the Application Identifier for that site

pEntityID - the Entity identifier for that application

EntityID

public EntityID(int pSiteID,
                int pApplicationID,
                int pEntityID)

Constructs a new Entity Identifier, with variables values passed in parameters. This is a convienence method for when you've got integers and don't want to convert to shorts, or if you have unsigned shorts that are greater than a signed short.

Parameters:

pSiteID - the Site Identifier

pApplicationID - the Application Identifier for that site

pEntityID - the Entity identifier for that application

Method Detail

clone

public java.lang.Object clone()

Description copied from class: PduElement

Makes deep copies of all the instance variables, so we don't have two objects pointing to the same data. The accessor methods make copies of the objects, rather than returning the objects themselves. The runtime provides the right object type with the call to super.clone(), and we cast it to our type. Subclasses should do the same thing, and all these ivars will be taken care of automatically.

Overrides:

clone in class PduElement

Returns:

a clone of this instance

See Also:

Object

serialize

public void serialize(java.io.DataOutputStream outputStream)

Description copied from class: PduElement

Serialize our data out to the stream. Subclasses of us should call super.Serialize() to make sure the superclasse's data is serialized out. The order in which instance variables are serialized is significant. They must be serialized in the same order they appear in the DIS spec. Prints out some information during execution if debugging flag is set.

Specified by:

serialize in interface SerializationInterface

Specified by:

serialize in class PduElement

Parameters:

outputStream - the stream to which this object is serialized

deSerialize

public void deSerialize(java.io.DataInputStream inputStream)

Description copied from class: PduElement

Deserialize our data from the input stream. Subclasses of us should call super.deSerialize to make sure the superclass's data are properly affected. The order in which instance variables are serialized is significant. They must be deSerialized in the same order as they have been serialized as specified by the DIS spec.

Specified by:

deSerialize in interface SerializationInterface

Specified by:

deSerialize in class PduElement

Parameters:

inputStream - the stream from which this object is initialized

length

public int length()

Description copied from class: PduElement

Returns the length of the object when serialized in a stream.

Specified by:

length in class PduElement

Returns:

the length of the object when serialized in a stream

printValues

public void printValues(int indentLevel,
                        java.io.PrintStream printStream)

Description copied from class: PduElement

Prints the generated serialized object for debugging.

Specified by:

printValues in class PduElement

Parameters:

indentLevel - number of spaces to indent for visibility

toString

public java.lang.String toString()

hashCode

public int hashCode()

This provides a hash code for the object. A Hash code is a handy way to uniquely identify entities.

• The problem:
  There's a problem with the core API, since there are 48 bits of information in the object, but the hash code has only 32 bits to put things in. So we have to hash on some subset of the data available.
• The solution:
  The solution right now is to ignore the application ID when generating the hash code. Furthermore, the entity ID is in the upper 16 bits, while the site ID is in the lower 16 bits. The idea is that this will help spread out the hash code a bit more, since there are probably many more entities than sites, and putting the part with more information in the MSB helps spread things out. This helps prevent collisions, which improves performance.

Returns:

a hash code value for this object

equals

public boolean equals(java.lang.Object obj)

Makes a "numeric equality" test.

Parameters:

obj - the object want to be compared with this object.

Returns:

yes if the object in parameter is of the same type and if the numerical values of both objects are equal.

getSiteID

public UnsignedShort getSiteID()

setSiteID

public void setSiteID(UnsignedShort pSiteID)

setSiteID

public void setSiteID(int pSiteID)

getApplicationID

public UnsignedShort getApplicationID()

setApplicationID

public void setApplicationID(UnsignedShort pApplicationID)

setApplicationID

public void setApplicationID(int pApplicationID)

getEntityID

public UnsignedShort getEntityID()

setEntityID

public void setEntityID(UnsignedShort pEntityID)

setEntityID

public void setEntityID(int pEntityID)