NAME
Rosetta::Features - What RNI features a Rosetta Engine can possibly implement
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".
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.
FEATURES FOR DATABASE CATALOGS
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.
CATALOG_INFO
The Engine can gather some basic information about a single specified database catalog instance. This feature has no RNI feature dependencies.
FEATURES FOR CONNECTIONS AND TRANSACTIONS
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.
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.
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.
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.
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.
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.
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.
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.
FEATURES FOR USERS AND SCHEMAS
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.
USER_INFO
The Engine can gather some basic information about a single specified database user. This RNI feature depends on: CONN_BASIC.
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.
SCHEMA_INFO
The Engine can gather some basic information about a single specified database schema. This RNI feature depends on: CONN_BASIC.
FEATURES FOR DOMAIN SCHEMA OBJECTS
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.
DOMAIN_INFO
The Engine can gather some basic information about a single specified domain schema object. This RNI feature depends on: CONN_BASIC.
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.
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.
FEATURES FOR TABLE SCHEMA OBJECTS
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.
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.
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.
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.
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.
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.
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.
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.
FEATURES FOR RECORD SELECTION QUERIES
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.
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.
Note that for all subsequent QUERY_* RNI feature descriptions, the term "table" means "table schema object or view schema object".
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.
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.
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.
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.
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.
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.
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.
QUERY_LIKE_PRED
The Engine can take a query that contains the LIKE predicate. This RNI feature depends on: QUERY_BASIC.
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.
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.
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.
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.
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.
QUERY_AGG_CONCAT
The Engine can take a query that contains the CONCAT aggregate function. This RNI feature depends on: QUERY_GROUP_BY_NONE.
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.
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.
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.
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.
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.
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.
QUERY_SUBQUERY
The Engine can take queries that contain sub-queries. This RNI feature depends on: QUERY_RETURN_COL_EXPRS.
SEE ALSO
Rosetta and the various other modules mentioned in its SEE ALSO.
AUTHOR
Darren R. Duncan (perl@DarrenDuncan.net)
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 perl@DarrenDuncan.net, or visit 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 (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.