=encoding utf8

=head1 NAME

Rosetta::Features - What RNI features a Rosetta Engine can possibly
implement

=head1 DESCRIPTION

For reference and context, please see the FEATURE SUPPORT VALIDATION
documentation section in the core "Rosetta" module.

This documentation file, Rosetta::Features, shows all of the individual
Rosetta Native Interface (RNI) features that a Rosetta Engine can possibly
implement; all of them are technically optional, though the Engine would be
useless without support for a basic subset.  Most of the level-2 headings
correspond exactly to the spelling of a single FEATURE_NAME that features()
can work with. An Engine declares its support for each feature on a yes/no
basis; the features should be finely grained enough that each can be
supported either in full or not at all.

Considering that support for some features is dependant on support for
other features (eg: SELECT support requires OPEN support), and such
dependencies are usually hierarchical, the description for each RNI feature
will say what other RNI features it is directly dependent on.  Any
dependant features are assumed to be not supported if a feature they depend
on is not supported.  For simplicity, only direct dependencies shown here.

Note that implementation of a supported RNI feature does not depend on
native database product support for it.  The support can be provided by
either the database product or the Rosetta Engine interfacing to it or
both.  All that matters is that it appears to the user like the database
product supports it. Interpret any "the Engine" as meaning "the Engine and
database product".

I<THE LISTS BELOW ARE NOT YET COMPLETE, AND MOST OF THE FEATURES THAT WILL
BE POSSIBLE AREN'T LISTED YET.  THEY WILL BE ADDED OVER TIME.>

=head1 FEATURES FOR DATABASE CATALOGS

=head2 CATALOG_LIST

The Engine can automatically detect existing instances of database catalogs
that are available to be opened.  The means by which these databases are
detected, as well as the scope of possible locations where they may reside,
is implementation-specific to the Engine.  (For example, the databases may
broadcast their presence as a network service using such protocols as
Zeroconf or perhaps ODBC.  Or, they may be a listening network service or
local server process such as ODBC or SQL*Net.  Or, they may be a local
embedded or disk file based solution.)  This feature has no RNI feature
dependencies.

=head2 CATALOG_INFO

The Engine can gather some basic information about a single specified
database catalog instance.  This feature has no RNI feature dependencies.

=head1 FEATURES FOR CONNECTIONS AND TRANSACTIONS

=head2 CONN_BASIC

The Engine can open at least one new connection or line of two-way
communication to a single specified database instance.  Also, the Engine
can close any database connection that it previously opened.  If the Engine
also supports transactions, then a newly opened database connection will
also represent a single active transaction context (more may possibly be
added later).  When a transaction-supporting database connection is closed,
then any incomplete transactions on it will be immediately rolled back
(explicit commits prior to this must be made to preserve any database
changes); this assumes that any relevant processes (Perl and/or the
database and/or intermediaries) have not been killed or crashed or suffered
hardware or power or network failure; on such a process death or network
failure, the default database recovery behaviour will occur, that may be
different; if there is no such death, then a rollback is guaranteed.  This
feature has no RNI feature dependencies.

=head2 CONN_MULTI_SAME

The Engine can open at least one new and independent connection to a
database instance while it simultaneously already has one or more open
connections to the same database instance.  The use of any open connection
will not interfere with any of the other connections, except that blocking
due to resource contention (such as write locks or transactions) is okay. 
Also, the Engine can close any of these independent connections without
affecting the other ones. This RNI feature depends on: CONN_BASIC.

=head2 CONN_MULTI_DIFF

The Engine can open at least one new connection to a database instance
while it simultaneously already has one or more open connections to
different database instances.  The use of or closing of any connection will
not interfere with any of the other connections.  This RNI feature depends
on: CONN_BASIC.

=head2 CONN_PING

The Engine can test whether a database connection that it expects to be
still open (because it wasn't explicitly closed) is in fact still open; the
service is still responsive.  This RNI feature depends on: CONN_BASIC.

=head2 TRAN_BASIC

The Engine has full basic support for transactions, which allows for
accumulations of multiple otherwise separate actions against the database
to be atomic.  Consecutive transactions are separated by a commit or
roll-back action; said action will end one transaction and start another. 
A commit will preserve the just-ended action set, and a roll-back will
discard it.  When an Engine supports transactions, they will always be
used; Rosetta intentionally does not support the concept of "auto commit
mode" for transaction-supporting databases (perform explicit commits where
you want them); "auto commit" only happens when a database doesn't support
transactions anyway.  Basic transaction support means that at least one
independent transaction can operate at a time on each open database
connection; support for multiple parallel transactions within one
connection, whether nested or not, is not implied to be supported; neither
is support for a certain transaction recovery behaviour on process death. 
This RNI feature depends on: CONN_BASIC.

=head2 TRAN_ROLLBACK_ON_DEATH

The actual data storage product in use by this Engine will roll back any
incomplete transactions during the recovery process following either the
death (from any means such as power failure or hardware fault or killed or
crashed process) of the data storage product itself or a prematurely
severed connection from the Rosetta Engine (such as a killed or crashed
Perl program, or network failure).  This feature is intrinsic to the data
storage product itself, and the Rosetta Engine can't do anything about it. 
This feature is separate from or additional to a prerequisite feature
behaviour (CONN_BASIC) that guarantees a roll back on disconnection when
there is no process death or network failure. If the data storage product's
current or only possible behaviour is to commit incomplete transactions
following a severed connection or during crash recovery, then
TRAN_ROLLBACK_ON_DEATH is explicitly *not* supported (and I also personally
recommend against said product for use in critical systems).  This RNI
feature depends on: TRAN_BASIC.

=head2 TRAN_MULTI_SIB

The Engine can support multiple lightweight connections or transaction
contexts which operate over a single actual connection to a database.  The
database actions performed on each lightweight connection are completely
isolated from any others, and commit or roll-back actions only affect one
transaction context at once.  The closure of a lightweight connection will
roll-back actions made on it, and not affect other transaction contexts. 
For all intents and purposes, each lightweight connection behaves
identically to a normal connection, except they use fewer resources and
don't require their own authentications.  This RNI feature depends on:
TRAN_BASIC.

=head2 TRAN_MULTI_CHILD

The Engine can support multiple nested (and possibly parallel ?)
transactions where one transaction is started by another and the child
transaction's actions can commit or roll-back independently from the parent
transaction.  Useful when you want a sub-action to commit even if the main
action doesn't.  This RNI feature depends on: TRAN_BASIC.

=head1 FEATURES FOR USERS AND SCHEMAS

=head2 USER_LIST

The Engine can automatically detect all (or some) existing users or
authorization identifiers present in or associated with a database catalog
instance.  Each user may possibly be used to authorize a connection to the
database catalog, or it may own one or more schema in the database catalog,
or it may have other statuses.  This RNI feature depends on: CONN_BASIC.

=head2 USER_INFO

The Engine can gather some basic information about a single specified
database user.  This RNI feature depends on: CONN_BASIC.

=head2 SCHEMA_LIST

The Engine can automatically detect all (or some) existing schemas or
name-spaces present in a database catalog instance, each of which may or
may not contain any schema objects.  This RNI feature depends on:
CONN_BASIC.

=head2 SCHEMA_INFO

The Engine can gather some basic information about a single specified
database schema.  This RNI feature depends on: CONN_BASIC.

=head1 FEATURES FOR DOMAIN SCHEMA OBJECTS

=head2 DOMAIN_LIST

The Engine can automatically detect all existing domain schema objects that
exist within a specified database schema.  This RNI feature depends on:
CONN_BASIC.

=head2 DOMAIN_INFO

The Engine can gather some basic information about a single specified
domain schema object.  This RNI feature depends on: CONN_BASIC.

=head2 DOMAIN_DEFN_VERIFY

The Engine can take a complete specification of a single specified domain
schema object, which is supposed to exist within a certain database schema,
and it will validate that not only does the object exist where it should,
but that all of the object's details match the given specification.  This
RNI feature depends on: CONN_BASIC.

=head2 DOMAIN_DEFN_BASIC

The Engine can take a complete specification of a single specified domain
schema object, and it can both create the object within a schema and delete
the object from the schema.  Support for updating or altering the
definition of a domain in place is not implied (a delete+create may be
required for alterations).  This RNI feature depends on: CONN_BASIC.

=head1 FEATURES FOR TABLE SCHEMA OBJECTS

=head2 TABLE_LIST

The Engine can automatically detect all existing table schema objects that
exist within a specified database schema.  This RNI feature depends on:
CONN_BASIC.

=head2 TABLE_INFO

The Engine can gather some basic information about a single specified table
schema object.  This RNI feature depends on: CONN_BASIC, DOMAIN_INFO.

=head2 TABLE_DEFN_VERIFY

The Engine can take a complete specification of a single specified table
schema object, which is supposed to exist within a certain database schema,
and it will validate that not only does the object exist where it should,
but that all of the object's details match the given specification.  This
RNI feature depends on: CONN_BASIC, DOMAIN_DEFN_VERIFY.

=head2 TABLE_DEFN_BASIC

The Engine can take a complete specification of a single specified table
schema object, and it can both create the object within a schema and delete
the object from the schema.  Basic table definition support means that a
table can be created that has multiple columns, each of which has a
domain-defined data type and enforces that data stored in the column is
valid for the domain; it also means that required-value or not-null
constraints for each column can be defined and enforced; support for any
other kind of data constraint, such as unique or primary key or foreign
key, or "check", is not implied to be supported; support for non-constraint
indexes, including full-text indexes, is not implied; support for triggers
is also not implied; support for updating or altering the definition of a
table or its columns or constraints in place is not implied (a
delete+create may be required for alterations).  This RNI feature depends
on: CONN_BASIC, DOMAIN_DEFN_BASIC.

=head2 TABLE_UKEY_BASIC

The Engine can create a table schema object which includes unique and
primary key constraints where each constraint encompasses exactly one table
column; support for multiple column keys is not implied.  Any definable
unique key constraints are enforced.  (The primary key of a table is
defined to be the first unique key definition whose columns all have
required-value constraints; if none do, then there is no primary key.) 
This RNI feature depends on: TABLE_DEFN_BASIC.

=head2 TABLE_UKEY_MULTI

The Engine can create a table schema object which includes unique and
primary key constraints where each constraint encompasses any number of
table columns, one or greater.  This RNI feature depends on:
TABLE_UKEY_BASIC.

=head2 TABLE_FKEY_BASIC

The Engine can create a table schema object which includes foreign key
constraints where each constraint encompasses exactly one table column (in
the table being constrained); support for multiple column keys is not
implied.  Any definable foreign key constraints are enforced.  This RNI
feature depends on: TABLE_DEFN_BASIC.

=head2 TABLE_FKEY_MULTI

The Engine can create a table schema object which includes foreign key
constraints where each constraint encompasses any number of table columns,
one or greater.  This RNI feature depends on: TABLE_FKEY_BASIC.

=head1 FEATURES FOR RECORD SELECTION QUERIES

=head2 QUERY_BASIC

The Engine can query exactly one database table schema object and can
return all columns of all rows in that table from a single request.  The
returned rows and columns may be returned in an apparently random order,
but the column name or sequence within each row must be the same for every
row.  The means by which all of the rows are returned, such that it is
accomplished within practical resource usage limits, is
implementation-specific to the Engine.  (For example, the rows may actually
be retrieved just one at a time to conserve local memory, or all at once to
conserve database service resources.)  Basic query support is indeed
extremely basic, and it does not imply support for anything more
intelligent than the action "SELECT * FROM <table-name>"; there is no
implied support for limiting columns or rows, or grouping, or sorting, or
any kind of join, or for querying view schema objects, or for any kind of
compound queries, or sub-queries, or invoking any kind of function or
predicate.  This RNI feature depends on: CONN_BASIC.

=head2 QUERY_SCHEMA_VIEW

The Engine can query exactly one database view ("viewed table") schema
object and can return all columns of all rows in that view ("viewed table")
from a single request.  This feature does not imply support for anything
more intelligent than the action "SELECT * FROM <view-name>".  This RNI
feature depends on: QUERY_BASIC.

I<Note that for all subsequent QUERY_* RNI feature descriptions, the term
"table" means "table schema object or view schema object".>

=head2 QUERY_RETURN_SPEC_COLS

The Engine can query exactly one database table and return just a specified
set of table columns, in the order specified, where each returned column
corresponds exactly to one table column, and has the same name.  This
feature does not imply support for either specifying different names for
the returned columns, or for returning the result of an arbitrary value
expression for the column; it also does not imply support for anything
other than "SELECT <col-list> FROM <table-name>" where <col-list> means
"<col-name>[,<col_name>]{1,}".  This RNI feature depends on: QUERY_BASIC.

=head2 QUERY_RETURN_COL_EXPRS

The Engine can take a query that returns a specified set of columns where
each column name is specified and each column value comes from an arbitrary
multi-level nested value expression.  At the very least, each column value
can either be equal to a database table column value, or it can be equal to
a specified literal value.  In addition, this feature gives support for
queries that do not use any database tables at all (and always return
exactly one row), such as "SELECT 'x' AS foo".  This feature does not imply
support for any other kinds of sub-expressions or predicates or functions
that might otherwise be used in a value expression.  This RNI feature
depends on: QUERY_RETURN_SPEC_COLS.

=head2 QUERY_WHERE

The Engine can take a query that contains a simple WHERE search expression
for limiting what rows are returned by the query.  At the very least, this
search expression can contain multiple levels of nested sub-expressions,
where each sub-expression is either a boolean value expression (NOT, AND,
OR, XOR), or a comparison predicate (EQ, NE, LT, GT, LE, GE), or a required
value predicate (IS NOT NULL, IS NULL), or a database table column value,
or a specified literal value.  This feature does not imply support for any
other kinds of sub-expressions or predicates (including LIKE) or functions
that might otherwise be used in a value expression.  This RNI feature
depends on: QUERY_BASIC.

=head2 QUERY_COMPARE_PRED

The Engine can take a query that contains comparison predicates or required
value predicates in places outside of search expressions, such as in the
returned column value expressions.  This RNI feature depends on:
QUERY_BASIC.

=head2 QUERY_BOOLEAN_EXPR

The Engine can take a query that contains boolean value expressions in
places outside of search expressions, such as in the returned column value
expressions.  This RNI feature depends on: QUERY_BASIC.

=head2 QUERY_NUMERIC_EXPR

The Engine can take a query that contains numeric value expressions (ADD,
SUB, MUL, DIV, DIVI, MOD, ROUND, ABS, POWER, LOG).  This RNI feature
depends on: QUERY_BASIC.

=head2 QUERY_STRING_EXPR

The Engine can take a query that contains string value expressions
(SCONCAT, SLENGTH, SINDEX, SUBSTR, SREPEAT, STRIM, SPAD, SPADL, LC, UC). 
This RNI feature depends on: QUERY_BASIC.

=head2 QUERY_LIKE_PRED

The Engine can take a query that contains the LIKE predicate.  This RNI
feature depends on: QUERY_BASIC.

=head2 QUERY_JOIN_BASIC

This Engine can query more than one database table, with the tables being
joined together by the query.  This feature supports cross joins and inner
joins only; this feature does not imply support for any kind of outer join.
This RNI feature depends on: QUERY_RETURN_COL_EXPRS.

=head2 QUERY_JOIN_OUTER_LEFT

This Engine can take a query that contains one or more left outer join, in
addition to cross joins and inner joins.  This RNI feature depends on:
QUERY_JOIN_BASIC.

=head2 QUERY_JOIN_ALL

This Engine can take a query that contains any kind of join (CROSS, INNER,
LEFT|RIGHT|FULL OUTER).  This RNI feature depends on:
QUERY_JOIN_OUTER_LEFT.

=head2 QUERY_GROUP_BY_NONE

The Engine can take a query that contains the basic aggregate functions in
the returned column value expression and has no GROUP BY expressions; the
use of this results in exactly one row being returned, as we have
conceptually "grouped by nothing".  This RNI feature depends on:
QUERY_RETURN_COL_EXPRS.

=head2 QUERY_GROUP_BY_SOME

The Engine can take a query that contains one or more simple GROUP BY
expressions for controlling the aggregation of returned rows by related
column values.  This feature also includes support for the use of basic
aggregate functions (COUNT, MIN, MAX, SUM, AVG) in other appropriate parts
of the query, such as the returned column value expressions.  This feature
does not imply support for either existence predicates or OLAP extensions. 
This RNI feature depends on: QUERY_GROUP_BY_NONE.

=head2 QUERY_AGG_CONCAT

The Engine can take a query that contains the CONCAT aggregate function. 
This RNI feature depends on: QUERY_GROUP_BY_NONE.

=head2 QUERY_AGG_EXIST

The Engine can take a query that contains the existence aggregate
predicates (EVERY, ANY, SOME, EXISTS).  This RNI feature depends on:
QUERY_GROUP_BY_NONE.

=head2 QUERY_OLAP

The Engine can take a query that uses the various OLAP extensions (GB_SETS,
GB_RLUP, GB_CUBE).  This RNI feature depends on: QUERY_GROUP_BY_SOME.

=head2 QUERY_HAVING

The Engine can take a query that contains a simple HAVING search expression
for limiting what rows are returned by an aggregated query.  At the very
least, this search expression can contain anything a WHERE search
expression can contain, plus the basic aggregate functions.  This RNI
feature depends on: QUERY_GROUP_BY_SOME.

=head2 QUERY_WINDOW_ORDER

The Engine can take a query that contains one or more simple ORDER BY
expressions for controlling the sequence of returned rows.  This RNI
feature depends on: QUERY_RETURN_SPEC_COLS.

=head2 QUERY_WINDOW_LIMIT

The Engine can take a query that contains a low intelligence LIMIT clause
for reducing how many rows are returned to a specified number N (either to
the "first" N rows, or another specified number can be skipped first). 
This RNI feature depends on: QUERY_BASIC.

=head2 QUERY_COMPOUND

The Engine can take a compound query, which is composed of several
otherwise separate queries connected by a compound operator (UNION,
DIFFERENCE, INTERSECTION, EXCLUSION).  This RNI feature depends on:
QUERY_RETURN_COL_EXPRS.

=head2 QUERY_SUBQUERY

The Engine can take queries that contain sub-queries.  This RNI feature
depends on: QUERY_RETURN_COL_EXPRS.

=head1 SEE ALSO

L<Rosetta> and the various other modules mentioned in its SEE ALSO.

=head1 AUTHOR

Darren R. Duncan (C<perl@DarrenDuncan.net>)

=head1 LICENCE AND COPYRIGHT

This file is part of the Rosetta database portability library.

Rosetta is Copyright (c) 2002-2005, Darren R. Duncan.  All rights reserved.
Address comments, suggestions, and bug reports to C<perl@DarrenDuncan.net>,
or visit L<http://www.DarrenDuncan.net/> for more information.

Rosetta is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License (GPL) as published by the Free
Software Foundation (L<http://www.fsf.org/>); either version 2 of the
License, or (at your option) any later version.  You should have received a
copy of the GPL as part of the Rosetta distribution, in the file named
"GPL"; if not, write to the Free Software Foundation, Inc., 51 Franklin St,
Fifth Floor, Boston, MA  02110-1301, USA.

Linking Rosetta statically or dynamically with other modules is making a
combined work based on Rosetta.  Thus, the terms and conditions of the GPL
cover the whole combination.  As a special exception, the copyright holders
of Rosetta give you permission to link Rosetta with independent modules,
regardless of the license terms of these independent modules, and to copy
and distribute the resulting combined work under terms of your choice,
provided that every copy of the combined work is accompanied by a complete
copy of the source code of Rosetta (the version of Rosetta used to produce
the combined work), being distributed under the terms of the GPL plus this
exception.  An independent module is a module which is not derived from or
based on Rosetta, and which is fully useable when not linked to Rosetta in
any form.

Any versions of Rosetta that you modify and distribute must carry prominent
notices stating that you changed the files and the date of any changes, in
addition to preserving this original copyright notice and other credits.
Rosetta is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.

While it is by no means required, the copyright holders of Rosetta would
appreciate being informed any time you create a modified version of Rosetta
that you are willing to distribute, because that is a practical way of
suggesting improvements to the standard version.

=cut
