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 character 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).
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:
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 1739. 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.EndpointSelection and
name.Endpoint.Selection properties in
Appendix C).
If the ‑s option is specified, only those endpoints that support secure invocations are considered during binding. If no valid endpoints are found, the application 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.
