This is unfortunate, because there are lots of reasons you might want to know. For example, you might want to command any train that reaches a particular red signal to stop. But you can't do that unless you know which train it is that is reaching the signal.
JMRI provides experimental tools for tracking trains as them move around on the layout.
At first the sensor for Block A is showing active. As the train moves into Block B, the Sensor for B will go active. When the train has completely left A, it's sensor will go inactive etc.
Although a particular Block only knows whether it's active or not (occupied or not), by also looking at the occupancy of the adjacent Blocks it can tell more. In the example above, if the code knew that train 321 was in Block A, when Block B goes active, the program can infer that 321 is now also in Block B.
This doesn't always work, unfortunately. Imagine the case above, where there is both a train in Block A and also a train in Block C. When Block B goes from inactive to active (unoccupied to occupied), which train moved in? The one from A, or the one from C?
Some of this ambiguity can be removed by careful arrangement of the detection Blocks, by accepting limitations on how trains can run (or how short Blocks have to be), and by using more intelligent logic that thinks about the direction and priority of trains. But it's clear that even straight track poses some problems.
Turnouts add an additional layer of complexity. Imagine a train is sitting in the Block next to the normal (closed) route, and another is sitting in the reversed (thrown) route. When the occupancy Sensor for the Turnout goes active, which Train has entered the Turnout track? That depends on which way the Turnout is set, so the program needs to be able to consider that information too.
Note that this is test code, and not all features are completely present. For example, you cannot store Block objects in a Configuration file; they must be manually created in your scripts. This limitations will be removed with time.
The direction of a Block is set from the direction of the incoming train. When a train is found to be coming in on a particular Path, that Path's getFromBlockDirection becomes the direction of the train in this Block.
Issues:
Do not assume that only one Block object uniquely represents a piece of track. To allow independent development, it must be possible for multiple Block objects to take care of a particular section of track.