Ice.ObjectAdapter

final class Ice.ObjectAdapter(impl: ObjectAdapter)

Bases: object

An object adapter is the main server-side Ice API. It has two main purposes: - accept incoming connections from clients and dispatch requests received over these connections (see

activate()); and

An object adapter can dispatch “bidirectional requests”–requests it receives over an outgoing connection instead of a more common incoming connection. It can also dispatch collocated requests (with no connection at all).

Parameters:

impl (IcePy.ObjectAdapter)

getName() → str

Gets the name of this object adapter.

Returns:

This object adapter’s name.

Return type:

str

getCommunicator() → Communicator

Gets the communicator that created this object adapter.

Returns:

This object adapter’s communicator.

Return type:

Communicator

activate() → None

Starts receiving and dispatching requests received over incoming connections.

Notes

When this object adapter is an indirect object adapter configured with a locator proxy, this function also registers the object adapter’s published endpoints with this locator.

Return type:

None

hold() → None

Stops reading requests from incoming connections. Outstanding dispatches are not affected. The object adapter can be reactivated with activate().

Notes

This function is provided for backward compatibility with older versions of Ice. Don’t use it in new applications.

Return type:

None

waitForHold() → None

Waits until the object adapter is in the holding state (see hold()) and the dispatch of requests received over incoming connections has completed.

Notes

This function is provided for backward compatibility with older versions of Ice. Don’t use it in new applications.

Return type:

None

deactivate() → None

Deactivates this object adapter: stops accepting new connections from clients and closes gracefully all incoming connections created by this object adapter once all outstanding dispatches have completed. If this object adapter is indirect, this function also unregisters the object adapter from the locator (see activate()).

This function does not cancel outstanding dispatches: it lets them execute until completion. A deactivated object adapter cannot be reactivated again; it can only be destroyed.

Return type:

None

waitForDeactivate() → None

Waits until deactivate() is called on this object adapter and all connections accepted by this object adapter are closed. A connection is closed only after all outstanding dispatches on this connection have completed.

Return type:

None

isDeactivated() → bool

Checks whether or not deactivate() was called on this object adapter.

Returns:

True if deactivate() has been called on this object adapter, False otherwise.

Return type:

bool

destroy() → None

Destroys this object adapter and cleans up all resources associated with it. Once this function has returned, you can recreate another object adapter with the same name.

Return type:

None

add(servant: Object, id: Identity) → ObjectPrx

Adds a servant to this object adapter’s Active Servant Map (ASM). The ASM is a map {identity, facet} -> servant.

Notes

This function is equivalent to calling addFacet() with an empty facet.

Parameters:

  • servant (Object) – The servant to add.

  • id (Identity) – The identity of the Ice object that is implemented by the servant.

Returns:

A proxy for id, created by this object adapter.

Return type:

ObjectPrx

Raises:

AlreadyRegisteredException – If a servant with the same identity is already registered.

addFacet(servant: Object, id: Identity, facet: str = '') → ObjectPrx

Adds a servant to this object adapter’s Active Servant Map (ASM), while specifying a facet. The ASM is a map {identity, facet} -> servant.

Parameters:

  • servant (Object) – The servant to add.

  • id (Identity) – The identity of the Ice object that is implemented by the servant.

  • facet (str, optional) – The facet of the Ice object that is implemented by the servant.

Returns:

A proxy for id and facet, created by this object adapter.

Return type:

ObjectPrx

Raises:

AlreadyRegisteredException – If a servant with the same identity and facet is already registered.

addWithUUID(servant: Object) → ObjectPrx

Adds a servant to this object adapter’s Active Servant Map (ASM), using an automatically generated UUID as its identity.

Parameters:

servant (Object) – The servant to add.

Returns:

A proxy with the generated UUID identity created by this object adapter.

Return type:

ObjectPrx

addFacetWithUUID(servant: Object, facet: str) → ObjectPrx

Adds a servant to this object adapter’s Active Servant Map (ASM), using an automatically generated UUID as its identity. Also specifies a facet.

Parameters:

  • servant (Object) – The servant to add.

  • facet (str) – The facet of the Ice object that is implemented by the servant.

Returns:

A proxy with the generated UUID identity and the specified facet.

Return type:

ObjectPrx

addDefaultServant(servant: Object, category: str) → None

Adds a default servant to handle requests for a specific category. When an object adapter dispatches an incoming request, it tries to find a servant for the identity and facet carried by the request in the following order:

  • The object adapter tries to find a servant for the identity and facet in the Active Servant Map.

  • If this fails, the object adapter tries to find a default servant for the category component of the identity.

  • If this fails, the object adapter tries to find a default servant for the empty category, regardless of the category contained in the identity.

  • If this fails, the object adapter tries to find a servant locator for the category component of the identity. If there is no such servant locator, the object adapter tries to find a servant locator for the empty category. - If a servant locator is found, the object adapter tries to find a servant using this servant locator.

  • If all the previous steps fail, the object adapter gives up and the caller receives an ObjectNotExistException or a FacetNotExistException.

Parameters:

  • servant (Object) – The default servant to add.

  • category (str) – The category for which the default servant is registered. The empty category means it handles all categories.

Raises:

AlreadyRegisteredException – If a default servant with the same category is already registered.

Return type:

None

remove(id: Identity) → Object

Removes a servant from the object adapter’s Active Servant Map.

Parameters:

id (Identity) – The identity of the Ice object that is implemented by the servant.

Returns:

The removed servant.

Return type:

Object

Raises:

NotRegisteredException – If no servant with the given identity is registered.

removeFacet(id: Identity, facet: str) → Object

Removes a servant from the object adapter’s Active Servant Map, while specifying a facet.

Parameters:

  • id (Identity) – The identity of the Ice object that is implemented by the servant.

  • facet (str) – The facet. An empty facet means the default facet.

Returns:

The removed servant.

Return type:

Object

Raises:

NotRegisteredException – If no servant with the given identity and facet is registered.

removeAllFacets(id: Identity) → dict[str, Object]

Removes all facets with the given identity from the Active Servant Map. This function completely removes the Ice object, including its default facet.

Parameters:

id (Identity) – The identity of the Ice object to be removed.

Returns:

A collection containing all the facet names and servants of the removed Ice object.

Return type:

dict[str, Object]

Raises:

NotRegisteredException – If no servant with the given identity is registered.

removeDefaultServant(category: str) → Object

Removes the default servant for a specific category.

Parameters:

category (str) – The category of the default servant to remove.

Returns:

The default servant.

Return type:

Object

Raises:

NotRegisteredException – If no default servant is registered for the given category.

find(id: Identity) → Object | None

Looks up a servant.

Notes

This function only tries to find the servant in the ASM and among the default servants. It does not attempt to locate a servant using servant locators.

Parameters:

id (Identity) – The identity of an Ice object.

Returns:

The servant that implements the Ice object with the given identity, or None if no such servant has been found.

Return type:

Object | None

findFacet(id: Identity, facet: str) → Object | None

Looks up a servant with an identity and facet.

Notes

This function only tries to find the servant in the ASM and among the default servants. It does not attempt to locate a servant using servant locators.

Parameters:

  • id (Identity) – The identity of an Ice object.

  • facet (str) – The facet of an Ice object. An empty facet means the default facet.

Returns:

The servant that implements the Ice object with the given identity and facet, or None if no such servant has been found.

Return type:

Object | None

findAllFacets(id: Identity) → dict[str, Object]

Finds all facets for a given identity in the Active Servant Map.

Parameters:

id (Identity) – The identity.

Returns:

A collection containing all the facet names and servants that have been found. Can be empty.

Return type:

dict[str, Object]

findByProxy(proxy: ObjectPrx) → Object | None

Looks up a servant with an identity and a facet. It’s equivalent to calling findFacet().

Notes

This function only tries to find the servant in the ASM and among the default servants. It does not attempt to locate a servant using servant locators.

Parameters:

proxy (ObjectPrx) – The proxy that provides the identity and facet to search.

Returns:

The servant that matches the identity and facet carried by proxy, or None if no such servant has been found.

Return type:

Object | None

addServantLocator(locator: ServantLocator, category: str) → None

Adds a ServantLocator to this object adapter for a specific category.

Parameters:

  • locator (ServantLocator) – The servant locator to add.

  • category (str) – The category. The empty category means the locator handles all categories.

Raises:

AlreadyRegisteredException – If a servant locator with the same category is already registered.

Return type:

None

removeServantLocator(category: str) → ServantLocator

Removes a ServantLocator from this object adapter.

Parameters:

category (str) – The category.

Returns:

The servant locator.

Return type:

ServantLocator

Raises:

NotRegisteredException – If no servant locator with the given category is registered.

findServantLocator(category: str) → ServantLocator | None

Finds a ServantLocator registered with this object adapter.

Parameters:

category (str) – The category.

Returns:

The servant locator, or None if not found.

Return type:

ServantLocator | None

findDefaultServant(category: str) → Object | None

Finds the default servant for a specific category.

Parameters:

category (str) – The category.

Returns:

The default servant, or None if not found.

Return type:

Object | None

createProxy(id: Identity) → ObjectPrx

Creates a proxy from an Ice identity. If this object adapter is configured with an adapter ID, the proxy is an indirect proxy that refers to this adapter ID. If a replica group ID is also defined, the proxy is an indirect proxy that refers to this replica group ID. Otherwise, the proxy is a direct proxy containing this object adapter’s published endpoints.

Parameters:

id (Identity) – An Ice identity.

Returns:

A proxy with the given identity.

Return type:

ObjectPrx

createDirectProxy(id: Identity) → ObjectPrx

Creates a direct proxy from an Ice identity.

Parameters:

id (Identity) – An Ice identity.

Returns:

A proxy with the given identity and the published endpoints of this object adapter.

Return type:

ObjectPrx

createIndirectProxy(id: Identity) → ObjectPrx

Creates an indirect proxy for an Ice identity.

Parameters:

id (Identity) – An Ice identity.

Returns:

An indirect proxy with the given identity. If this object adapter is not configured with an adapter ID or a replica group ID, the new proxy is a well-known proxy (i.e., an identity-only proxy).

Return type:

ObjectPrx

setLocator(locator: LocatorPrx) → None

Sets an Ice locator on this object adapter.

Parameters:

locator (LocatorPrx) – The locator used by this object adapter.

Return type:

None

getLocator() → LocatorPrx | None

Gets the Ice locator used by this object adapter.

Returns:

The locator used by this object adapter, or None if no locator is used by this object adapter.

Return type:

LocatorPrx | None

getEndpoints() → tuple[Endpoint, ...]

Gets the set of endpoints configured on this object adapter.

Notes

This function remains usable after the object adapter has been deactivated.

Returns:

The set of endpoints.

Return type:

tuple[Ice.Endpoint, …]

getPublishedEndpoints() → tuple[Endpoint, ...]

Gets the set of endpoints that proxies created by this object adapter will contain.

Notes

This function remains usable after the object adapter has been deactivated.

Returns:

The set of published endpoints.

Return type:

tuple[Ice.Endpoint, …]

setPublishedEndpoints(newEndpoints: tuple[Endpoint, ...] | list[Endpoint]) → None

Sets the endpoints that proxies created by this object adapter will contain.

Parameters:

newEndpoints (tuple[Ice.Endpoint, ...] | list[Ice.Endpoint]) – The new set of endpoints that the object adapter will embed in proxies.

Raises:

RuntimeError – If newEndpoints is empty or if this adapter is associated with a router.

Return type:

None