Module com.darkcollective.relix.embed

Package com.darkcollective.relix.embed

package com.darkcollective.relix.embed

The Relix embedding API — what a plain Java program depends on to build, optimise, inspect and run a query.

Two types carry it. Relix is the session: the declarations a script would hold, together with the bindings that connect them outward — a live DataSource, a catalog, a clock. Relation is the value: an expression together with the analysis it resolves against. Operators are functions from relations to relations, and nothing executes until an execution terminal is called.

What this artifact promises

relix-embed is backward compatible within a major version. Code that compiles and runs against one release keeps compiling and running against every later release of the same major.

• Every public member records when it arrived, with @since. That is what makes the rest of this readable: a promise about when something may be removed says nothing without the release it appeared in.
• Nothing is removed without warning. A member on its way out is marked @Deprecated for at least one minor release, with the replacement named, and can only disappear at a major.
• The types this API hands back are part of it. A relation's schema is the engine's Schema, a row is its Row, an event its QueryEvent — deliberately, because a second Schema type would be a permanent tax on every caller. The consequence is that those engine types are under this promise too, and the set of them is fixed rather than left to grow quietly.

Both claims are checked on every build rather than remembered.

One artifact

Everything above ships in a single dependency, com.darkcollective.relix:relix: the engine, the default function library, the standard connectors and a solver. A program needs that and a JDBC driver.

The modules the engine is built from are not published separately. Their boundaries are enforced where they mean something — in the build that defines them — and were never a surface to write code against.

Class	Description
Diagnostic	One thing wrong with a query, as data rather than as an exception.
QueryExecutionException	Thrown when a query started and did not finish.
ReferencePage	One page of the language reference, as Relix.referencePages() lists it.
Relation	A relation — an expression together with the analysis it resolves against.
Relix	A Relix session — the environment relations resolve against, and the entry point to the embedding API.
Relix.Builder	Assembles a Relix session.
RelixException	Thrown when text will not parse, or a relation will not analyse against its session.
Rows	The result of one run — the rows, their heading, and what the engine did to produce them.
Sandbox	What a session lets its users reach, and how much work one query may do.
Sandbox.Builder	Assembles a closed sandbox.
SandboxViolationException	A closed Sandbox refused what a session was given: an external declaration the sandbox does not permit, or text longer than its input limit.
Token	A run of .relix text and what kind of token it is, as Relix.tokens(java.lang.String) reports it.
TokenKind	What a Token is, in the handful of categories a syntax highlighter colours.
Tuple	One row of a result, read as Java types.
UnboundedRelationException	Thrown when a terminal that must collect every row is asked for one that never ends.