Ice Docs

Object Adapter Properties

11 min read

12 min read

12 min read

2 min read

11 min read

11 min read

11 min read

11 min read

11 min read

These properties configure the runtime's Ice.Admin object adapter in MATLAB, PHP, and Ruby. Replace the adapter prefix with Ice.Admin, for example Ice.Admin.ThreadPool.Size=2.

adapter.AdapterId=id

Assigns an adapter ID to this object adapter. An object adapter with an adapter ID is called an indirect adapter.

This ID must be unique among all object adapters using the same locator instance. If a locator proxy is defined using adapter.Locator or Ice.Default.Locator, this object adapter registers its endpoints with the locator registry upon activation.

adapter.AllowedOrigins=originList

Restricts which HTTP Origin headers are accepted on the WebSocket upgrade request received by this object adapter. This property has effect only for adapters with WebSocket endpoints (ws or wss).

originList is a comma or whitespace-separated list of origins. Each entry has the form scheme://host[:port], where scheme is http or https and host is a DNS name or IP address. The scheme and host are compared case-insensitively; the default port for the scheme (80 for http, 443 for https) is omitted during comparison, so https://web.example.com and https://web.example.com:443 match the same origin.

The default value (empty) disables the check. A * entry also disables it, whatever the other entries are. Ice reads this property when creating an adapter with WebSocket endpoints.

When the check is enabled, Ice checks each incoming WebSocket upgrade request as follows:

If the request has no Origin header, the upgrade is accepted. Browsers always send Origin; non-browser Ice clients do not, so the check only filters browser-originated traffic. If the request has an Origin header that canonicalizes to an entry in the list, the upgrade is accepted. An unlisted or malformed origin causes Ice to reject the upgrade and close the connection.

This property is intended to mitigate cross-site WebSocket hijacking against browser-based Ice clients (Ice for JavaScript).

Properties
MyAdapter.Endpoints=wss -h api.example.com -p 443
MyAdapter.AllowedOrigins=https://web.example.com, https://admin.example.com

adapter.Connection.CloseTimeout=num (in seconds)

Overrides the setting of Ice.Connection.Server.CloseTimeout for this object adapter.

adapter.Connection.ConnectTimeout=num (in seconds)

Overrides the setting of Ice.Connection.Server.ConnectTimeout for this object adapter.

adapter.Connection.EnableIdleCheck=num

Overrides the setting of Ice.Connection.Server.EnableIdleCheck for this object adapter.

adapter.Connection.IdleTimeout=num (in seconds)

Overrides the setting of Ice.Connection.Server.IdleTimeout for this object adapter.

adapter.Connection.InactivityTimeout=num (in seconds)

Overrides the setting of Ice.Connection.Server.InactivityTimeout for this object adapter.

adapter.Connection.MaxDispatches=num

Overrides the setting of Ice.Connection.Server.MaxDispatches for this object adapter.

adapter.Endpoints=endpoints

Sets the physical endpoints of this object adapter. These endpoints correspond to the network interfaces on which the object adapter accepts connections and receives requests.

adapter.Locator=locator

Specifies the locator of this object adapter. The value is a stringified proxy to an Ice::Locator object.

As a proxy property, you can configure additional aspects of the proxy using properties.

adapter.MaxConnections=num

When num is greater than 0, Ice limits the number of incoming connections separately for each listening endpoint of this object adapter. Once an endpoint reaches the limit, Ice accepts and immediately closes additional connections to that endpoint until an existing connection closes. UDP endpoints are exempt from this limit.

The default value is 0. A value of 0 or less disables the limit.

adapter.MessageSizeMax=num (in KiB)

Limits the size of the Ice protocol messages this adapter receives, in KiB (1024 bytes). The limit applies to the whole message, including the protocol header; for a compressed message, it also applies to the decompressed size. If not defined, the adapter uses the communicator's Ice.MessageSizeMax limit.

A value of 0 or less selects the maximum supported size of 2,147,483,647 bytes. A positive value must be at most 2,097,151 KiB.

This property is logically a connection property, and only applies to messages received over network connections created by this object adapter.

adapter.AdapterId=id

Assigns an adapter ID to this object adapter. An object adapter with an adapter ID is called an indirect adapter.

This ID must be unique among all object adapters using the same locator instance. If a locator proxy is defined using adapter.Locator or Ice.Default.Locator, this object adapter registers its endpoints with the locator registry upon activation.

adapter.AllowedOrigins=originList

Restricts which HTTP Origin headers are accepted on the WebSocket upgrade request received by this object adapter. This property has effect only for adapters with WebSocket endpoints (ws or wss).

originList is a comma or whitespace-separated list of origins. Each entry has the form scheme://host[:port], where scheme is http or https and host is a DNS name or IP address. The scheme and host are compared case-insensitively; the default port for the scheme (80 for http, 443 for https) is omitted during comparison, so https://web.example.com and https://web.example.com:443 match the same origin.

The default value (empty) disables the check. A * entry also disables it, whatever the other entries are. Ice reads this property when creating an adapter with WebSocket endpoints.

When the check is enabled, Ice checks each incoming WebSocket upgrade request as follows:

If the request has no Origin header, the upgrade is accepted. Browsers always send Origin; non-browser Ice clients do not, so the check only filters browser-originated traffic. If the request has an Origin header that canonicalizes to an entry in the list, the upgrade is accepted. An unlisted or malformed origin causes Ice to reject the upgrade and close the connection.

This property is intended to mitigate cross-site WebSocket hijacking against browser-based Ice clients (Ice for JavaScript).

Properties
MyAdapter.Endpoints=wss -h api.example.com -p 443
MyAdapter.AllowedOrigins=https://web.example.com, https://admin.example.com

adapter.Connection.CloseTimeout=num (in seconds)

Overrides the setting of Ice.Connection.Server.CloseTimeout for this object adapter.

adapter.Connection.ConnectTimeout=num (in seconds)

Overrides the setting of Ice.Connection.Server.ConnectTimeout for this object adapter.

adapter.Connection.EnableIdleCheck=num

Overrides the setting of Ice.Connection.Server.EnableIdleCheck for this object adapter.

adapter.Connection.IdleTimeout=num (in seconds)

Overrides the setting of Ice.Connection.Server.IdleTimeout for this object adapter.

adapter.Connection.InactivityTimeout=num (in seconds)

Overrides the setting of Ice.Connection.Server.InactivityTimeout for this object adapter.

adapter.Connection.MaxDispatches=num

Overrides the setting of Ice.Connection.Server.MaxDispatches for this object adapter.

adapter.Endpoints=endpoints

Sets the physical endpoints of this object adapter. These endpoints correspond to the network interfaces on which the object adapter accepts connections and receives requests.

adapter.Locator=locator

Specifies the locator of this object adapter. The value is a stringified proxy to an Ice::Locator object.

As a proxy property, you can configure additional aspects of the proxy using properties.

adapter.MaxConnections=num

When num is greater than 0, Ice limits the number of incoming connections separately for each listening endpoint of this object adapter. Once an endpoint reaches the limit, Ice accepts and immediately closes additional connections to that endpoint until an existing connection closes. UDP endpoints are exempt from this limit.

The default value is 0. A value of 0 or less disables the limit.

adapter.MessageSizeMax=num (in KiB)

Limits the size of the Ice protocol messages this adapter receives, in KiB (1024 bytes). The limit applies to the whole message, including the protocol header; for a compressed message, it also applies to the decompressed size. If not defined, the adapter uses the communicator's Ice.MessageSizeMax limit.

A value of 0 or less selects the maximum supported size of 2,147,483,647 bytes. A positive value must be at most 2,097,151 KiB.

This property is logically a connection property, and only applies to messages received over network connections created by this object adapter.

adapter.ProxyOptions=options

Specifies the proxy options for proxies created by the object adapter. The value is a string representing the proxy options as they would be specified in a stringified proxy. The default value is -t, which creates twoway proxies.

adapter.PublishedEndpoints=endpoints

The published endpoints of an object adapter can be set using adapter.PublishedEndpoints. The exact algorithm is described in Published Object Adapter Endpoints.

adapter.PublishedHost=host

Specifies the published host for this object adapter. A published host is usually a DNS name, but it can also be an IP address.

The published host is used by the algorithm that computes the published endpoints of an object adapter, when adapter.PublishedEndpoints is not set. See Published Object Adapter Endpoints. This property is particularly useful when the object adapter endpoints do not specify port numbers.

adapter.ReplicaGroupId=id

Identifies the group of replicated object adapters to which this adapter belongs. The replica group is treated as a virtual object adapter, so that an indirect proxy of the form identity@id refers to the object adapters in the group. During binding, a client will attempt to establish a connection to an endpoint of one of the participating object adapters, and automatically try others until a connection is successfully established or all attempts have failed. Similarly, an outstanding request will, when permitted, automatically fail over to another object adapter of the replica group upon connection failure. The set of endpoints actually used by the client during binding is determined by the locator's configuration policies.

Defining a value for this property has no effect unless adapter.AdapterId is also defined. Furthermore, the locator registry may require replica groups to be defined in advance (see IceGrid.Registry.DynamicRegistration), otherwise Ice.NotRegisteredException is thrown upon adapter activation. Regardless of whether an object adapter is replicated, it can always be addressed individually in an indirect proxy if it defines a value for adapter.AdapterId.

adapter.PublishedHost=host

Specifies the published host for this object adapter. A published host is usually a DNS name, but it can also be an IP address.

The published host is used by the algorithm that computes the published endpoints of an object adapter, when adapter.PublishedEndpoints is not set. See Published Object Adapter Endpoints. This property is particularly useful when the object adapter endpoints do not specify port numbers.

adapter.ReplicaGroupId=id

Identifies the group of replicated object adapters to which this adapter belongs. The replica group is treated as a virtual object adapter, so that an indirect proxy of the form identity@id refers to the object adapters in the group. During binding, a client will attempt to establish a connection to an endpoint of one of the participating object adapters, and automatically try others until a connection is successfully established or all attempts have failed. Similarly, an outstanding request will, when permitted, automatically fail over to another object adapter of the replica group upon connection failure. The set of endpoints actually used by the client during binding is determined by the locator's configuration policies.

Defining a value for this property has no effect unless adapter.AdapterId is also defined. Furthermore, the locator registry may require replica groups to be defined in advance (see IceGrid.Registry.DynamicRegistration), otherwise Ice.NotRegisteredException is thrown upon adapter activation. Regardless of whether an object adapter is replicated, it can always be addressed individually in an indirect proxy if it defines a value for adapter.AdapterId.

adapter.Router=router

Specifies a router for this object adapter. The value is a stringified proxy to an Ice::Router object. Defining a router allows the object adapter to receive callbacks from the router over a bidirectional connection, thereby avoiding the need for the router to establish a connection back to the object adapter.

A router can only be assigned to one object adapter. The default value is no router.

An adapter with a router cannot also set adapter.Endpoints.

As a proxy property, you can configure additional aspects of the proxy using properties.

adapter.ThreadPool.Serialize=num

If num is a value greater than 0, the adapter's thread pool serializes all messages from each connection. It is not necessary to enable this feature in a thread pool whose maximum size is 1 thread. When a thread pool dispatches requests implemented with AMD, it serializes the dispatching of requests from each connection, but it does not wait for a request to complete before it dispatches the next request.

In a multi-threaded pool, enabling serialization allows requests from different connections to be dispatched concurrently while preserving the order of messages on each connection. Note that serialization can have a significant impact on latency and throughput. If not defined, the default value is 0.

adapter.ThreadPool.Size=num

A communicator creates a default server thread pool that dispatches requests to its object adapters. An object adapter can also be configured with its own thread pool. This is useful in avoiding deadlocks due to thread starvation by ensuring that a minimum number of threads is available for dispatching requests to certain Ice objects.

The adapter uses the communicator's server thread pool when no adapter.ThreadPool.* property is set. Setting any property with this prefix creates a dedicated pool. For example, setting only adapter.ThreadPool.SizeMax=4 creates a pool with one initial thread and a maximum of four threads.

num is the initial number of threads in the dedicated pool. Its default value is 1. See Ice.ThreadPool.name.Size for more information.

adapter.ThreadPool.SizeMax=num

num is the maximum number of threads for the thread pool. See Ice.ThreadPool.name.SizeMax for more information.

The default value is the value of adapter.ThreadPool.Size, meaning the thread pool can never grow larger than its initial size.

adapter.ThreadPool.SizeWarn=num

Whenever num threads are active in a thread pool, a "low on threads" warning is printed. The default value is 0, which disables the warning.

adapter.ThreadPool.ThreadIdleTime=num

In a dynamically-sized thread pool, Ice reaps a thread after it is idle for num seconds. Setting this property to 0 disables idle thread reaping. If not specified, the default value is 60 seconds. See Ice.ThreadPool.name.ThreadIdleTime for more information.

adapter.ThreadPool.Serialize=num

If num is a value greater than 0, the adapter's thread pool serializes all messages from each connection. It is not necessary to enable this feature in a thread pool whose maximum size is 1 thread. When a thread pool dispatches requests implemented with AMD, it serializes the dispatching of requests from each connection, but it does not wait for a request to complete before it dispatches the next request.

In a multi-threaded pool, enabling serialization allows requests from different connections to be dispatched concurrently while preserving the order of messages on each connection. Note that serialization can have a significant impact on latency and throughput. If not defined, the default value is 0.

adapter.ThreadPool.Size=num

A communicator creates a default server thread pool that dispatches requests to its object adapters. An object adapter can also be configured with its own thread pool. This is useful in avoiding deadlocks due to thread starvation by ensuring that a minimum number of threads is available for dispatching requests to certain Ice objects.

The adapter uses the communicator's server thread pool when no adapter.ThreadPool.* property is set. Setting any property with this prefix creates a dedicated pool. For example, setting only adapter.ThreadPool.SizeMax=4 creates a pool with one initial thread and a maximum of four threads.

num is the initial number of threads in the dedicated pool. Its default value is 1. See Ice.ThreadPool.name.Size for more information.

adapter.ThreadPool.SizeMax=num

num is the maximum number of threads for the thread pool. See Ice.ThreadPool.name.SizeMax for more information.

The default value is the value of adapter.ThreadPool.Size, meaning the thread pool can never grow larger than its initial size.

adapter.ThreadPool.SizeWarn=num

Whenever num threads are active in a thread pool, a "low on threads" warning is printed. The default value is 0, which disables the warning.

adapter.ThreadPool.StackSize=num

num is the stack size (in bytes) of threads in the thread pool. The default value is 0, meaning the operating system's default is used.

adapter.ThreadPool.ThreadIdleTime=num

In a dynamically-sized thread pool, Ice reaps a thread after it is idle for num seconds. Setting this property to 0 disables idle thread reaping. If not specified, the default value is 60 seconds. See Ice.ThreadPool.name.ThreadIdleTime for more information.

adapter.ThreadPool.ThreadPriority=value

value specifies a thread priority for the object adapter's thread pool. The object adapter creates its threads with the specified priority. Leaving this property unset causes the adapter to create threads with the priority specified by Ice.ThreadPriority.

value can be Lowest, BelowNormal, Normal, AboveNormal, or Highest.

The named values can also include the ThreadPriority. prefix, for example ThreadPriority.AboveNormal.

adapter.ThreadPool.Serialize=num

If num is a value greater than 0, the adapter's thread pool serializes all messages from each connection. It is not necessary to enable this feature in a thread pool whose maximum size is 1 thread. When a thread pool dispatches requests implemented with AMD, it serializes the dispatching of requests from each connection, but it does not wait for a request to complete before it dispatches the next request.

In a multi-threaded pool, enabling serialization allows requests from different connections to be dispatched concurrently while preserving the order of messages on each connection. Note that serialization can have a significant impact on latency and throughput. If not defined, the default value is 0.

adapter.ThreadPool.Size=num

A communicator creates a default server thread pool that dispatches requests to its object adapters. An object adapter can also be configured with its own thread pool. This is useful in avoiding deadlocks due to thread starvation by ensuring that a minimum number of threads is available for dispatching requests to certain Ice objects.

The adapter uses the communicator's server thread pool when no adapter.ThreadPool.* property is set. Setting any property with this prefix creates a dedicated pool. For example, setting only adapter.ThreadPool.SizeMax=4 creates a pool with one initial thread and a maximum of four threads.

num is the initial number of threads in the dedicated pool. Its default value is 1. See Ice.ThreadPool.name.Size for more information.

adapter.ThreadPool.SizeMax=num

num is the maximum number of threads for the thread pool. See Ice.ThreadPool.name.SizeMax for more information.

The default value is the value of adapter.ThreadPool.Size, meaning the thread pool can never grow larger than its initial size.

adapter.ThreadPool.SizeWarn=num

Whenever num threads are active in a thread pool, a "low on threads" warning is printed. The default value is 0, which disables the warning.

adapter.ThreadPool.StackSize=num

num is the stack size (in bytes) of threads in the thread pool. The default value is 0, meaning the operating system's default is used.

adapter.ThreadPool.ThreadIdleTime=num

In a dynamically-sized thread pool, Ice reaps a thread after it is idle for num seconds. Setting this property to 0 disables idle thread reaping. If not specified, the default value is 60 seconds. See Ice.ThreadPool.name.ThreadIdleTime for more information.

adapter.ThreadPool.ThreadPriority=value

value specifies a thread priority for the object adapter's thread pool. The object adapter creates its threads with the specified priority. Leaving this property unset causes the adapter to create threads with the priority specified by Ice.ThreadPriority.

value can be MIN_PRIORITY, NORM_PRIORITY, MAX_PRIORITY, or an integer between 1 and 10.

The named values can also include the java.lang.Thread. prefix, for example java.lang.Thread.NORM_PRIORITY.