COMP 310 Fall 2016	Lec40: Mixed Data  Dictionaries, WWJ Mapping Library and the map package

Final Project Issues:

• How restrictive is the API?    Does it rule out certain system architectures, e.g. only client-server topologies are allowed?    Remember, that this assignment is not at all about games but rather about enterprise communications architectures that are connecting arbitrary systems together, so is it reasonable to make such restrictions?
  • Focus on what the fundamental behaviors and data are needed for message-based communications across an enterprise, not on what is "easiest to code" or "makes it easy to create a particular type of system".    The communications subsystem is one of the most invariant parts of an enterprise system and what it is asked to do today may not look anything like what it will be asked to do tomorrow.   Don't base your decisions on whether or not you think that the implementation will be "too hard"--do  the right thing, not the easy thing.
• Can an externally-sourced command send a message to
  • The sender of the datapacket that it is processing?  ==> Does the command have access to the local entity that would be defined as the "sender" of the message?
  • The chatroom in which the user of the command is located?   ==> Does the command have access to an ability to send a message directly to the containing chatroom?   
    • If sending to the chatroom is done by relaying the message back through the original sender of the data packet being processed, what implications does this have about the commands that are being used on that machine vs. other machines?
  • Other chatrooms?  ==> Does the command have access to services that enable this type of communications?
    • Once again, if sending to the chatroom is done by relaying the message back through the original sender of the data packet being processed, what implications does this have about the commands that are being used on that machine vs. other machines?
  • Does the API encourage the respecting of the local system's encapsulation of its communications subsystem?
    • At the level of the internal workings of a command, what can be said about how messages are transported between computers, e.g. does the command actually know how messages are transported?   Should it know anything about the message transport mechanism? 
• In client-server or other game architectures where different machines are not equivalent, what are the implications about what commands are being used to process the same message on different machines?
  • Are different "rooms" on the same machine even required to process the same message identically?
• Is there a semantic difference between the process used to initially connect the game clients and game server together and initialize the game vs. the actual in-game processes and is the API able to clearly express the differences and similarities?
  • Note that semantic differences can be expressed at many levels, e.g. at the receiver level, at the method level, at the message level or some combination of these techniques.
• Does an externally-sourced command have/need access to local system information, e.g. the name of the local user, the name of the room/team, IP address, etc?
• Does the GUI interactions enable the added components to be labeled?   This makes it a lot easier for the GUI to make a sensible presentation of the custom components.
  • Try to make your system maximally respectful of  the local system's MVC separations, including notions that code running under the command's (usually RMI) threads are not directly working with GUI threading.    This can be accomplished by having the command create a "mini-mini-MVC" where the command's "view" is installed into the local system's GUI.

Mixed Data Dictionaries

The problem with dictionaries is that they are typed to fixed <key, value> types.   One can only put one type of object into a dictionary.    If one wants to put a variety of types of data into the same dictionary, e.g. for configuration information or other common data stores, the superclass of all possible held data types must be used to define the dictionary.    This causes two main problems with type-safety in the application:

1. The retrieved data must be downcast to be used because it comes out with a type that is too abstract to be useful.
2. The application must keep track of which keys are related to which types of data.    Nothing prevents incorrect casting at run-time.

What we'd really like a dictionary that enables us to store mixed types of data safely together.   The problem is that Java's type erasure causes the type information to be lost at runtime.   

The soluton is thus to encode the key with the type information of the data to which it refers.   Then, the dictionary can a) restrict any data being stored to only the type or subtype of that the key specifies and b) because of a), can unequivocally retrieve the data with the specific type as defined by the key being used.   

See the documentation for the mixedData package.

While a MixedDataKey is Serializable, it is often more practical to build the key when and where it is used by using the three values needed to specify the key instead of sending a serialized key instance.

Here's a breakdown of the information needed to generate a key. These three values completely and uniquely determine a key, that is, any MixedDataKey instance made with the same three values will be equal.

• UUID id = This value insures that the key will be unique from all other keys with the same two other values. In a typical scenario, all the keys in use share the same id value. For instance, a single randomly-generated UUID value could be used to uniquely identify the instance of the Game Server. The Game Server would then give that common UUID value to all commands it sends out so that they would be tied to that instance of the Game Server. 
• String desc = This is a "human-friendly" name that you can use to identify the particular value in the dictionary to which this key maps, e.g. "MapView adapter". This helps you keep track of what each key is for.  In practice, this is the main part of the key that one uses to differentiate one value from another in the dictionary.
• Class<?> type = The is the Java type of the value to which this key maps in the dictionary. Only values of this type can be associated with this key. While it is technically possible to use the same description above for different value types, it is not recommended because of the semantic confusion it would cause. Technically, this type specification duplicates the generic typing of the MixedDataKey itself but is needed in Java due to type erasure; in run-time generics languages such as C#, this parameter is not needed at all.

Type-erasure Problems when Storing Generic Types in a Mixed-Data Dictionary (MDD)

It turns out that saving generic types to the MDD is problematic due to Java's type-erasure (boo, hiss!).    

In particular, type erasure prevents on from getting the class object of a generic type, e.g. suppose one has a generic class, MyClass<T>, then Java won't let you get the class object for it, e.g. MyClass<SomeClass>.class will not compile.   This is because at run-time, only the raw MyClass exists, not the fully generic type.    Thus, we cannot make the MDD key that we want because the key requires the corresponding Class object for the data being stored.

The type-safe work-around is to create a custom, non-generic subclass for the desired type, e.g:

class MyCustomClass extends MyClass<SomeClass> {
}

Now, MyCustomClass.class is a perfectly valid operation and creates the Class object we want for the MDD key.

Notes:

• The irony is that we need the Class object at all is because of type-erasure!
• This issue would also come up when trying to make DataPackets of generic types.

WWJ Mapping Library

Please use a message-passing architecture for game server to game client communications -- one of the main points of the final project is to practice thinking in these terms.

Today we will discuss the new World Wind Java mapping library as well as any design issues that have come up over the break.   Here are some links to WWJ references and demos:

• Comp310 WWJ page
• WWJ library attachment instructions -- follow carefully!
• NASA WorldWind
  • World Wind Central
  • FAQ
  • Setup

A WWJ demo app is available: simply check out the following project:   https://svn.rice.edu/r/comp310/course/FinalProjec/FXX/WWJ_Demo   (FXX = F14 for Fall 2014, for example)

Word of advice:   Those who accomplish more, earlier, will have first dibs at suggesting and effecting common API changes that would naturally benefit their game the most!   Stragglers will be forced to modify their code to accomodate other people's desires.

map Package

The supplied map package provides some basic WWJ map capabilities such as

• Easy-to-use default annotation attributes
• Customizable right-click behavior for annotations
•  Simple map panel GUI component that shows the map that supports the adding and removing of map overlay layers.
• Map overlay layers onto which annotations can be placed.
• "Toggle Annotations" that will change their displayed text when clicked.
• A modified Position class that can have an altitude (hieght in the sky) different than its elevation (height of the ground at that point).

See the documentation for the map package.

© 2016 by Stephen Wong