The org.jboss.remoting.ident.Identity is one of the main components remoting uses during discovery to identify remoting server instances (is actually the way it guarantees uniqueness). So, if have two remoting servers running on the same server, they can be uniquely identified. The reason the identity is persisted (currently only able to do this to the file system) is so if a server crashes and then restarts, can identify it when it restarts as the one that crashed (instead of being a completely new instance that is being started). This may be important from a monitoring point as would want to know that the crashed server is back online.
As for how/where the identity is persisted, is all contained within org.jboss.remoting.ident.Identity.createId().
I noticed that there isn't anything covering idenity in the remoting docs anymore (guess was left out at some point, but am not sure why). So if there are any particular changes that need to be made or specifics you would like to see covered in the doc, please let me know.
However, would like to mention that there are some discussions of moving detection functionality out of remoting all together and putting into a separate project. See following for more details:
I'm not sure I need alot of docs on this. But it would be helpful to know that
a) your app must have write permissions to the file system so it can persist the jboss.identity file (since there is no way to tell it to NOT write that file - which is something I think should be changed - not crazy about always requiring the remoting infrastructure to write a file to the file system. This is a minor issue, though).
b) how can I tell the remoting infrastructure where to write that file (document the system properties that define this behavior). This is especially helpful for people to know when they are not deploying in JBossAS (and thus no default /data directory is defined)