Ice Reference Documentation
<<< Previous |  | Next >>>

# Proxies and Endpoints

# 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 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).

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 quotes can be used to prevent white space characters from being interpreted as delimiters, and to escape the special meaning of the backslash (`\`) character. Within single quotes, the only character that retains its special meaning is the single quote itself; a backslash can be used to prevent interpretation of a single quote as a closing quote, for example: `'a string with a \' quote'`.

Double quotes prevent interpretation of white space characters as delimiters and prevent interpretation of a single quote as an opening or closing quote. For example: `"a string with a ' quote"`. However, escape sequences such as `\b` are interpreted within 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`). A double quote 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 in Endpoints. 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, the endpoint list is randomized as a form of load balancing.

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`.

<<< Previous | Home | Next >>>
IcePatch2 Properties |  | Endpoints