# 11 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 (albeit some luck is required, since they offer some security against typos). The following is an example ticket encoded as an Oz atom:

> `'x-ozticket://134.96.186.115:9000:egbj0:DS/v:s:kn'`

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. Values for many-to-one connections are offered through gates.

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

## 11.1 One-to-one Connections

`offer`

  > `{Connection.offer` `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.

## 11.2 Many-to-one Connections

Values for many-to-one connections can be offered through gates. Values offered through gates can be taken with `Connection.take` as described for one-to-one connections. Gates can be closed which implies that the associated ticket becomes invalid.

The special case and frequently occuring case that the gate never gets closed is supported by the procedure `Connection.offerUnlimited` which is as follows:

`offerUnlimited`

  > `{Connection.offerUnlimited` `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 the current Oz process terminates.

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.