# 12 Connecting Computations: `Connection`

Oz uses a ticket-based mechanism to establish connections between independent Oz processes. One process (called server) creates a ticket with which other sites (called clients) can establish a connection.

A ticket is a character string which can be stored and transported through all media that can handle text, e.g., phone lines, electronic mail, paper, and so forth. Tickets are insecure, in that they can be forged. The following is an example ticket encoded as an Oz atom:

> `'oz-ticket://130.104.228.81:9000/h9323679#42'`

The ticket identifies both the server and the value to which a remote reference will be made. Independent connections can be made to different values on the same server. Once an initial connection is established by the value exchanged, then further connections as desired by applications can be built from programming abstractions, like object, classes, ports or procedures.

Two different types of connections and tickets are supported:

One-to-one connections and one-shot tickets.

  Allow to establish a single connection only.

Many-to-one connections and many-shot tickets.

  Allow multiple connections with the same ticket to the same value.

The module `Connection` provides procedures and classes that support both one-to-one and many-to-one connections.

## 12.1 One-to-one Connections

`offerOnce`, `offer`

  > `{Connection.offerOnce` `X``` `?TicketA``}`

  Returns the single-shot ticket `TicketA` (an atom) under which the value `X` is offered.

  The value `X` is exported immediately. An exception is raised, if exportation of `X` fails, because `X` refers to sited entities.

`take`

  > `{Connection.take` `+TicketV``` `?X``}`

  Returns the value `X` offered under the ticket `TicketV` (a virtual string).

  Waits until the connection to the offering process is established and the ticket has been acknowledged by that process.

  Raises an exception if the ticket is illegal, or if the offering process does not longer exist.

  Also works for many-shot tickets, where an exception might be raised if the same ticket is used more than once.

## 12.2 Many-to-one Connections

`offerMany`, `offerUnlimited`

  > `{Connection.offerMany` `X``` `?TicketA``}`

  offers the value `X` under the returned many-shot ticket `TicketA` (an atom).

  The value `X` is exported immediately. An exception is raised, if exportation of `X` fails, because `X` might refer to sited entities.

  The ticket remains valid until it is retracted, or the current Oz process terminates.

`retract`

  > `{Connection.retract` `+TicketA``}`

  retracts the ticket `TicketA` (an atom). The ticket is discarded, and any future attempt to take it will fail.

  A one-shot ticket is nothing more than a many-shot ticket that is automatically retracted once it is taken.

### 12.2.1 Gates

Values for many-to-one connections can also be offered through gates. Gates provide many-shot tickets with an object interface. Values offered through gates can be taken with `Connection.take` as described above.

Gates are provided as instances of the class `Connection.gate`. The methods of `Connection.gate` are as follows.

`init`

  > `init(``X``` `TicketA``<= _)`

  Optionally returns the many-shot ticket `TicketA` (an atom) under which the value `X` is offered.

  The value `X` is exported immediately. An exception is raised, if exportation of `X` fails, because `X` might refer to sited entities.

`getTicket`

  > `getTicket(``TicketA``)`

  Returns the many-shot ticket `TicketA` (an atom) of the gate.

`close`

  > `close()`

  Closes the gate, which makes further use of the associated ticket illegal.