Appendix E 

Proxies and Endpoints

E.1 Proxies

Synopsis

identity ‑f facet ‑t ‑o ‑O ‑d ‑D ‑s @ adapter_id : endpoints

Description

A stringified proxy consists of an identity, proxy options, and an optional object adapter identifier or endpoint list. White space (the space, tab (\t), line feed (\n), and carriage return (\r) characters) act as token delimiters; if a white space char­acter appears as part of a component of a stringified proxy (such as the identity), it must be quoted or escaped as described below.

A proxy containing an identity with no endpoints, or an identity with an object adapter identifier, represents an indirect proxy that will be resolved using the Ice locator (see the Ice.Default.Locator property).

Proxy options configure the invocation mode:

‑f facet	Select a facet of the Ice object.
‑t	Configures the proxy for twoway invocations (default).
‑o	Configures the proxy for oneway invocations.
‑O	Configures the proxy for batch oneway invocations.
‑d	Configures the proxy for datagram invocations.
‑D	Configures the proxy for batch datagram invocations.
‑s	Configures the proxy for secure invocations.

The proxy options ‑t, ‑o, ‑O, ‑d, and ‑D are mutually exclusive.

The object identity identity is structured as [category/]name, where the category component and slash separator are optional. If identity contains white space or either of the characters : or @, it must be enclosed in single or double quotes. The category and name components are UTF‑8 strings that use the encoding described below. Any occurrence of a slash (/) in category or name must be escaped with a backslash (i.e., \/).

The facet argument of the ‑f option represents a facet name. If facet contains white space, it must be enclosed in single or double quotes. A facet name is a UTF‑8 string that uses the encoding described below.

The object adapter identifier adapter_id is a UTF‑8 string that uses the encoding described below. If adapter_id contains white space, it must be enclosed in single or double quotes.

Single or double quotes can be used to prevent white space characters from being interpreted as delimiters. Double quotes prevent interpretation of a single quote a as an opening or closing quote, for example:

"a string with a ' quote"

Single quotes prevent interpretation of a double quote as an opening or closing quote. For example:

'a string with a " quote'

Escape sequences such as \b are interpreted within single and double quotes.

UTF‑8 strings are encoded using ASCII characters for the ordinal range 32–126 (inclusive). Characters outside this range must be encoded using escape sequences (\b, \f, \n, \r, \t) or octal notation (e.g., \007). Single and double quotes can be escaped using a backslash, as can the backslash itself (\\).

If endpoints are specified, they must be separated with a colon (:) and formatted as described on page 1959. The order of endpoints in the stringified proxy is not necessarily the order in which connections are attempted during binding: when a stringified proxy is converted into a proxy instance, by default, the endpoint list is randomized as a form of load balancing. You can change this this default behavior by setting properties (see the Ice.Default.EndpointSe­lection and name.Endpoint.Selection properties in Appendix D).

If the ‑s option is specified, only those endpoints that support secure invoca­tions are considered during binding. If no valid endpoints are found, the applica­tion receives Ice::NoEndpointException.

Otherwise, if the ‑s option is not specified, the endpoint list is ordered so that non-secure endpoints have priority over secure endpoints during binding. In other words, connections are attempted on all non-secure endpoints before any secure endpoints are attempted.

If an unknown option is specified, or the stringified proxy is malformed, the application receives Ice::ProxyParseException. If an endpoint is malformed, the application receives Ice::EndpointParseException.