4.6 Restricting Signal Capabilities
In order to make the use of signal event objects more secure, subscribers to a signal event should not normally be able to generate signal event notifications. For example, it would be undesirable if application code could `fake' a reactor shutdown by calling the signal or signalFinalize methods on the signal event object obtained via the getReactorShutdownSignal method. This is addressed by the presence of the makeRestricted method on the signal event object, which returns a restricted capability reference. Any attempt to call the signal or signalFinalize methods on a restricted capability reference will then result in a RestrictedCapabilityException being thrown.
Since the restricted and full capability signal references are distinct objects, it is not safe to use the object identity test (==) to check equivalence between them. However, the Object.equals and Object.hashCode methods are fully implemented - so that different references to the same signal event objects are considered to be equivalent for all other comparison tests. Note that the signal event handle passed back to signalable callback handlers as the first parameter in the onSignal method will always be a restricted capability reference.
It is generally good practice to restrict the capability of signal event objects which are returned over a publisher interface, such as the one described in Listing 4.7. This ensures that the only entity which can generate notifications for those signal event objects is the publisher itself. Listing 4.10 demonstrates the way in which this may be achieved for the publisher / subscriber example previously presented in Section 4.4.