Object Adapter Endpoints
An object adapter maintains two sets of endpoints. One set identifies the network interfaces on which the adapter listens for new connections, and the other set is embedded in proxies created by the adapter and used by clients to communicate with it. We will refer to these sets of endpoints as the physical endpoints and the published endpoints, respectively.
Physical Object Adapter Endpoints
An object adapter's physical endpoints identify the network interfaces on which it receives requests from clients. These endpoints are configured via the name.Endpoints property, or they can be specified explicitly when creating an adapter using the operation createObjectAdapterWithEndpoints. The endpoint syntax generally consists of a transport protocol followed by an optional host name and port.
Despite the name of the property and the name of the method, we recommend you always configure your object adapter with a single endpoint. Specifying multiple endpoints, while possible, does not provide any real benefit.
If a host name is specified, the object adapter listens only on the network interface associated with that host name. If no host name is specified but the property Ice.Default.Host is defined, the object adapter uses the property's value as the host name. Finally, if a host name is not specified, and the property Ice.Default.Host is undefined, the object adapter listens on all available network interfaces, including the loopback interface. You may also force the object adapter to listen on all interfaces by using one of the host names 0.0.0.0 or *. The adapter does not expand the list of interfaces when it is initialized. Instead, if no host is specified, or you use -h * or -h "::0", the adapter binds to INADDR_ANY to listen for incoming requests.
If the host name refers to a DNS name which is configured with multiple addresses, the object adapter will listen on the network interfaces identified by each address. All the addresses should refer to local network interfaces or the object adapter creation will fail.
You should not use DNS names for your object adapter endpoint(s). This DNS support is only provided for backwards compatibility with previous versions of Ice.
If you want an adapter to accept requests on certain network interfaces, you must specify a separate endpoint for each interface. For example, the following property configures a single endpoint for the adapter named MyAdapter:
MyAdapter.Endpoints=tcp -h 10.0.1.1 -p 9999This endpoint causes the adapter to accept requests on the network interface associated with the IP address 10.0.1.1 at port 9999. Note however that this adapter configuration does not accept requests on the loopback interface (the one associated with address 127.0.0.1). If both addresses must be supported, then both must be specified explicitly, as shown below:
# An adapter with multiple endpoints (not recommended)
MyAdapter.Endpoints=tcp -h 10.0.1.1 -p 9999:tcp -h 127.0.0.1 -p 9999If these are the only two network interfaces available on the host, then a simpler configuration omits the host name altogether, causing the object adapter to listen on both interfaces automatically:
MyAdapter.Endpoints=tcp -p 9999If you want to make your configuration more explicit, you can use one of the special host names mentioned earlier:
MyAdapter.Endpoints=tcp -h * -p 9999Careful consideration must also be given to the selection of a port for an endpoint. If no port is specified, the adapter uses a port that is selected (essentially at random) by the operating system, meaning the adapter will likely be using a different port each time the server is restarted. Whether that behavior is desirable depends on the application, but in many applications a client has a proxy containing the adapter's endpoint and expects that proxy to remain valid indefinitely. Therefore, an endpoint generally should contain a fixed port to ensure that the adapter is always listening at the same port.
However, there are certain situations where a fixed port is not required. For example, an adapter whose servants are transient does not need a fixed port, because the proxies for those objects are not expected to remain valid past the lifetime of the server process. Similarly, a server using indirect binding via IceGrid does not need a fixed port because its port is never published.
Published Object Adapter Endpoints
When an object adapter creates a proxy, it embeds its published endpoints in this proxy.
The published endpoints of an object adapter matter only if you create proxies with this object adapter and then transmit these proxies to other applications.
Most of the time, the published endpoints consist of a single published endpoint. Multiple published endpoints are useful for replicated servers, as presented below.
The published endpoints of a regular object adapter (that is, not configured with a router) are computed as follows:
If the property adapter.PublishedEndpoints is set, use the specified endpoints.
start from the physical endpoints, split these endpoints in loopback and multicast endpoints on one side, and regular endpoints on the other
if there is any regular endpoint:
discard the loopback and multicast endpoints
replace the host name in each of these endpoints by the value of adapter.PublishedHost. If
adapter.PublishedHostis not set, use the DNS name of the current host as published host.
otherwise, when all endpoints are loopback or multicast, replace the host name in each of these endpoints by the value of
adapter.PublishedHost, if set. Don’t perform any substitution ifadapter.PublishedHostis not set.finally, eliminate duplicate endpoints
Your physical endpoint(s) should be simple: a single endpoint that is loopback, multicast, or neither loopback nor multicast (typically, INADDR_ANY).
The published endpoints computation accepts odd mixes of endpoints only to maximize compatibility for existing applications.
As an example, the published endpoints for an object adapter with the following configuration:
MyAdapter.Endpoints=tcp -h 10.0.1.1 -p 9999
MyAdapter.PublishedHost=Sun1are tcp -h Sun1 -p 9999.
You can also configure PublishedEndpoints explicitly:
MyAdapter.Endpoints=tcp -h 10.0.1.1 -p 9999
MyAdapter.PublishedEndpoints=tcp -h corpfw -p 25000This example assumes that clients connecting to host corpfw at port 25000 are forwarded to the adapter's endpoint in the private network.
Another use case of published endpoints is for replicated servers. Suppose we have two instances of a stateless server running on separate hosts in order to distribute the load between them. We can supply the client with a bootstrap proxy containing the endpoints of both servers, and the Ice runtime in the client will select one of the servers at random when a connection is established. However, should the client invoke an operation on a server that returns a proxy for another object, that proxy would normally contain only the endpoint of the server that created it. Invocations on the new proxy would always be directed at the same server, reducing the opportunity for load balancing.
We can alleviate this situation by configuring the adapters to publish the endpoints of both servers. For example, here is a configuration for the server on host Sun1:
MyAdapter.Endpoints=tcp -h 10.0.0.1 -p 9999
MyAdapter.PublishedEndpoints=tcp -h Sun1 -p 9999:tcp -h Sun2 -p 9999Similarly, the configuration for host Sun2 retains the same published endpoints:
MyAdapter.Endpoints=tcp -h 10.0.0.2 -p 9999
MyAdapter.PublishedEndpoints=tcp -h Sun1 -p 9999:tcp -h Sun2 -p 9999A Router's Effect on Object Adapter Endpoints
If an object adapter is configured with a router, the adapter's published endpoints are those provided by the router's server proxy. Calling setPublishedEndpoints on such an object adapter will throw an illegal argument exception. See Routers for additional information.