net.ertp
Interface Assay

public interface Assay

Untamed:

Method Summary

double	compareTo(Assay other) Enabled: Return -1.0, 0.0, 1.0, or NaN as the erights represented by this Assay is a strict subset, interchangeable with, a strict superset, or incomparable with the erights of other.
Issuer	getIssuer() Enabled: The Issuer that "stands behind" this Assay.
void	transfer(Purse src, Purse dest) Enabled: If src and dest are both of this Issuer and src contains adequate erights to fund the transfer, transfer the erights described by this Assay into dest.

Method Detail

getIssuer

public Issuer getIssuer()

Enabled: The Issuer that "stands behind" this Assay.

The returned Issuer must be one that will vouch for this Assay. Typically, this will be the Issuer that issued this Assay.

transfer

public void transfer(Purse src,
                     Purse dest)
              throws UnsealingException,
                     InsufficientERightsException

Enabled: If src and dest are both of this Issuer and src contains adequate erights to fund the transfer, transfer the erights described by this Assay into dest.

Given a 'src' Purse acceptable to this Issuer that's alleged to have at least the erights described by this Assay, and any 'dest' Purse acceptable to this Issuer, the Assay checks that all of these conditions are met, and if so, ideally transfer the erights it describes from 'src' to 'dest'. Otherwise, it throws an exception and ideally leaves the two Purses unaffected.

What does "acceptable to" above mean? At a minimum, the Purses issued by an Issuer must be acceptable to it (indeed, must be vouched-for by it). Base level Issuers of atomic erights will typically do nothing more. However, to enable "Market Translator" services (Nick, what's a good URL?), a virtual Assay (an Assay of a virtual Issuer) may accept 'src' Purses of other Issuers, extract erights and trade them on the market into the kind of erights this Assay represents, and trade these in turn for the kind of erights that can be deposited into 'dest'. Obviously, one will often be able to do this with one trade instead of two.

Why "ideally" above? A transfer attempt, whether successful or not, can involve some amount of friction. As a result, an unsuccessful transfer can still cause some loss to the src Purse, and a successful transfer can cause the src Purse to lose more than the amount transfered into the dest Purse. An individual Issuer should state what kinds of friction-losses its customers may be subject to. In all cases, a successful trasfer should increase the erights of dest by exactly the erights described by this Assay (subject to Market Translator interpretation) and an unsuccessful transfer should leave dest unaffected. All friction-losses are born only by src.

Throws:

UnsealingException - Thrown if src or dest isn't acceptable to the same Issuer as this Assay.

InsufficientERightsException - Thrown if src doesn't contain adequate erights to fund the transfer.

compareTo

public double compareTo(Assay other)
                 throws UnsealingException

Enabled: Return -1.0, 0.0, 1.0, or NaN as the erights represented by this Assay is a strict subset, interchangeable with, a strict superset, or incomparable with the erights of other.

The E comparison operators, <, <= <=>, >=, >, are syntactic shorthands that expand to calls to compareTo assuming the convention stated here. Therefore, you can use these operators directly on near Assay objects.

Throws:

UnsealingException - if other isn't issued by the same Issuer.