The term servant activation refers to making the presence of a servant for a particular Ice object known to the Ice run time. Activating a servant adds an entry to the Active Servant Map (ASM). Another way of looking at servant activation is to think of it as creating a link between the identity of an Ice object and the corresponding programming-language servant that handles requests for that Ice object. Once the Ice run time has knowledge of this link, it can dispatch incoming requests to the correct servant. Without this link, that is, without a corresponding entry in the ASM, an incoming request for the identity results in an
ObjectNotExistException. While a servant is activated, it is said to incarnate the corresponding Ice object.
The inverse operation is known as servant deactivation. Deactivating a servant removes an entry for a particular identity from the ASM. Thereafter, incoming requests for that identity are no longer dispatched to the servant and result in an
The object adapter offers a number of operations for managing servant activation and deactivation:
The operations behave as follows:
addoperation adds a servant with the given identity to the ASM. Requests are dispatched to that servant as soon as
addis called. The return value is the proxy for the Ice object incarnated by that servant. The proxy embeds the identity passed to
You cannot call
addwith the same identity more than once: attempts to add an already existing identity to the ASM result in an
AlreadyRegisteredException. (It does not make sense to add two servants with the same identity because that would make it ambiguous as to which servant should handle incoming requests for that identity.)
Note that it is possible to activate the same servant multiple times with different identities. In that case, the same single servant incarnates multiple Ice objects. We explore the ramifications of this in more detail in our discussion of server implementation techniques.
addWithUUIDoperation behaves the same way as the
addoperation but does not require you to supply an identity for the servant. Instead,
addWithUUIDgenerates a UUID as the identity for the corresponding Ice object. You can retrieve the generated identity by calling the
ice_getIdentityoperation on the returned proxy.
addWithUUIDis useful to create identities for temporary objects, such as short-lived session objects. (You can also use
addWithUUIDfor persistent objects that do not have a natural identity, as we have done for the file system application.)
removeoperation breaks the association between an identity and its servant by removing the corresponding entry from the ASM; it returns a reference to the removed servant.
Once the servant is deactivated, new incoming requests for the removed identity cause the client to receive an
ObjectNotExistException. Requests that are executing inside the servant at the time
removeis called are allowed to complete normally. Once the last request for the servant is complete, the object adapter drops its reference (or smart pointer, for C++) to the servant. At that point, the servant becomes available for garbage collection (or is destroyed, for C++), provided there are no other references or smart pointers to the servant. The net effect is that a deactivated servant is destroyed once it becomes idle.
Deactivating an object adapter implicitly calls
removeon its active servants.
findoperation performs a lookup in the ASM and returns the servant for the specified object identity. If no servant with that identity is registered, the operation returns null. Note that
finddoes not consult any servant locators or default servants.
findByProxyoperation performs a lookup in the ASM and returns the servant with the object identity and facet that are embedded in the proxy. If no such servant is registered, the operation returns null. Note that
findByProxydoes not consult any servant locators or default servants.