[Rails-devel] Item names for game engine, UI and debugging

[Stefan F. <ste...@we...>]

For Rails2.0 I have introduced both conventions for
A) names to identify items (for the game engine)
B) names of items for the UI (for the user)
C) names of items for debugging

In some cases they coincide (e.g. companies), in many cases they
differ.

The chosen methods are:
A) Game engine names

String getId() (method of Item interface)
Unique identifier for a given parent

String getURI() (method of Item interface)
Unique identifier in the context

String getFullURI() (method of Item interface)
Unique identifier in the game engine

Examples for getId() are:
Certificates: cert_0, cert_1
Trains: 3_0, 3_1, 3_2, 3_3

Examples for getURI() are:
Certificates: Public/B&O/cert_0
Trains: 3_0

Examples for getFullURI() are:
Certificates: /CompanyManager/Public/B&O/cert_0
Trains: /TrainManager/3_0


B) UI names
String toText() (new method of Item interface)

toText() is already the method that Models use to communicate to the
observer in  the UI.
So I extend this to non-Model items, that toText() generates the String 
used to display for the User.

The default (defined e.g. in AbstractItem, RailsItem etc.) is that 
toText() links to getId().


C) Debugging information
String toString() method

The default is ClassName followed by FullURI (for states) or URI (for items)

Examples:
Train{URI=3_0}
PublicCompany{URI=Public/B&O}
BooleanState{FullURI=/CompanyManager/Public/NYC/closed}

One could (rightly) wonder why not choose toString() instead of toText() 
for the UI names?

The reason is that I reserve toString() for debug information.

There are two reasons for it:
ii) (Main) I want refactor support for calls to toText().
toString() is often implicitly called by omitting toString() in string 
concatenation.
String s = "Train:" + train;
instead of
String s = "Train:" + train.toText();

i) The new logger (sl4j) supports a resource-friendly mechanism to use

log.debug("Bought new train {}", train);
which automatically calls train.toString() if log is enabled, but does 
not call any method if log is turned off.