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. 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 UTF8 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 path comprising one or more facets separated by a slash (`/`). If `facet` contains white space, it must be enclosed in single or double quotes. Each component of the facet path is a UTF8 string that uses the encoding described below. Any occurrence of a slash (`/`) in a facet path component must be escaped with a backslash (i.e., `\/`).

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

UTF8 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`). Quotation marks used to enclose a string 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